conversations

Update the handoff queue

Updates the end user's place in the agent queue for the conversation specified by the conversation_id. The chat widget shows a waiting banner with the position or the estimated wait, keeps it across a page reload, and clears it when a human agent joins or the handoff ends. Send an update whenever the position or the wait changes. Each request replaces the previous queue state, so include unit, and amount for the position and time units, every time. The conversation must be on the chat channel (the web widget and mobile SDKs), in an active Handoffs API handoff, and still waiting for an agent: voice, email and custom channels have no surface for the queue, and an update sent while a human agent is already on the conversation is rejected.

patch/v2/conversations/{conversation_id}/handoff-queue/

Request

  • Base URL: https://example.ada.support/api
  • URL: https://example.ada.support/api/v2/conversations/{conversation_id}/handoff-queue/
  • Auth: HTTP bearer

Path parameters

conversation_idstring id required

The ID of the chat conversation in an active handoff

Request body

unit'position' | 'time' | 'unknown' required

What amount measures. Use position to show the end user how many people are ahead of them. Use time to show the estimated wait. Use unknown when a queue exists but its depth is not disclosed; the end user then sees a generic waiting message instead of a number.

amountinteger

Must be a whole number. Required when unit is position or time, and ignored when unit is unknown. For position, the number of people ahead of the end user, from 0 to 9999; 0 shows the generic waiting message. For time, the estimated wait in seconds, from -1 to 86400. The end user sees the wait rounded up to whole minutes, and -1 or 0 shows the generic waiting message.

Response

Handoff queue updated

messagestring

Changes

No recorded changes to this operation across all 1 revision of this API.