Inbound queue routing: callback offers, skills, and VIP priority

Spanish version: Enrutamiento de colas entrantes.

This guide separates what is available in the latest published core release from the routing controls that are present only in the next version. It covers API configuration only; it does not imply that a dashboard screen exists.

Availability

Capability	Availability
Store or remove a queue's callback-offer threshold	Published in core v0.94.0
Offer and book the callback for a waiting caller	The published v0.94.0 contract says the threshold alone does not activate an offer
Assign skills to agents and require skills on a queue	Published in core v0.95.0
Designate debt lists as VIP	Published in core v0.95.0
Read VIP and matching-agent queue metrics	Published in core v0.96.0

The API reference generated on this site can lag the latest release until its vendored OpenAPI document is refreshed. The version labels above come from the OpenAPI document attached to the published core release.

Authentication and permissions

All operations in this guide are tenant-scoped. Send a tenant API key in the standard bearer header:

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

Configuration writes accept a dd_ key or a dashboard login with the account_admin role. A dashboard member receives 403 role_forbidden; a widget token or suspended tenant receives 403 forbidden.

Callback-offer threshold (published in v0.94.0)

The threshold is the measured wait in one queue after which a caller could be offered a callback. It is not an estimated wait.

Set the threshold

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

{
  "callback_offer_after_ms": 90000
}

callback_offer_after_ms is required and must be a JSON integer greater than zero. The response is 200 and wraps the updated queue:

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

The real queue response contains the rest of the InboundQueue fields as well. Do not treat a successful write as proof that callers will hear an offer: the published contract states that the account's inbound_callback_offer_enabled switch must also be on and that the threshold by itself only stores configuration.

Remove the threshold

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

The request has no body. A successful 200 response returns the queue with callback_offer_after_ms: null. A null threshold means that this queue does not offer a callback.

Callback configuration errors

HTTP	error.code	When it applies
400	invalid	The threshold is not an integer greater than zero.
400	bad_request	The JSON shape is wrong or contains an unrecognized field.
401	unauthorized	The bearer credential is missing, unknown, or revoked.
403	role_forbidden	A dashboard login lacks account_admin.
403	forbidden	The credential is a widget token or the tenant is suspended.
404	not_found	The id is not an active queue of this tenant.
429	rate_limited	The API-key request quota rejects the request.

The exact 429 code is defined by the shared rate-limit response in the OpenAPI document; clients should always branch on error.code, not the human message.

Skills (core v0.95.0)

The following operations were published in core v0.95.0. Do not call them against an older deployed core.

Replace an agent's skills

PUT /v1/agents/{id}/skills

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

The body replaces the entire set. Repeated values count once. A skill is a tenant-defined label matching ^[a-z0-9][a-z0-9_-]{0,39}$; there is no global catalog or level. Send at most 50 values. Read the sorted result with:

GET /v1/agents/{id}/skills

Both operations are admin-only. A missing agent returns 404 not_found. Malformed labels, a non-array value, or more than 50 entries return 422 unprocessable without changing the stored set. Unknown request fields return 400 bad_request.

Replace a queue's required skills

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

{
  "skills": ["idioma_es"]
}

This body also replaces the entire set. An agent must have every label required by the queue. An empty array removes the requirement. Read the sorted set and warnings with:

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

The validation and permission errors are the same as for agent skills, plus 404 not_found when the queue is not an active queue of this tenant. A hard requirement with no overflow is saved, but the response carries required_skills_without_overflow in warnings.

Skill configuration remains inert while inbound_queue_skill_routing_enabled is off. If the router cannot read the agent or queue skills, it does not offer the call to an unchecked agent; the call remains in the queue. A queue overflow is the configured exit for a call that has no matching agent. Skills are routing preferences, not compliance authorizations, and do not bypass downstream gates.

VIP list designation (core v0.95.0)

VIP priority uses existing debt lists rather than a new account attribute. Replace all designated lists with:

PUT /v1/inbound-vip-lists

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

list_ids must be an array of at most 50 UUID strings. An empty array removes all designations. Read the designated lists with:

GET /v1/inbound-vip-lists

Both operations are admin-only. The write returns 422 unprocessable without changing anything when the value is not an array of UUID strings, exceeds the limit, or names a list outside this tenant. Unknown fields return 400 bad_request; authentication and permission failures use the same 401 and 403 codes described above.

Stored designations remain inert while inbound_queue_vip_head_start_ms is zero. When enabled, VIP is a bounded head start rather than strict priority: it changes offer order without changing the reported queue position. If VIP status cannot be decided, the caller remains standard; admission is not blocked and no privilege is granted.

Live metrics (core v0.96.0)

The existing queue-live operations gain these fields per queue:

• vip_depth: VIP calls waiting; null while VIP is inactive or the queue stream is off, and 0 only when VIP is active and none are waiting.
• vip_oldest_wait_ms: the oldest VIP wait; null when vip_depth is null or zero.
• ready_matching: ready agents who have every skill required by this queue; null when the queue has no requirement, skill routing is off, the seat journal is off, or skills could not be read.

These nulls are deliberate fail-closed signals. Do not render them as zero: zero means the capability was measured and found no matching entity, while null means it was inactive or could not be measured.

Safe rollout order

1. Configure overflow for queues that will have hard skill requirements.
2. Store agent skills and queue requirements while skill routing is off.
3. Designate VIP debt lists while the VIP head start is zero.
4. Confirm that your deployed core version publishes the operations above.
5. Have the operator enable the tenant switches; these API operations do not enable them.
6. Watch the queue-live null/zero distinctions and the no-skilled-agent signal before widening the rollout.

Turning the skill switch off or setting the VIP head start back to zero makes the stored configuration inert. Removing the callback threshold with DELETE makes that queue ineligible for callback offers.