Appearance
Menús IVR entrantes
Generado desde
DialerDigital/corecommit0fc18008b3c8— especificaciónopenapi/dialer-v1.yamlv0.134.0. No se edita a mano; consulta Cómo se construye esta referencia. Descargar la especificación OpenAPI.
Traducción en curso
Esta referencia se genera desde la especificación OpenAPI. Las cadenas que todavía no tienen traducción aparecen en inglés.
Los menús IVR entrantes del tenant: versiones publicadas, historial de solo anexar, convertidos en audio al publicarse. Una ruta entrante con dest_type: ivr ejecuta uno de ellos.
Endpoints
| Método | Ruta | Resumen |
|---|---|---|
GET | /v1/inbound-ivr-menus | Los menús IVR entrantes vigentes del tenant |
POST | /v1/inbound-ivr-menus | Publicar un menú IVR entrante, o la siguiente versión de uno |
GET | /v1/inbound-ivr-menus/{id} | Un menú IVR entrante, su versión vigente y su historial |
POST | /v1/inbound-ivr-menus/{id}/retire | Retirar un menú IVR entrante |
Los menús IVR entrantes vigentes del tenant
http
GET /v1/inbound-ivr-menusTodos los menús que no están retirados, en su versión vigente (la más alta), ordenados por nombre. Un menú retirado no se lista; GET /v1/inbound-ivr-menus/{id} lo sigue respondiendo. Lo puede leer una clave dd_ y cualquier login de dashboard; un token de widget (ddw_) da 403 forbidden.
Una ruta entrante con dest_type: ivr nombra uno de estos menús en su dest_ref; cada llamada a ella oye la versión vigente cuando se conecta (core#1319).
Respuestas
200
Los menús vigentes.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_ivr_menus | arreglo de InboundIvrMenu | sí | |
inbound_ivr_menus[].id | string (uuid) | sí | El menú; estable entre sus versiones. |
inbound_ivr_menus[].status | published · retired | sí | |
inbound_ivr_menus[].version | integer | sí | La versión vigente, o aquella en la que se retiró el menú. |
inbound_ivr_menus[].name | string | sí | |
inbound_ivr_menus[].menu | object (InboundIvrMenuNode) | sí | |
inbound_ivr_menus[].menu.prompt | string | sí | Lo que oye quien llama al entrar en el nodo, con las palabras del tenant (2000 bytes como máximo; un valor vacío se rechaza). Se convierte en audio cuando se publica el menú. |
inbound_ivr_menus[].menu.default | any | sí | OBLIGATORIA. Si no se pulsa ninguna tecla, el aviso se repite y, la segunda vez, se ejecuta esta acción: ningún menú es un callejón sin salida. Nunca optout: no pulsar nada no es pedir salir de la lista. |
inbound_ivr_menus[].menu.entries | object | sí | Una tecla DTMF (0-9, *, #) → una acción terminal o un submenú. |
inbound_ivr_menus[].published_at | string (date-time) | sí | Cuándo se publicó esta versión. |
inbound_ivr_menus[].published_by | string | sí | El id de usuario o de agente de la credencial que publicó esta versión, o tenant-api-key. |
inbound_ivr_menus[].retired_at | string,null (date-time) | sí | |
inbound_ivr_menus[].retired_by | string,null | sí |
401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — Forbidden
El tenant está suspendido. Una sesión del dashboard (ddu_) de un tenant cuya política de inicio de sesión (ADR 227) está en modo enforce responde 403 con el código login_policy_denied ante una solicitud desde una dirección o en una hora que la política no permite — el mismo cuerpo en ambos casos; la sesión no se revoca y una solicitud posterior dentro de la política se procesa. Un token de widget (ddw_) de un puesto queda sujeto a la misma política en cada solicitud (core#2406, indicador widget_login_honors_policy). Un tenant sintético (demo) responde 403 con el código synthetic_tenant en toda ruta que llegaría a un tercero — marcación manual, pierna de transferencia externa o de conferencia, envío de SMS (core#2251, adenda del ADR #280). Ningún pago lo cambia.
json
{
"error": {
"code": "forbidden",
"message": "tenant is suspended"
}
}429 — ApiKeyRateLimited
Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Publicar un menú IVR entrante, o la siguiente versión de uno
http
POST /v1/inbound-ivr-menusPublica menu bajo name. Sin menu_id es un menú nuevo, versión 1, cuyo id es el del menú a partir de entonces; con menu_id es la siguiente versión de ese menú, que pasa a ser la vigente. Nada se edita nunca en el sitio: el historial conserva cada versión.
Publicar, en orden, y no se escribe nada salvo que todo pase:
- se valida el árbol (
InboundIvrMenuNode): cada nodo tiene un aviso de voz y una accióndefault, las teclas son teclas DTMF sueltas, como máximo 5 niveles y 64 nodos; - cada
queue:<id>debe ser una cola entrante ACTIVA (no retirada) de este tenant (/v1/inbound-queues) y cadaagent:<id>un agente ACTIVO de este tenant, si no422que los nombra (la de otro tenant, una inexistente y una cola retirada se leen igual); - cada aviso de voz se convierte en audio AHORA, no cuando llega una llamada. Si alguno no se convierte, el menú no se publica:
503 prompt_render_failed, y la misma petición se puede reintentar.
Los avisos de voz son las palabras del tenant: la plataforma no añade ningún texto propio. Un menu_id que no es un menú de este tenant da 404; uno retirado da 409 conflict (un menú retirado sigue retirado: publica uno nuevo).
Solo gestión del tenant: una clave dd_ o un login account_admin. Un login member recibe 403 role_forbidden; un token de widget (ddw_) recibe 403 forbidden. Quién publicó se toma de la credencial.
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | sí | El nombre del menú, para el operador (recortado; un valor vacío se rechaza). |
menu | object (InboundIvrMenuNode) | sí | |
menu.prompt | string | sí | Lo que oye quien llama al entrar en el nodo, con las palabras del tenant (2000 bytes como máximo; un valor vacío se rechaza). Se convierte en audio cuando se publica el menú. |
menu.default | any | sí | OBLIGATORIA. Si no se pulsa ninguna tecla, el aviso se repite y, la segunda vez, se ejecuta esta acción: ningún menú es un callejón sin salida. Nunca optout: no pulsar nada no es pedir salir de la lista. |
menu.entries | object | sí | Una tecla DTMF (0-9, *, #) → una acción terminal o un submenú. |
menu_id | string (uuid) | no | El menú del que publicar la siguiente versión. Ausente ⇒ un menú nuevo. |
json
{
"name": "Main line",
"menu": {
"prompt": "Thanks for calling. For sales press 1. For billing press 2. To stop receiving our calls press 9.",
"default": "queue:6f1c1b7e-2d7a-4c1e-9d3a-0b5e8f7a1c21",
"entries": {
"1": {
"action": "agent:0d9e2b4a-8c3f-4e6b-a1d2-3c4b5a6f7e80"
},
"2": {
"submenu": {
"prompt": "For a copy of your invoice press 1.",
"default": "hangup",
"entries": {
"1": {
"action": "queue:6f1c1b7e-2d7a-4c1e-9d3a-0b5e8f7a1c21"
}
}
}
},
"9": {
"action": "optout"
}
}
}
}Respuestas
201
Publicado.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_ivr_menu | object (InboundIvrMenu) | sí | |
inbound_ivr_menu.id | string (uuid) | sí | El menú; estable entre sus versiones. |
inbound_ivr_menu.status | published · retired | sí | |
inbound_ivr_menu.version | integer | sí | La versión vigente, o aquella en la que se retiró el menú. |
inbound_ivr_menu.name | string | sí | |
inbound_ivr_menu.menu | object (InboundIvrMenuNode) | sí | |
inbound_ivr_menu.menu.prompt | string | sí | Lo que oye quien llama al entrar en el nodo, con las palabras del tenant (2000 bytes como máximo; un valor vacío se rechaza). Se convierte en audio cuando se publica el menú. |
inbound_ivr_menu.menu.default | any | sí | OBLIGATORIA. Si no se pulsa ninguna tecla, el aviso se repite y, la segunda vez, se ejecuta esta acción: ningún menú es un callejón sin salida. Nunca optout: no pulsar nada no es pedir salir de la lista. |
inbound_ivr_menu.menu.entries | object | sí | Una tecla DTMF (0-9, *, #) → una acción terminal o un submenú. |
inbound_ivr_menu.published_at | string (date-time) | sí | Cuándo se publicó esta versión. |
inbound_ivr_menu.published_by | string | sí | El id de usuario o de agente de la credencial que publicó esta versión, o tenant-api-key. |
inbound_ivr_menu.retired_at | string,null (date-time) | sí | |
inbound_ivr_menu.retired_by | string,null | sí |
400 — BadRequest
Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).
json
{
"error": {
"code": "bad_request",
"message": "from must be RFC-3339"
}
}401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403
role_forbidden: un inicio de sesión de dashboard sin el rol account_admin; forbidden: un token de widget o un tenant suspendido.
json
{
"error": {
"code": "role_forbidden",
"message": "a dashboard login needs the account_admin role to manage inbound IVR menus"
}
}404 — NotFound
Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).
json
{
"error": {
"code": "not_found",
"message": "resource not found for this tenant"
}
}409 — Conflict
Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.
json
{
"error": {
"code": "conflict",
"message": "invalid state transition"
}
}422 — Unprocessable
La forma es correcta, la semántica no (regla de dominio incumplida).
json
{
"error": {
"code": "unprocessable",
"message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
}
}429 — ApiKeyRateLimited
Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}503
Un aviso de voz no se convirtió en audio; no se publicó nada. Reintentable.
json
{
"error": {
"code": "prompt_render_failed",
"message": "a prompt could not be rendered to audio; the menu was not published"
}
}Un menú IVR entrante, su versión vigente y su historial
http
GET /v1/inbound-ivr-menus/{id}La versión vigente del menú (o, una vez retirado, la versión en la que se retiró, con status: retired) más history, cada hecho desde la primera versión hasta la retirada. Un menú que no es de este tenant (o no existe) da 404. Mismos lectores que la lista.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
id | path | string (uuid) | sí | UUID del recurso. Los ids mal formados o de otro tenant se leen como 404. |
Respuestas
200
El menú y su historial.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_ivr_menu | any | sí |
401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — Forbidden
El tenant está suspendido. Una sesión del dashboard (ddu_) de un tenant cuya política de inicio de sesión (ADR 227) está en modo enforce responde 403 con el código login_policy_denied ante una solicitud desde una dirección o en una hora que la política no permite — el mismo cuerpo en ambos casos; la sesión no se revoca y una solicitud posterior dentro de la política se procesa. Un token de widget (ddw_) de un puesto queda sujeto a la misma política en cada solicitud (core#2406, indicador widget_login_honors_policy). Un tenant sintético (demo) responde 403 con el código synthetic_tenant en toda ruta que llegaría a un tercero — marcación manual, pierna de transferencia externa o de conferencia, envío de SMS (core#2251, adenda del ADR #280). Ningún pago lo cambia.
json
{
"error": {
"code": "forbidden",
"message": "tenant is suspended"
}
}404 — NotFound
Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).
json
{
"error": {
"code": "not_found",
"message": "resource not found for this tenant"
}
}429 — ApiKeyRateLimited
Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Retirar un menú IVR entrante
http
POST /v1/inbound-ivr-menus/{id}/retireRetira el menú con un hecho nuevo que nombra su versión vigente; el historial es de solo anexar. Un menú retirado sigue retirado: no se puede publicar de nuevo. Un id que no es un menú vigente de este tenant (desconocido, ya retirado o de otro tenant) da 404. Un menú que una ruta entrante ACTIVA todavía usa da 409 conflict que nombra las rutas: deshabilítalas o apúntalas antes a otro menú (core#1319). Mismos roles que publicar. Sin cuerpo.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
id | path | string (uuid) | sí | UUID del recurso. Los ids mal formados o de otro tenant se leen como 404. |
Respuestas
200
Retirado.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_ivr_menu | object (InboundIvrMenu) | sí | |
inbound_ivr_menu.id | string (uuid) | sí | El menú; estable entre sus versiones. |
inbound_ivr_menu.status | published · retired | sí | |
inbound_ivr_menu.version | integer | sí | La versión vigente, o aquella en la que se retiró el menú. |
inbound_ivr_menu.name | string | sí | |
inbound_ivr_menu.menu | object (InboundIvrMenuNode) | sí | |
inbound_ivr_menu.menu.prompt | string | sí | Lo que oye quien llama al entrar en el nodo, con las palabras del tenant (2000 bytes como máximo; un valor vacío se rechaza). Se convierte en audio cuando se publica el menú. |
inbound_ivr_menu.menu.default | any | sí | OBLIGATORIA. Si no se pulsa ninguna tecla, el aviso se repite y, la segunda vez, se ejecuta esta acción: ningún menú es un callejón sin salida. Nunca optout: no pulsar nada no es pedir salir de la lista. |
inbound_ivr_menu.menu.entries | object | sí | Una tecla DTMF (0-9, *, #) → una acción terminal o un submenú. |
inbound_ivr_menu.published_at | string (date-time) | sí | Cuándo se publicó esta versión. |
inbound_ivr_menu.published_by | string | sí | El id de usuario o de agente de la credencial que publicó esta versión, o tenant-api-key. |
inbound_ivr_menu.retired_at | string,null (date-time) | sí | |
inbound_ivr_menu.retired_by | string,null | sí |
401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403
role_forbidden: un inicio de sesión de dashboard sin el rol account_admin; forbidden: un token de widget o un tenant suspendido.
404 — NotFound
Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).
json
{
"error": {
"code": "not_found",
"message": "resource not found for this tenant"
}
}409 — Conflict
Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.
json
{
"error": {
"code": "conflict",
"message": "invalid state transition"
}
}429 — ApiKeyRateLimited
Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}