curl -X POST https://api.tracklysms.com/api/v1/voice/queues \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Support",
"holdAudioUrl": "https://cdn.example.com/audio/hold.wav",
"notifyUrl": "https://hooks.example.com/voice/queue",
"notifySecret": "whsec_9f2c1a9e4b7d4c3a8e5b2f1d6c0a49387b1c2d3e4f5061728394a5b6c7d8e9f0",
"isDefault": true,
"autoAnswer": true
}'
{
"queue": {
"id": "665f1e2a9c4b1a0012ab34cd",
"name": "Support",
"holdAudioUrl": "https://cdn.example.com/audio/hold.wav",
"notifyUrl": "https://hooks.example.com/voice/queue",
"numbers": [],
"isDefault": true,
"autoAnswer": true,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Voice Calls (v1)
Create a Queue
Create a named hold queue that parks inbound callers on hold audio until an agent dequeues them.
POST
/
v1
/
voice
/
queues
curl -X POST https://api.tracklysms.com/api/v1/voice/queues \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Support",
"holdAudioUrl": "https://cdn.example.com/audio/hold.wav",
"notifyUrl": "https://hooks.example.com/voice/queue",
"notifySecret": "whsec_9f2c1a9e4b7d4c3a8e5b2f1d6c0a49387b1c2d3e4f5061728394a5b6c7d8e9f0",
"isDefault": true,
"autoAnswer": true
}'
{
"queue": {
"id": "665f1e2a9c4b1a0012ab34cd",
"name": "Support",
"holdAudioUrl": "https://cdn.example.com/audio/hold.wav",
"notifyUrl": "https://hooks.example.com/voice/queue",
"numbers": [],
"isDefault": true,
"autoAnswer": true,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Creates a named queue. A queue holds inbound callers on hold audio until an agent dequeues them and bridges the oldest waiting caller to an answerer.
Requires the
voice_calls.write scope and the Voice Calls product entitlement.
Body Parameters
string
required
A human-readable name for the queue. Must be unique within your account.
string
A public
https URL to the hold-audio file played to waiting callers. The URL’s origin must be on the platform’s configured hold-audio origin allowlist — a deployment-wide list, not per-account — or the request is rejected with hold_audio_origin_not_allowed. If no origins are configured at all, the request is rejected with hold_audio_origin_not_configured.string
Your HTTPS webhook that receives queue events. See Queue Webhooks.
string
A secret used to HMAC-sign the webhook payload delivered to
notifyUrl. Use a long, high-entropy random value — its strength is what protects your endpoint from forged events. See Queue Webhooks.boolean
default:false
Make this the account default queue for unrouted numbers.
boolean
default:true
Automatically answer inbound calls routed to this queue.
Response Fields
object
The created queue.
Hide Queue properties
Hide Queue properties
string
The queue’s unique identifier.
string
The queue name.
string | null
The hold-audio URL played to waiting callers.
string | null
The webhook that receives queue events.
array
The numbers this queue serves, in digits-only form (no leading
+). Numbers are assigned during onboarding, not through this API, so a newly created queue returns []. Request number routing from support.boolean
Whether this is the account default queue for unrouted numbers.
boolean
Whether inbound calls routed here are answered automatically.
string | null
ISO 8601 timestamp when the queue was created.
Examples
curl -X POST https://api.tracklysms.com/api/v1/voice/queues \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Support",
"holdAudioUrl": "https://cdn.example.com/audio/hold.wav",
"notifyUrl": "https://hooks.example.com/voice/queue",
"notifySecret": "whsec_9f2c1a9e4b7d4c3a8e5b2f1d6c0a49387b1c2d3e4f5061728394a5b6c7d8e9f0",
"isDefault": true,
"autoAnswer": true
}'
{
"queue": {
"id": "665f1e2a9c4b1a0012ab34cd",
"name": "Support",
"holdAudioUrl": "https://cdn.example.com/audio/hold.wav",
"notifyUrl": "https://hooks.example.com/voice/queue",
"numbers": [],
"isDefault": true,
"autoAnswer": true,
"createdAt": "2026-08-21T18:00:00.000000Z"
}
}
Error Codes
| Status | Code | Meaning |
|---|---|---|
| 403 | voice_not_entitled | Voice calling is not enabled for your account. |
| 409 | queue_exists | A queue with this name already exists in your account. |
| 422 | invalid_hold_audio_url | holdAudioUrl is not a valid URL. |
| 422 | invalid_notify_url | notifyUrl is not a valid URL. |
| 422 | hold_audio_origin_not_allowed | The holdAudioUrl origin is not on the approved-origins allowlist. |
| 422 | hold_audio_origin_not_configured | No approved hold-audio origins are configured, so holdAudioUrl cannot be accepted. |