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": [],
"numberAssignmentsApplicable": true,
"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": [],
"numberAssignmentsApplicable": true,
"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.
This endpoint does not attach phone numbers. If you supply a nonempty
numbers value, the response includes warnings: ["queue_numbers_ignored"] and does not assign them. Such requests will return 422 invalid_fields after the compatibility window closes. Empty arrays and null remain accepted.
Queue creation is an inbound workflow; it does not use optional outbound recipient screening.
Requires the voice_calls.write scope and the Voice Calls product entitlement.
Body Parameters
string
Omit this field or use
hosted for a hosted queue. Use managed for an enabled Trackly-managed queue.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 public HTTPS webhook on standard TCP port 443. Omit the port or specify
:443; HTTP, other ports, and malformed ports are rejected. 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
hosted or managed.string
The queue name.
string | null
The hold-audio URL played to waiting callers.
string | null
The webhook that receives queue events.
array
Hosted queue number assignments, in digits-only form. This list does not apply to managed queues; they return
[] and numberAssignmentsApplicable: false. Queue creation does not configure number ownership or carrier routing.boolean
Whether
queue.numbers participates in inbound routing. Managed queues return false; inbound calls use the account’s owned number and default managed queue.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.
array
Present only when a nonempty unsupported
numbers request field was ignored during the compatibility window.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": [],
"numberAssignmentsApplicable": true,
"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_fields | Once strict validation is enabled, queue creation cannot assign numbers. |
| 422 | invalid_hold_audio_url | holdAudioUrl is not a valid URL. |
| 422 | invalid_notify_url | notifyUrl is not a public HTTPS URL on TCP port 443, or has a malformed port. |
| 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. |