Appearance
Colas 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.
Las colas entrantes del tenant: se crean con un nombre, un desborde opcional hacia otra de sus colas, y se retiran cuando nada las usa. Una ruta con dest_type: queue nombra una en queue_id; un menú IVR entrante nombra una como queue:<id>.
Endpoints
Las colas entrantes activas del tenant, y si el encolado está activado
http
GET /v1/inbound-queuesTodas las colas que no están retiradas, ordenadas por nombre (sin distinguir mayúsculas; una cola creada antes de que existieran los nombres tiene name: null y va la última). Cada una lleva su desborde y cuántas rutas queue ACTIVAS la nombran. Una cola retirada no se lista; GET /v1/inbound-queues/{id} la sigue respondiendo.
capability dice si la cola entrante admite llamadas para este tenant, y qué interruptor falta cuando no lo hace (ADR #104 D7 y su adenda de core#1354): necesita DOS interruptores, ambos resueltos para el tenant: inbound_queue_stream_enabled, el propio de la cola, y agent_session_journal_enabled, el diario de puestos de agente sin el cual no se puede ofrecer una llamada a ningún agente. enabled es true solo con ambos ACTIVADOS; con cualquiera APAGADO, una llamada a una ruta queue no se admite en ninguna cola, no se contesta y no se ofrece a nadie, sea cual sea la configuración de la cola. Esta lectura no cambia ninguno de los dos interruptores. Lo puede leer una clave dd_ y cualquier login de dashboard; un token de widget (ddw_) da 403 forbidden.
Respuestas
200
Las colas activas y la capacidad.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_queues | arreglo de InboundQueue | sí | |
inbound_queues[].id | string (uuid) | sí | |
inbound_queues[].name | string,null | sí | null solo para una cola creada antes de que existieran los nombres (core#1347). |
inbound_queues[].status | active · retired | sí | |
inbound_queues[].overflow_max_wait_ms | integer,null | sí | La espera tras la cual una llamada pasa a overflow_queue_id; null = sin desborde. |
inbound_queues[].overflow_queue_id | string,null (uuid) | sí | |
inbound_queues[].callback_offer_after_ms | integer,null | sí | La espera MEDIDA, en milisegundos, tras la cual a quien llama a esta cola se le ofrecería una rellamada; null = esta cola no ofrece ninguna. Por sí solo no ofrece nada, porque el indicador inbound_callback_offer_enabled de la cuenta también tiene que estar activado (core#1670). |
inbound_queues[].active_route_count | integer | sí | Cuántas rutas queue ACTIVAS del tenant nombran esta cola. |
inbound_queues[].created_at | string (date-time) | sí | |
inbound_queues[].retired_at | string,null (date-time) | sí | |
inbound_queues[].retired_by | string,null | sí | El id de usuario o de agente de la credencial que la retiró, o tenant-api-key. |
inbound_queues[].required_skills | arreglo de string | no | Las habilidades que necesita un agente para que se le ofrezcan las llamadas de esta cola (ordenadas); [] = no exige nada. Se fijan con PUT /v1/inbound-queues/{id}/skills. |
inbound_queues[].warnings | arreglo de required_skills_without_overflow | no | required_skills_without_overflow: la cola exige habilidades y no tiene desborde, así que una llamada para la que nadie está cualificado espera sin salida (ADR #216 D6). |
capability | object (InboundQueueCapability) | sí | |
capability.flag | inbound_queue_stream_enabled | sí | El interruptor propio de la cola, el que se activa para activar la cola. |
capability.enabled | boolean | sí | Si la cola entrante admite llamadas para este tenant: true solo cuando AMBOS switches están ACTIVADOS (core#1354). false es el valor por defecto; esta API no lo cambia. |
capability.switches | object | sí | Cada interruptor que necesita la cola, resuelto para el tenant. Con la cola ACTIVADA y el diario de puestos APAGADO, una llamada a una ruta queue se rechaza sin contestar, porque nunca se podría ofrecer a ningún agente. |
capability.switches.inbound_queue_stream_enabled | boolean | sí | |
capability.switches.agent_session_journal_enabled | boolean | 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"
}
}Crear una cola entrante
http
POST /v1/inbound-queuesCrea una cola activa llamada name, sin desborde. El nombre se recorta y debe ser único entre las colas ACTIVAS de este tenant sin distinguir mayúsculas (409 conflict en caso contrario); el nombre de una cola retirada vuelve a quedar libre. Una cola nunca se renombra.
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.
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | sí | El nombre de la cola, para el operador (recortado; un valor vacío se rechaza). |
json
{
"name": "Sales"
}Respuestas
201
Creada.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_queue | object (InboundQueue) | sí | |
inbound_queue.id | string (uuid) | sí | |
inbound_queue.name | string,null | sí | null solo para una cola creada antes de que existieran los nombres (core#1347). |
inbound_queue.status | active · retired | sí | |
inbound_queue.overflow_max_wait_ms | integer,null | sí | La espera tras la cual una llamada pasa a overflow_queue_id; null = sin desborde. |
inbound_queue.overflow_queue_id | string,null (uuid) | sí | |
inbound_queue.callback_offer_after_ms | integer,null | sí | La espera MEDIDA, en milisegundos, tras la cual a quien llama a esta cola se le ofrecería una rellamada; null = esta cola no ofrece ninguna. Por sí solo no ofrece nada, porque el indicador inbound_callback_offer_enabled de la cuenta también tiene que estar activado (core#1670). |
inbound_queue.active_route_count | integer | sí | Cuántas rutas queue ACTIVAS del tenant nombran esta cola. |
inbound_queue.created_at | string (date-time) | sí | |
inbound_queue.retired_at | string,null (date-time) | sí | |
inbound_queue.retired_by | string,null | sí | El id de usuario o de agente de la credencial que la retiró, o tenant-api-key. |
inbound_queue.required_skills | arreglo de string | no | Las habilidades que necesita un agente para que se le ofrezcan las llamadas de esta cola (ordenadas); [] = no exige nada. Se fijan con PUT /v1/inbound-queues/{id}/skills. |
inbound_queue.warnings | arreglo de required_skills_without_overflow | no | required_skills_without_overflow: la cola exige habilidades y no tiene desborde, así que una llamada para la que nadie está cualificado espera sin salida (ADR #216 D6). |
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 queues"
}
}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"
}
}Cuántas llamadas esperan en cada cola entrante activa, y desde cuándo
http
GET /v1/inbound-queues/liveEl estado en vivo de cada cola entrante ACTIVA del tenant (core#1526): depth (las llamadas que esperan ahora) y oldest_wait_ms (cuánto lleva esperando la que más). Ambos se DERIVAN del flujo de cola de solo anexar, nunca de un contador: una llamada está esperando mientras su enqueued no tenga terminal (answered, abandoned, overflowed, callback_booked). Una llamada que se está ofreciendo a un agente sigue esperando y cuenta. Una llamada que se desborda a otra cola deja de contar aquí y cuenta en el destino, donde su espera empieza en el desborde.
Apagado no es cero. Con inbound_queue_stream_enabled del tenant APAGADO nadie escribe el flujo, así que no hay nada que contar: stream_enabled es false y depth y oldest_wait_ms son null, nunca 0. depth: 0 significa que la cola está activada y vacía, y entonces oldest_wait_ms también es null.
Los huérfanos no lo inflan. Una caída entre el enqueued y su terminal deja una admisión que nadie cierra. Una admisión más antigua que wait_bound_ms se lee como huérfana y se deja fuera de ambas cifras: wait_bound_ms es el overflow_max_wait_ms de la cola (el mismo límite que usa su desborde) y, para una cola sin desborde configurado, un techo fijo de una hora. El flujo es de solo anexar; no se cierra nada, la lectura simplemente deja de contarla.
oldest_wait_ms es una lectura en vivo tomada con el reloj de pared (as_of menos el instante de enqueued, nunca por debajo de 0), no el wait_duration_ms medido que usan el historial y los informes. ready_agents es el recuento, de todo el tenant, de agentes en Ready ahora (los agentes no son por cola), null cuando el diario de puestos de agente está APAGADO. Lo puede leer una clave dd_ y cualquier login de dashboard; un token de widget (ddw_) da 403 forbidden.
VIP y habilidades (core#1677). Por cola, vip_depth y vip_oldest_wait_ms son las mismas dos cifras contadas solo sobre las llamadas VIP (admisiones selladas vip). Son null, nunca 0, mientras el VIP no está activo para el tenant (inbound_queue_vip_head_start_ms en 0, o inerte porque la ventaja alcanza el umbral de servicio) y mientras el flujo de cola está APAGADO; con el VIP activo y ningún VIP esperando, vip_depth es 0 y vip_oldest_wait_ms es null. ready_matching es cuántos agentes Ready cumplen el requisito de habilidades de ESA cola; es null cuando la cola no exige habilidades, el enrutamiento por habilidades está APAGADO, el diario de puestos está APAGADO, o no se pudieron leer las habilidades. Cuenta los agentes Ready del diario, sin descontar los que ya tienen una oferta viva.
Respuestas
200
El estado en vivo de las colas activas.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
as_of | string (date-time) | sí | El instante en que se tomó la lectura. |
stream_enabled | boolean | sí | false = el flujo de cola está APAGADO para el tenant: depth es desconocido, no cero. |
ready_agents | integer,null | sí | Agentes en Ready ahora, de todo el tenant; null cuando el diario de puestos está APAGADO. |
inbound_queues | arreglo de InboundQueueLive | sí | |
inbound_queues[].queue_id | string (uuid) | sí | |
inbound_queues[].name | string,null | sí | |
inbound_queues[].depth | integer,null | sí | Llamadas que esperan ahora (admisiones sin terminal, dentro de wait_bound_ms). null cuando el flujo de cola del tenant está APAGADO: desconocido, nunca 0. |
inbound_queues[].oldest_wait_ms | integer,null | sí | Cuánto lleva esperando la llamada que más espera, por el reloj de pared. null cuando depth es null o 0. |
inbound_queues[].vip_depth | integer,null | sí | De depth, las llamadas VIP (admisiones selladas vip). null mientras el VIP no está activo (inbound_queue_vip_head_start_ms en 0, o inerte) o el flujo de cola está APAGADO, nunca 0; 0 significa que el VIP está activo y ninguno espera. |
inbound_queues[].vip_oldest_wait_ms | integer,null | sí | Cuánto lleva esperando la llamada VIP que más espera, por el reloj de pared. null cuando vip_depth es null o 0. |
inbound_queues[].ready_matching | integer,null | sí | Cuántos agentes Ready cumplen el requisito de habilidades de ESTA cola (todos ellos). null cuando la cola no exige habilidades, el enrutamiento por habilidades está APAGADO, el diario de puestos está APAGADO, o no se pudieron leer las habilidades; nunca 0 por «no medido». Cuenta los agentes Ready sin descontar los que ya tienen una oferta viva. |
inbound_queues[].wait_bound_ms | integer | sí | La antigüedad a partir de la cual una admisión sin terminal se lee como huérfana y se deja fuera. El overflow_max_wait_ms de la cola cuando está fijado; si no, 3600000 (una hora). |
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"
}
}Una cola entrante, activa o retirada
http
GET /v1/inbound-queues/{id}La cola (con status: retired una vez retirada) y la capability del tenant, como en la lista. Una cola 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
La cola.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_queue | object (InboundQueue) | sí | |
inbound_queue.id | string (uuid) | sí | |
inbound_queue.name | string,null | sí | null solo para una cola creada antes de que existieran los nombres (core#1347). |
inbound_queue.status | active · retired | sí | |
inbound_queue.overflow_max_wait_ms | integer,null | sí | La espera tras la cual una llamada pasa a overflow_queue_id; null = sin desborde. |
inbound_queue.overflow_queue_id | string,null (uuid) | sí | |
inbound_queue.callback_offer_after_ms | integer,null | sí | La espera MEDIDA, en milisegundos, tras la cual a quien llama a esta cola se le ofrecería una rellamada; null = esta cola no ofrece ninguna. Por sí solo no ofrece nada, porque el indicador inbound_callback_offer_enabled de la cuenta también tiene que estar activado (core#1670). |
inbound_queue.active_route_count | integer | sí | Cuántas rutas queue ACTIVAS del tenant nombran esta cola. |
inbound_queue.created_at | string (date-time) | sí | |
inbound_queue.retired_at | string,null (date-time) | sí | |
inbound_queue.retired_by | string,null | sí | El id de usuario o de agente de la credencial que la retiró, o tenant-api-key. |
inbound_queue.required_skills | arreglo de string | no | Las habilidades que necesita un agente para que se le ofrezcan las llamadas de esta cola (ordenadas); [] = no exige nada. Se fijan con PUT /v1/inbound-queues/{id}/skills. |
inbound_queue.warnings | arreglo de required_skills_without_overflow | no | required_skills_without_overflow: la cola exige habilidades y no tiene desborde, así que una llamada para la que nadie está cualificado espera sin salida (ADR #216 D6). |
capability | object (InboundQueueCapability) | sí | |
capability.flag | inbound_queue_stream_enabled | sí | El interruptor propio de la cola, el que se activa para activar la cola. |
capability.enabled | boolean | sí | Si la cola entrante admite llamadas para este tenant: true solo cuando AMBOS switches están ACTIVADOS (core#1354). false es el valor por defecto; esta API no lo cambia. |
capability.switches | object | sí | Cada interruptor que necesita la cola, resuelto para el tenant. Con la cola ACTIVADA y el diario de puestos APAGADO, una llamada a una ruta queue se rechaza sin contestar, porque nunca se podría ofrecer a ningún agente. |
capability.switches.inbound_queue_stream_enabled | boolean | sí | |
capability.switches.agent_session_journal_enabled | boolean | 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"
}
}Cuántas llamadas esperan en una cola entrante, y desde cuándo
http
GET /v1/inbound-queues/{id}/liveLa misma lectura en vivo que GET /v1/inbound-queues/live, para una cola (mismas reglas: derivada del flujo, apagado es null y no 0, los huérfanos más allá de wait_bound_ms se dejan fuera). Una cola que no es de este tenant, no existe o está retirada da 404: una cola retirada no admite a nadie, así que no hay nada en vivo que leer. Mismos lectores.
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 estado en vivo de la cola.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
as_of | string (date-time) | sí | |
stream_enabled | boolean | sí | |
ready_agents | integer,null | sí | |
inbound_queue | object (InboundQueueLive) | sí | |
inbound_queue.queue_id | string (uuid) | sí | |
inbound_queue.name | string,null | sí | |
inbound_queue.depth | integer,null | sí | Llamadas que esperan ahora (admisiones sin terminal, dentro de wait_bound_ms). null cuando el flujo de cola del tenant está APAGADO: desconocido, nunca 0. |
inbound_queue.oldest_wait_ms | integer,null | sí | Cuánto lleva esperando la llamada que más espera, por el reloj de pared. null cuando depth es null o 0. |
inbound_queue.vip_depth | integer,null | sí | De depth, las llamadas VIP (admisiones selladas vip). null mientras el VIP no está activo (inbound_queue_vip_head_start_ms en 0, o inerte) o el flujo de cola está APAGADO, nunca 0; 0 significa que el VIP está activo y ninguno espera. |
inbound_queue.vip_oldest_wait_ms | integer,null | sí | Cuánto lleva esperando la llamada VIP que más espera, por el reloj de pared. null cuando vip_depth es null o 0. |
inbound_queue.ready_matching | integer,null | sí | Cuántos agentes Ready cumplen el requisito de habilidades de ESTA cola (todos ellos). null cuando la cola no exige habilidades, el enrutamiento por habilidades está APAGADO, el diario de puestos está APAGADO, o no se pudieron leer las habilidades; nunca 0 por «no medido». Cuenta los agentes Ready sin descontar los que ya tienen una oferta viva. |
inbound_queue.wait_bound_ms | integer | sí | La antigüedad a partir de la cual una admisión sin terminal se lee como huérfana y se deja fuera. El overflow_max_wait_ms de la cola cuando está fijado; si no, 3600000 (una hora). |
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"
}
}Cuántas rellamadas ofreció una cola entrante y cuántas se aceptaron
http
GET /v1/inbound-queues/{id}/callback-offer/statsLas ofertas de rellamada hechas en [from, to) en una cola y cómo terminó cada una (adenda del ADR #215, core#1884). Derivado del flujo de cola de solo anexar (callback_offered, callback_booked y los demás eventos terminales); no se acumula nada. La cohorte son las ofertas hechas en la ventana, así que offered = accepted + declined_or_abandoned + open siempre:
accepted: quien llamó aceptó la rellamada (uncallback_bookedcerró la admisión), aunque ocurriera después deto.declined_or_abandoned: la admisión se cerró de cualquier otra forma (contestada, abandonada o desbordada) sin reserva.open: la admisión aún no se ha cerrado.
from y to son obligatorios (RFC-3339). 400 cuando falta uno o está mal formado o from no es anterior a to; 422 cuando la ventana es mayor de 31 días. Una cola que no es de este tenant o que no existe da 404; una cola retirada conserva su historial legible. Mismos lectores que las demás lecturas de colas entrantes.
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. |
from | query | string (date-time) | sí | Inicio de la ventana, inclusivo. |
to | query | string (date-time) | sí | Fin de la ventana, exclusivo. Como máximo 31 días después de from. |
Respuestas
200
Los recuentos de la ventana.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_queue_id | string (uuid) | sí | |
from | string (date-time) | sí | |
to | string (date-time) | sí | |
callback_offer | object | sí | |
callback_offer.offered | integer | sí | |
callback_offer.accepted | integer | sí | |
callback_offer.declined_or_abandoned | integer | sí | |
callback_offer.open | integer | sí |
json
{
"inbound_queue_id": "0b6f5f8e-3f5c-4d0e-9a53-6a2f1f6a1c11",
"from": "2026-10-01T00:00:00Z",
"to": "2026-10-02T00:00:00Z",
"callback_offer": {
"offered": 6,
"accepted": 2,
"declined_or_abandoned": 3,
"open": 1
}
}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 — 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"
}
}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"
}
}Fijar el desborde de la cola hacia otra de las colas del tenant
http
PUT /v1/inbound-queues/{id}/overflowUna llamada que ha esperado overflow_max_wait_ms en esta cola pasa a la cola overflow_queue_id (ADR #104 FASE 2c: el único desborde que hay). Ambos campos son obligatorios. 400 invalid cuando el máximo no es un entero positivo, cuando el destino es esta misma cola, no es una cola ACTIVA de este tenant (retirada, de otro tenant, inexistente, mal formada), o ya se desborda, directamente o a través de otras colas, de vuelta a esta: un ciclo de desborde se rechaza. Una cola que no es una cola activa de este tenant da 404. Mismos roles que crear.
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. |
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
overflow_max_wait_ms | integer | sí | |
overflow_queue_id | string (uuid) | sí |
json
{
"overflow_max_wait_ms": 120000,
"overflow_queue_id": "6f1c1b7e-2d7a-4c1e-9d3a-0b5e8f7a1c21"
}Respuestas
200
La cola con su desborde.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_queue | object (InboundQueue) | sí | |
inbound_queue.id | string (uuid) | sí | |
inbound_queue.name | string,null | sí | null solo para una cola creada antes de que existieran los nombres (core#1347). |
inbound_queue.status | active · retired | sí | |
inbound_queue.overflow_max_wait_ms | integer,null | sí | La espera tras la cual una llamada pasa a overflow_queue_id; null = sin desborde. |
inbound_queue.overflow_queue_id | string,null (uuid) | sí | |
inbound_queue.callback_offer_after_ms | integer,null | sí | La espera MEDIDA, en milisegundos, tras la cual a quien llama a esta cola se le ofrecería una rellamada; null = esta cola no ofrece ninguna. Por sí solo no ofrece nada, porque el indicador inbound_callback_offer_enabled de la cuenta también tiene que estar activado (core#1670). |
inbound_queue.active_route_count | integer | sí | Cuántas rutas queue ACTIVAS del tenant nombran esta cola. |
inbound_queue.created_at | string (date-time) | sí | |
inbound_queue.retired_at | string,null (date-time) | sí | |
inbound_queue.retired_by | string,null | sí | El id de usuario o de agente de la credencial que la retiró, o tenant-api-key. |
inbound_queue.required_skills | arreglo de string | no | Las habilidades que necesita un agente para que se le ofrezcan las llamadas de esta cola (ordenadas); [] = no exige nada. Se fijan con PUT /v1/inbound-queues/{id}/skills. |
inbound_queue.warnings | arreglo de required_skills_without_overflow | no | required_skills_without_overflow: la cola exige habilidades y no tiene desborde, así que una llamada para la que nadie está cualificado espera sin salida (ADR #216 D6). |
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.
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"
}
}Quitar el desborde de la cola
http
DELETE /v1/inbound-queues/{id}/overflowAmbos campos de desborde vuelven a null: una llamada espera en esta cola el tiempo que haga falta. Una cola que no es una cola activa de este tenant da 404. Mismos roles que crear. 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
La cola sin desborde.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_queue | object (InboundQueue) | sí | |
inbound_queue.id | string (uuid) | sí | |
inbound_queue.name | string,null | sí | null solo para una cola creada antes de que existieran los nombres (core#1347). |
inbound_queue.status | active · retired | sí | |
inbound_queue.overflow_max_wait_ms | integer,null | sí | La espera tras la cual una llamada pasa a overflow_queue_id; null = sin desborde. |
inbound_queue.overflow_queue_id | string,null (uuid) | sí | |
inbound_queue.callback_offer_after_ms | integer,null | sí | La espera MEDIDA, en milisegundos, tras la cual a quien llama a esta cola se le ofrecería una rellamada; null = esta cola no ofrece ninguna. Por sí solo no ofrece nada, porque el indicador inbound_callback_offer_enabled de la cuenta también tiene que estar activado (core#1670). |
inbound_queue.active_route_count | integer | sí | Cuántas rutas queue ACTIVAS del tenant nombran esta cola. |
inbound_queue.created_at | string (date-time) | sí | |
inbound_queue.retired_at | string,null (date-time) | sí | |
inbound_queue.retired_by | string,null | sí | El id de usuario o de agente de la credencial que la retiró, o tenant-api-key. |
inbound_queue.required_skills | arreglo de string | no | Las habilidades que necesita un agente para que se le ofrezcan las llamadas de esta cola (ordenadas); [] = no exige nada. Se fijan con PUT /v1/inbound-queues/{id}/skills. |
inbound_queue.warnings | arreglo de required_skills_without_overflow | no | required_skills_without_overflow: la cola exige habilidades y no tiene desborde, así que una llamada para la que nadie está cualificado espera sin salida (ADR #216 D6). |
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"
}
}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"
}
}Fijar la espera tras la cual la cola ofrece una rellamada
http
PUT /v1/inbound-queues/{id}/callback-offerFija callback_offer_after_ms, la espera MEDIDA en esta cola tras la cual a quien llama se le ofrecería una rellamada en lugar de seguir esperando (ADR #215, core#1636). El campo es obligatorio. 400 invalid cuando no es un entero de 1 a 9223372036854775807. Una cola que no es una cola activa de este tenant da 404. Mismos roles que crear.
Esto solo almacena el umbral: no se ofrece nada hasta que el indicador inbound_callback_offer_enabled de la cuenta esté activado y se entregue la propia oferta.
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. |
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
callback_offer_after_ms | integer | sí |
json
{
"callback_offer_after_ms": 90000
}Respuestas
200
La cola con su umbral de oferta de rellamada.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_queue | object (InboundQueue) | sí | |
inbound_queue.id | string (uuid) | sí | |
inbound_queue.name | string,null | sí | null solo para una cola creada antes de que existieran los nombres (core#1347). |
inbound_queue.status | active · retired | sí | |
inbound_queue.overflow_max_wait_ms | integer,null | sí | La espera tras la cual una llamada pasa a overflow_queue_id; null = sin desborde. |
inbound_queue.overflow_queue_id | string,null (uuid) | sí | |
inbound_queue.callback_offer_after_ms | integer,null | sí | La espera MEDIDA, en milisegundos, tras la cual a quien llama a esta cola se le ofrecería una rellamada; null = esta cola no ofrece ninguna. Por sí solo no ofrece nada, porque el indicador inbound_callback_offer_enabled de la cuenta también tiene que estar activado (core#1670). |
inbound_queue.active_route_count | integer | sí | Cuántas rutas queue ACTIVAS del tenant nombran esta cola. |
inbound_queue.created_at | string (date-time) | sí | |
inbound_queue.retired_at | string,null (date-time) | sí | |
inbound_queue.retired_by | string,null | sí | El id de usuario o de agente de la credencial que la retiró, o tenant-api-key. |
inbound_queue.required_skills | arreglo de string | no | Las habilidades que necesita un agente para que se le ofrezcan las llamadas de esta cola (ordenadas); [] = no exige nada. Se fijan con PUT /v1/inbound-queues/{id}/skills. |
inbound_queue.warnings | arreglo de required_skills_without_overflow | no | required_skills_without_overflow: la cola exige habilidades y no tiene desborde, así que una llamada para la que nadie está cualificado espera sin salida (ADR #216 D6). |
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.
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"
}
}Quitar el umbral de oferta de rellamada de la cola
http
DELETE /v1/inbound-queues/{id}/callback-offercallback_offer_after_ms vuelve a null: esta cola no ofrece rellamada. Una cola que no es una cola activa de este tenant da 404. Mismos roles que crear. 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
La cola sin umbral de oferta de rellamada.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
inbound_queue | object (InboundQueue) | sí | |
inbound_queue.id | string (uuid) | sí | |
inbound_queue.name | string,null | sí | null solo para una cola creada antes de que existieran los nombres (core#1347). |
inbound_queue.status | active · retired | sí | |
inbound_queue.overflow_max_wait_ms | integer,null | sí | La espera tras la cual una llamada pasa a overflow_queue_id; null = sin desborde. |
inbound_queue.overflow_queue_id | string,null (uuid) | sí | |
inbound_queue.callback_offer_after_ms | integer,null | sí | La espera MEDIDA, en milisegundos, tras la cual a quien llama a esta cola se le ofrecería una rellamada; null = esta cola no ofrece ninguna. Por sí solo no ofrece nada, porque el indicador inbound_callback_offer_enabled de la cuenta también tiene que estar activado (core#1670). |
inbound_queue.active_route_count | integer | sí | Cuántas rutas queue ACTIVAS del tenant nombran esta cola. |
inbound_queue.created_at | string (date-time) | sí | |
inbound_queue.retired_at | string,null (date-time) | sí | |
inbound_queue.retired_by | string,null | sí | El id de usuario o de agente de la credencial que la retiró, o tenant-api-key. |
inbound_queue.required_skills | arreglo de string | no | Las habilidades que necesita un agente para que se le ofrezcan las llamadas de esta cola (ordenadas); [] = no exige nada. Se fijan con PUT /v1/inbound-queues/{id}/skills. |
inbound_queue.warnings | arreglo de required_skills_without_overflow | no | required_skills_without_overflow: la cola exige habilidades y no tiene desborde, así que una llamada para la que nadie está cualificado espera sin salida (ADR #216 D6). |
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"
}
}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 una cola entrante
http
POST /v1/inbound-queues/{id}/retireRetira la cola para siempre: sale de la lista, ninguna ruta, menú ni desborde puede nombrarla, y no se puede configurar; su historial permanece. Un id que no es una cola activa de este tenant (desconocido, ya retirado o de otro tenant) da 404. Mientras algo activo todavía nombre la cola (una ruta queue ACTIVA, un menú IVR entrante vigente, o el desborde de otra cola activa) da 409 conflict que nombra cada uno: deshabilítalos o redirígelos antes. Mismos roles que crear. 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_queue | object (InboundQueue) | sí | |
inbound_queue.id | string (uuid) | sí | |
inbound_queue.name | string,null | sí | null solo para una cola creada antes de que existieran los nombres (core#1347). |
inbound_queue.status | active · retired | sí | |
inbound_queue.overflow_max_wait_ms | integer,null | sí | La espera tras la cual una llamada pasa a overflow_queue_id; null = sin desborde. |
inbound_queue.overflow_queue_id | string,null (uuid) | sí | |
inbound_queue.callback_offer_after_ms | integer,null | sí | La espera MEDIDA, en milisegundos, tras la cual a quien llama a esta cola se le ofrecería una rellamada; null = esta cola no ofrece ninguna. Por sí solo no ofrece nada, porque el indicador inbound_callback_offer_enabled de la cuenta también tiene que estar activado (core#1670). |
inbound_queue.active_route_count | integer | sí | Cuántas rutas queue ACTIVAS del tenant nombran esta cola. |
inbound_queue.created_at | string (date-time) | sí | |
inbound_queue.retired_at | string,null (date-time) | sí | |
inbound_queue.retired_by | string,null | sí | El id de usuario o de agente de la credencial que la retiró, o tenant-api-key. |
inbound_queue.required_skills | arreglo de string | no | Las habilidades que necesita un agente para que se le ofrezcan las llamadas de esta cola (ordenadas); [] = no exige nada. Se fijan con PUT /v1/inbound-queues/{id}/skills. |
inbound_queue.warnings | arreglo de required_skills_without_overflow | no | required_skills_without_overflow: la cola exige habilidades y no tiene desborde, así que una llamada para la que nadie está cualificado espera sin salida (ADR #216 D6). |
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"
}
}Las listas de deudas designadas como VIP para la cola entrante
http
GET /v1/inbound-vip-listsLas listas designadas, por nombre y luego por id, cada una con su nombre y cuándo se designó. vip_lists: [] cuando no hay ninguna designada. Solo administración, como la escritura.
Respuestas
200
Las listas designadas.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
vip_lists | arreglo de object | sí | |
vip_lists[].list_id | string (uuid) | sí | |
vip_lists[].name | string | sí | |
vip_lists[].designated_at | string (date-time) | 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.
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"
}
}Reemplazar las listas de deudas designadas como VIP para la cola entrante
http
PUT /v1/inbound-vip-listsDeclara cuáles de las listas de deudas del tenant cuentan como VIP para la cola entrante (ADR #216 D9). Quien llama es VIP cuando su número pertenece a una deuda que está en alguna de estas listas; quién está en una lista se gestiona con /v1/debt-lists y la importación, nada más cambia. El cuerpo REEMPLAZA el conjunto entero; un id repetido cuenta una vez y [] no designa nada. 422 unprocessable cuando list_ids no es un arreglo de cadenas UUID, tiene más de 50, o nombra una lista que no es una lista de este tenant; entonces no se escribe nada. Escribir funciona con inbound_queue_vip_head_start_ms en 0: lo almacenado queda inerte hasta que se active la ventaja. Borrar una lista retira su designación. Solo administración: dd_ o un login de dashboard con el rol account_admin.
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
list_ids | arreglo de string (uuid) | sí |
json
{
"list_ids": [
"6f1c1f0e-8f4e-4c3e-9a61-0d7c1b6f2a10"
]
}Respuestas
200
Las listas designadas tras la escritura, por nombre.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
vip_lists | arreglo de object | sí | |
vip_lists[].list_id | string (uuid) | sí | |
vip_lists[].name | string | sí | |
vip_lists[].designated_at | string (date-time) | 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.
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"
}
}Las habilidades que exige una cola
http
GET /v1/inbound-queues/{id}/skillsLas habilidades exigidas por la cola, ordenadas, y sus avisos. [] cuando no exige nada (y para una cola retirada, cuyas habilidades se borraron). Una cola que no es de este tenant da 404. Solo administración, como la escritura.
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
Las habilidades exigidas por la cola y los avisos.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
queue_id | string (uuid) | sí | |
skills | arreglo de string | sí | |
warnings | arreglo de required_skills_without_overflow | 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"
}
}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"
}
}Reemplazar las habilidades que exige una cola
http
PUT /v1/inbound-queues/{id}/skillsDeclara qué habilidades debe tener un agente para que se le ofrezcan las llamadas de esta cola (ADR #216 D4-D5): TODAS ellas (un agente necesita cada habilidad). Un conjunto vacío significa que la cola no exige nada. El cuerpo REEMPLAZA el conjunto entero; una habilidad repetida cuenta una vez. 422 unprocessable cuando alguna habilidad está mal formada (^[a-z0-9][a-z0-9_-]{0,39}$), skills no es un arreglo de cadenas, o hay más de 50; entonces no se escribe nada. Una cola que no es una cola activa de este tenant da 404. El requisito es duro: una llamada para la que nadie está cualificado sigue esperando, y la salida es el desborde de la cola. Así que una cola que exige habilidades y no tiene desborde se GUARDA y la respuesta lleva el aviso required_skills_without_overflow (ADR #216 D6); nunca rechaza la escritura. Escribir funciona con inbound_queue_skill_routing_enabled APAGADO: lo almacenado queda inerte. Retirar la cola borra sus habilidades. Mismos roles que las habilidades de agente: solo administración.
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. |
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
skills | arreglo de string | sí |
json
{
"skills": [
"idioma_es"
]
}Respuestas
200
Las habilidades exigidas por la cola tras la escritura, ordenadas, y sus avisos.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
queue_id | string (uuid) | sí | |
skills | arreglo de string | sí | |
warnings | arreglo de required_skills_without_overflow | 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.
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"
}
}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"
}
}