Enrutamiento de colas entrantes: ofertas de rellamada, habilidades y prioridad VIP

English version: Inbound queue routing.

Esta guía separa lo que está disponible en la última versión publicada de core de los controles de enrutamiento que sólo existen en la versión siguiente. Cubre únicamente la configuración por API; no da a entender que exista una pantalla del dashboard.

Disponibilidad

Capacidad	Disponibilidad
Guardar o quitar el umbral de oferta de rellamada de una cola	Publicado en core v0.94.0
Ofrecer y agendar la rellamada a quien espera	El contrato publicado en v0.94.0 dice que el umbral por sí solo no activa una oferta
Asignar habilidades a los agentes y exigir habilidades en una cola	Publicado en core v0.95.0
Designar listas de deudas como VIP	Publicado en core v0.95.0
Leer las métricas de cola de VIP y de agentes coincidentes	Publicado en core v0.96.0

La referencia de la API generada en este sitio puede ir por detrás de la última versión hasta que se actualice su documento OpenAPI vendorizado. Las etiquetas de versión de arriba salen del documento OpenAPI adjunto a la versión publicada de core.

Autenticación y permisos

Todas las operaciones de esta guía están acotadas al tenant. Envía una llave de API del tenant en la cabecera bearer estándar:

Authorization: Bearer dd_example-not-a-real-key
Content-Type: application/json

Las escrituras de configuración aceptan una llave dd_ o un login del dashboard con el rol account_admin. Un miembro del dashboard recibe 403 role_forbidden; un token de widget o un tenant suspendido recibe 403 forbidden.

Umbral de oferta de rellamada (publicado en v0.94.0)

El umbral es la espera medida en una cola a partir de la cual se podría ofrecer una rellamada a quien llama. No es una espera estimada.

Fijar el umbral

PUT /v1/inbound-queues/{id}/callback-offer

{
  "callback_offer_after_ms": 90000
}

callback_offer_after_ms es obligatorio y debe ser un entero JSON mayor que cero. La respuesta es 200 y envuelve la cola actualizada:

{
  "inbound_queue": {
    "id": "6f1c1f0e-8f4e-4c3e-9a61-0d7c1b6f2a10",
    "callback_offer_after_ms": 90000
  }
}

La respuesta real de la cola contiene también el resto de los campos de InboundQueue. No tomes una escritura exitosa como prueba de que quien llama oirá una oferta: el contrato publicado establece que el interruptor inbound_callback_offer_enabled de la cuenta también debe estar activo y que el umbral por sí solo únicamente guarda configuración.

Quitar el umbral

DELETE /v1/inbound-queues/{id}/callback-offer

La petición no lleva cuerpo. Una respuesta 200 exitosa devuelve la cola con callback_offer_after_ms: null. Un umbral nulo significa que esa cola no ofrece rellamada.

Errores de la configuración de rellamada

HTTP	error.code	Cuándo aplica
400	invalid	El umbral no es un entero mayor que cero.
400	bad_request	La forma del JSON es incorrecta o contiene un campo no reconocido.
401	unauthorized	La credencial bearer falta, es desconocida o fue revocada.
403	role_forbidden	Un login del dashboard no tiene account_admin.
403	forbidden	La credencial es un token de widget o el tenant está suspendido.
404	not_found	El id no es una cola activa de este tenant.
429	rate_limited	La cuota de peticiones de la llave de API rechaza la petición.

El código exacto de 429 lo define la respuesta compartida de límite de tasa del documento OpenAPI; los clientes deben ramificar siempre por error.code, no por el mensaje legible.

Habilidades (core v0.95.0)

Las operaciones siguientes se publicaron en core v0.95.0. No las llames contra un core desplegado más antiguo.

Reemplazar las habilidades de un agente

PUT /v1/agents/{id}/skills

{
  "skills": ["idioma_es", "cobranza_tardia"]
}

El cuerpo reemplaza el conjunto completo. Los valores repetidos cuentan una sola vez. Una habilidad es una etiqueta definida por el tenant que cumple ^[a-z0-9][a-z0-9_-]{0,39}$; no hay catálogo global ni niveles. Envía como máximo 50 valores. Lee el resultado ordenado con:

GET /v1/agents/{id}/skills

