curl -X POST https://api.tracklysms.com/api/v1/voice/queues/665f1e2a9c4b1a0012ab34cd/dequeue \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"connectTo": "665f1e2a9c4b1a0012ab34ef",
"record": true
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab34d0",
"direction": "inbound",
"state": "dequeuing",
"legKind": "primary",
"from": "+14155551234",
"to": "+18005551234",
"connectTo": null,
"queueId": "665f1e2a9c4b1a0012ab34cd",
"conferenceId": "665f1e2a9c4b1a0012ab34e1",
"parentCallId": null,
"bridgedCallId": "665f1e2a9c4b1a0012ab34e2",
"monitorRole": null,
"record": false,
"recordingState": null,
"recordingFileIds": [],
"customData": {},
"error": null,
"startedAt": "2026-08-21T18:00:00.000000Z",
"answeredAt": "2026-08-21T18:00:12.000000Z",
"endedAt": null,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Voice Calls (v1)
Dequeue a Call
Claim the oldest waiting caller in a queue (FIFO) and bridge it to an agent.
POST
/
v1
/
voice
/
queues
/
{queueId}
/
dequeue
curl -X POST https://api.tracklysms.com/api/v1/voice/queues/665f1e2a9c4b1a0012ab34cd/dequeue \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"connectTo": "665f1e2a9c4b1a0012ab34ef",
"record": true
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab34d0",
"direction": "inbound",
"state": "dequeuing",
"legKind": "primary",
"from": "+14155551234",
"to": "+18005551234",
"connectTo": null,
"queueId": "665f1e2a9c4b1a0012ab34cd",
"conferenceId": "665f1e2a9c4b1a0012ab34e1",
"parentCallId": null,
"bridgedCallId": "665f1e2a9c4b1a0012ab34e2",
"monitorRole": null,
"record": false,
"recordingState": null,
"recordingFileIds": [],
"customData": {},
"error": null,
"startedAt": "2026-08-21T18:00:00.000000Z",
"answeredAt": "2026-08-21T18:00:12.000000Z",
"endedAt": null,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Claims the oldest waiting caller in the queue (FIFO) and bridges it to the supplied agent or number. The returned call is the caller, now transitioning to the
dequeuing state.
Requires the voice_calls.write scope and the Voice Calls product entitlement.
Path Parameters
string
required
The id of the queue to claim a caller from.
Body Parameters
string
required
The bridge target for the claimed caller. Accepts either the
id of a voice agent or an E.164 number. The resolved destination is screened against your account’s compliance suppression (DNC, opt-out, quiet hours) before dialing; if it is blocked, the caller is returned to the queue and the request fails with a 403.boolean
default:false
Whether to record the call. This applies only to the newly dialed agent bridge leg and never changes the caller’s own
record / recordingState. The returned caller reflects whatever recording state it already had — record: false / recordingState: null unless recording was previously started on that caller, for example via Start Recording while queued, or by answering the call with record: true. Recording may require consent — see call recording.Response Fields
object
The claimed caller.
Hide Call properties
Hide Call properties
string
The call’s unique identifier.
string
inbound for a queued caller.string
Lifecycle state. A dequeued caller transitions to
dequeuing. See Call states.string
primary, bridge, or monitor.string
The caller’s number.
string
The number the caller dialed.
string | null
Always
null on the returned caller — the resolved agent target lives on the bridge leg, referenced by bridgedCallId.string | null
The queue this call was parked in.
string | null
The provider conference id once a bridge or monitor leg is attached.
string | null
For a bridge/monitor leg, the primary call it belongs to.
string | null
For a primary call, the currently bridged agent leg.
string | null
MONITOR or ADVISOR for a monitor leg.boolean
Whether recording was requested.
string | null
requested, started, stopped, ready, failed, or deleted.array
Provider file ids for completed recordings.
object
Metadata attached to the call.
string | null
A machine-readable reason when the call failed.
string | null
ISO 8601 timestamp when the call was placed.
string | null
ISO 8601 timestamp when the call was answered.
string | null
ISO 8601 timestamp when the call ended.
string | null
ISO 8601 timestamp when the record was created.
Examples
curl -X POST https://api.tracklysms.com/api/v1/voice/queues/665f1e2a9c4b1a0012ab34cd/dequeue \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"connectTo": "665f1e2a9c4b1a0012ab34ef",
"record": true
}'
{
"call": {
"id": "665f1e2a9c4b1a0012ab34d0",
"direction": "inbound",
"state": "dequeuing",
"legKind": "primary",
"from": "+14155551234",
"to": "+18005551234",
"connectTo": null,
"queueId": "665f1e2a9c4b1a0012ab34cd",
"conferenceId": "665f1e2a9c4b1a0012ab34e1",
"parentCallId": null,
"bridgedCallId": "665f1e2a9c4b1a0012ab34e2",
"monitorRole": null,
"record": false,
"recordingState": null,
"recordingFileIds": [],
"customData": {},
"error": null,
"startedAt": "2026-08-21T18:00:00.000000Z",
"answeredAt": "2026-08-21T18:00:12.000000Z",
"endedAt": null,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Error Codes
| Status | Code | Meaning |
|---|---|---|
| 403 | voice_not_entitled | Voice calling is not enabled for your account. |
| 404 | queue_not_found | No queue with this id exists in your account. |
| 404 | queue_empty | No callers are currently waiting in this queue. |
| 404 | agent_not_found | connectTo is an agent id that does not exist. |
| 422 | invalid_number | connectTo is not a valid E.164 number. |
| 403 | compliance_dnc / compliance_opted_out / compliance_suppressed / compliance_quiet_hours | The resolved connectTo destination is blocked by a compliance rule. |
| 429 | concurrency_limit | Your account has too many concurrent calls in progress. |
| 502 | provider_error | The upstream telephony provider rejected the request. |