API reference

Queue & members

A Queue holds inbound calls while they wait to be matched to an agent. TelVox's queues run on a real Redis-backed ACD with FIFO or longest-idle selection, hold music, configurable max size and max wait, overflow handling and ring-no-answer re-queue — the same engine Dial ships. You can fetch and list queues, tune their limits, and inspect or act on the calls waiting inside them via the Members subresource. The public Queue/Members REST shape is in developer preview, so the fields and payloads below are illustrative and may change before GA.

Base URL https://api.telvox.dev

Authentication Authorization: Bearer $TELVOX_API_KEY

Queue properties

A Queue resource has the following properties.

Property	Type	Description
sid	string	Unique identifier for the queue, prefixed QU.
friendly_name	string	A human-readable name for the queue, used to address it from your call flows.
current_size	integer	Number of calls currently waiting in the queue.
max_size	integer	Maximum number of calls allowed to wait before new calls hit the overflow path.
max_wait	integer	Maximum time in seconds a call may wait before it is sent to the overflow path.
selection	enum	How waiting calls are matched to agents: fifo or longest-idle.
hold_music_url	string<uri>	Answer-URL document played to waiting callers as hold music (MOH).
overflow_url	string<uri>	Answer-URL document run when a call exceeds max_size or max_wait.
average_wait_time	integer	Rolling average wait, in seconds, for calls recently dequeued from this queue.
date_updated	string<date-time>	ISO 8601 timestamp for the last configuration change.

List queues

GET/v1/queues

Return a paginated list of the queues on your account.

Query parameter	Type	Description
friendly_name	string	Filter to queues matching an exact friendly name.
page_size	integer	Number of results per page. Defaults to 50; cursor returned in the response.

GET/v1/queues

illustrative

curl -G https://api.telvox.dev/v1/queues \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  --data-urlencode "page_size=25"

200 ok

200 — response

illustrative

{
  "queues": [
    {
      "sid": "QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c",
      "friendly_name": "support-tier-1",
      "current_size": 4,
      "max_size": 50,
      "max_wait": 600,
      "selection": "longest-idle",
      "hold_music_url": "https://your.app/voice/moh",
      "overflow_url": "https://your.app/voice/overflow",
      "average_wait_time": 38,
      "date_updated": "2026-06-21T16:10:02Z"
    }
  ],
  "meta": {
    "page_size": 25,
    "next_cursor": null
  }
}

Fetch a queue

GET/v1/queues/{sid}

Retrieve a single queue by its SID, including its current size and average wait.

GET/v1/queues/{sid}

illustrative

curl https://api.telvox.dev/v1/queues/QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c \
  -H "Authorization: Bearer $TELVOX_API_KEY"

200 ok

200 — response

illustrative

{
  "sid": "QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c",
  "friendly_name": "support-tier-1",
  "current_size": 4,
  "max_size": 50,
  "max_wait": 600,
  "selection": "longest-idle",
  "hold_music_url": "https://your.app/voice/moh",
  "overflow_url": "https://your.app/voice/overflow",
  "average_wait_time": 38,
  "date_updated": "2026-06-21T16:10:02Z"
}

Update a queue

POST/v1/queues/{sid}

Tune a queue's limits and routing — max size, max wait, selection strategy, hold music and overflow target.

Body parameter	Type	Description
friendly_name	string	Rename the queue.
max_size	integer	Set the maximum number of calls allowed to wait before overflow.
max_wait	integer	Set the maximum wait in seconds before a call is sent to the overflow path.
selection	enum	Set the matching strategy: fifo or longest-idle.
hold_music_url	string<uri>	Set the answer-URL document used for hold music.
overflow_url	string<uri>	Set the answer-URL document run when a call overflows.

POST/v1/queues/{sid}

illustrative

curl -X POST https://api.telvox.dev/v1/queues/QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -d max_size="75" \
  -d max_wait="900" \
  -d overflow_url="https://your.app/voice/overflow"

200 ok

Member subresource

A member is a call leg currently waiting in a queue, addressed by its call_sid. Members expose their queue position and how long they have waited.

Property	Type	Description
call_sid	string	The SID of the waiting call leg. Identifies the member within the queue.
queue_sid	string	The SID of the queue the call is waiting in.
position	integer	Current 1-based position of the call in the queue.
wait_time	integer	Time in seconds the call has been waiting in the queue.
date_enqueued	string<date-time>	ISO 8601 timestamp for when the call entered the queue.

List members

GET/v1/queues/{sid}/members

List the calls currently waiting in a queue, in position order.

GET/v1/queues/{sid}/members

illustrative

curl https://api.telvox.dev/v1/queues/QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c/members \
  -H "Authorization: Bearer $TELVOX_API_KEY"

200 ok

200 — response

illustrative

{
  "members": [
    {
      "call_sid": "CA1d7b9e3a6c2f48d0b5a1e9c7f2d0b8a4",
      "queue_sid": "QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c",
      "position": 1,
      "wait_time": 47,
      "date_enqueued": "2026-06-21T16:09:15Z"
    }
  ]
}

Update a member (dequeue / redirect)

POST/v1/queues/{sid}/members/{call_sid}

Act on a waiting call: dequeue it to connect to the next available agent, or redirect it to a new answer-URL document.

Body parameter	Type	Description
actionrequired	enum	What to do with the waiting call: dequeue (connect to the next agent) or redirect (send to a new answer-URL document).
url	string<uri>	When action is redirect, the answer-URL document the call is sent to. Ignored for dequeue.

POST/v1/queues/{sid}/members/{call_sid}

illustrative

curl -X POST https://api.telvox.dev/v1/queues/QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c/members/CA1d7b9e3a6c2f48d0b5a1e9c7f2d0b8a4 \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -d action="redirect" \
  -d url="https://your.app/voice/callback-offer"

200 ok

200 — response

illustrative

{
  "call_sid": "CA1d7b9e3a6c2f48d0b5a1e9c7f2d0b8a4",
  "queue_sid": "QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c",
  "action": "redirect",
  "url": "https://your.app/voice/callback-offer"
}

Queue callbacks

When a call enters a queue with a status_callback URL, TelVox issues a signed POST as the call is enqueued, dequeued, redirected, overflowed or abandoned — over the same signed, SSRF-safe egress as the rest of the platform.

Field	Type	Description
QueueSid	string	The SID of the queue the event belongs to.
CallSid	string	The SID of the call leg that triggered the event.
QueueEvent	enum	One of enqueued, dequeued, redirected, overflowed or abandoned.
QueueTime	integer	Seconds the call spent in the queue, included on dequeue and overflow events.

POST your endpoint — dequeued

illustrative

{
  "QueueSid": "QU3e8a1c6b9d2f470a8b5c1e3d7f0a2b9c",
  "CallSid": "CA1d7b9e3a6c2f48d0b5a1e9c7f2d0b8a4",
  "QueueEvent": "dequeued",
  "QueueTime": 47
}