Ambas operaciones son sólo para administradores. Un agente inexistente devuelve 404 not_found. Las etiquetas mal formadas, un valor que no sea arreglo o más de 50 entradas devuelven 422 unprocessable sin cambiar el conjunto guardado. Los campos desconocidos en la petición devuelven 400 bad_request.

Reemplazar las habilidades exigidas de una cola

PUT /v1/inbound-queues/{id}/skills

{
  "skills": ["idioma_es"]
}

Este cuerpo también reemplaza el conjunto completo. Un agente debe tener todas las etiquetas que exige la cola. Un arreglo vacío quita el requisito. Lee el conjunto ordenado y las advertencias con:

GET /v1/inbound-queues/{id}/skills

Los errores de validación y de permisos son los mismos que en las habilidades de agente, más 404 not_found cuando la cola no es una cola activa de este tenant. Un requisito duro sin desborde se guarda, pero la respuesta lleva required_skills_without_overflow en warnings.

La configuración de habilidades sigue inerte mientras inbound_queue_skill_routing_enabled esté apagado. Si el enrutador no puede leer las habilidades del agente o de la cola, no ofrece la llamada a un agente sin comprobar; la llamada permanece en la cola. El desborde de una cola es la salida configurada para una llamada sin agente coincidente. Las habilidades son preferencias de enrutamiento, no autorizaciones de cumplimiento, y no se saltan las puertas posteriores.

Designación de listas VIP (core v0.95.0)

La prioridad VIP usa las listas de deudas existentes en lugar de un atributo nuevo de la cuenta. Reemplaza todas las listas designadas con:

PUT /v1/inbound-vip-lists

{
  "list_ids": ["6f1c1f0e-8f4e-4c3e-9a61-0d7c1b6f2a10"]
}

list_ids debe ser un arreglo de como máximo 50 cadenas UUID. Un arreglo vacío quita todas las designaciones. Lee las listas designadas con:

GET /v1/inbound-vip-lists

Ambas operaciones son sólo para administradores. La escritura devuelve 422 unprocessable sin cambiar nada cuando el valor no es un arreglo de cadenas UUID, excede el límite o nombra una lista ajena a este tenant. Los campos desconocidos devuelven 400 bad_request; los fallos de autenticación y de permisos usan los mismos códigos 401 y 403 descritos arriba.

Las designaciones guardadas siguen inertes mientras inbound_queue_vip_head_start_ms sea cero. Cuando se activa, el VIP es una ventaja inicial acotada y no una prioridad estricta: cambia el orden de oferta sin cambiar la posición en cola que se reporta. Si no se puede decidir el estado VIP, quien llama sigue siendo estándar; no se bloquea su admisión ni se le concede ningún privilegio.

Métricas en vivo (core v0.96.0)

Las operaciones existentes de cola en vivo ganan estos campos por cola:

• vip_depth: llamadas VIP en espera; null mientras el VIP esté inactivo o el flujo de la cola esté apagado, y 0 sólo cuando el VIP está activo y no hay ninguna esperando.
• vip_oldest_wait_ms: la espera VIP más antigua; null cuando vip_depth es nulo o cero.
• ready_matching: agentes listos que tienen todas las habilidades que exige esta cola; null cuando la cola no tiene requisito, el enrutamiento por habilidades está apagado, el diario de asientos está apagado o no se pudieron leer las habilidades.

Estos nulos son señales fail-closed deliberadas. No los muestres como cero: cero significa que la capacidad se midió y no encontró ninguna entidad coincidente, mientras que nulo significa que estaba inactiva o no se pudo medir.

Orden seguro de despliegue

1. Configura el desborde de las colas que tendrán requisitos duros de habilidades.
2. Guarda las habilidades de los agentes y los requisitos de las colas mientras el enrutamiento por habilidades esté apagado.
3. Designa las listas de deudas VIP mientras la ventaja inicial del VIP sea cero.
4. Confirma que la versión de core desplegada publica las operaciones de arriba.
5. Pide al operador que active los interruptores del tenant; estas operaciones de la API no los activan.
6. Vigila las distinciones nulo/cero de la cola en vivo y la señal de falta de agentes con la habilidad antes de ampliar el despliegue.

Apagar el interruptor de habilidades o volver a poner en cero la ventaja inicial del VIP deja inerte la configuración guardada. Quitar el umbral de rellamada con DELETE deja esa cola sin elegibilidad para ofertas de rellamada.