Voice
Call queues
Create and tune the project’s call queues — strategy, timeouts, hours, hold audio, overflow, announcements, callbacks, skill routing — and choose who answers them.
A call queue holds callers until an agent takes them: a number routed to the queue, a call flow’s enqueue, a transfer to it, a campaign feeding it. /v1/queues manages the same queues as the console’s desk settings (Queues), under the same rules, with queues:read and queues:write. Every change is audited against the key.
- GET
/v1/queuesLists call queues, newest first - POST
/v1/queuesCreates a call queue for a team - GET
/v1/queues/{queueId}Retrieves a call queue, with its members - PATCH
/v1/queues/{queueId}Changes a call queue (a `version` compare-and-set) - PUT
/v1/queues/{queueId}/membersReplaces a call queue’s members, with their tier and skill - DELETE
/v1/queues/{queueId}Deletes a call queue nothing uses
Create a queue
A queue belongs to a team, whose seats answer it: teamId must be an active team of the project (404 TEAM_NOT_FOUND otherwise) and cannot change later. Only teamId and name are required; every other setting starts at the console’s default. Names are unique in the project (409 QUEUE_NAME_TAKEN).
curl -X POST 'https://api.trovacast.com/v1/queues' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: support-queue-v1' \
-H 'Content-Type: application/json' \
-d '{
"teamId": "0f1e2d3c-4b5a-4968-8778-695a4b3c2d1e",
"name": "Support",
"strategy": "longest_idle",
"maxWaitSeconds": 240,
"announcePosition": true,
"overflowAction": "voicemail",
"overflowAfterSeconds": 180
}'{
"object": "queue",
"id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
"teamId": "0f1e2d3c-4b5a-4968-8778-695a4b3c2d1e",
"name": "Support",
"strategy": "longest_idle",
"ringTimeoutSeconds": 20,
"maxWaitSeconds": 240,
"maxSize": 50,
"wrapUpSeconds": 30,
"serviceLevelSeconds": 20,
"scheduleId": null,
"holdAudio": null,
"holdAudioAssetId": null,
"active": true,
"overflowAfterSeconds": 180,
"overflowOnNoAgents": false,
"overflowAction": "voicemail",
"overflowQueueId": null,
"overflowFlowId": null,
"announcePosition": true,
"announceWaitTime": false,
"announceEverySeconds": 60,
"callbackEnabled": false,
"requiredSkill": null,
"skillFallbackSeconds": 30,
"alertThresholds": {},
"transferBoost": true,
"members": [],
"version": 1,
"createdAt": "2026-11-06T10:00:00.000Z",
"updatedAt": "2026-11-06T10:00:00.000Z"
}Settings
| Field | What it does |
|---|---|
strategy | longest_idle (the seat idle longest), round_robin (in turn) or ring_all (every free seat at once). |
ringTimeoutSeconds | 5–120: how long a seat rings before the caller is offered on. |
maxWaitSeconds, maxSize | 10–3600 and 1–1000: the longest wait, and how many may wait at once. |
wrapUpSeconds | 0–900: a seat’s wrap-up after each call. |
serviceLevelSeconds | 5–600: the answer-time target the service level is measured against. |
scheduleId | The opening hours (a business schedule set up in the console); null for always open. |
holdAudio, holdAudioAssetId | Up to five say/play call-flow verbs looped on hold, or an uploaded hold file of the team or project. |
overflowAction | queue (overflowQueueId: a queue of the same team), flow (overflowFlowId: a published call flow) or voicemail; null turns overflow off. With overflowAfterSeconds (5–3600) and overflowOnNoAgents. |
announcePosition, announceWaitTime | Tell waiting callers their place and the expected wait, every announceEverySeconds (20–600). |
callbackEnabled | Offer “press 1 to be called back”: a callback task in the console instead of waiting. |
requiredSkill, skillFallbackSeconds | Offer callers only to members at or above this skill (1–10) for the first 0–3600 seconds, then to anyone. |
alertThresholds | Supervisor alerts on the live desk: longestWaitSeconds, waitingCallers, serviceLevelBelowPercent, agentsAvailableBelow. null or {} clears them. |
transferBoost | A caller an agent transfers in waits ahead of new callers (default on). |
active | Off, the queue takes no callers (a transfer to it is 409 QUEUE_CLOSED). |
A value out of range, or a reference that is not this project’s — an unknown schedule, an overflow queue of another team, a flow or hold audio of another project — is 400 VALIDATION_FAILED, exactly as the console refuses it. Another project’s queue is 404 QUEUE_NOT_FOUND, as is a queue of a deactivated team.
Change a queue
PATCH changes only the fields you send, under the version you read: if the queue changed since, it is 409 QUEUE_VERSION_CONFLICT — read it again and retry. Every change bumps version.
curl -X PATCH 'https://api.trovacast.com/v1/queues/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 1,
"requiredSkill": 7,
"skillFallbackSeconds": 45
}'Members
PUT /v1/queues/{queueId}/members replaces the whole list. Each member is an organization seat (membershipId) with a priority tier (1–10, default 1: lower tiers are offered a caller first) and a skill level (1–10, default 5). Every seat must be an active seat on the queue’s team; a duplicate or a stranger is 400 and nothing changes. Send the queue’s version too, so a list someone else just saved is not overwritten (409 QUEUE_VERSION_CONFLICT). Members are named by seat id only — the API never returns a person’s name.
curl -X PUT 'https://api.trovacast.com/v1/queues/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d/members' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 2,
"members": [
{
"membershipId": "6c5b4a39-2817-4f6e-9d5c-4b3a29180716",
"priority": 1,
"skill": 8
},
{
"membershipId": "7d6c5b4a-3928-4170-8e6d-5c4b3a291807",
"priority": 2,
"skill": 5
}
]
}'Delete a queue
DELETE removes a queue nothing uses. While a number routes to it, a campaign feeds it, a caller waits in it or another queue overflows into it, it is 409 QUEUE_IN_USE — move those first.
Test keys
A test key reads queues; every write is 422 TEST_MODE_UNSUPPORTED. Queues have no test partition: a change would reach live callers.
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
QUEUE_IN_USE | 409 | The queue cannot be deleted while a number routes to it, a campaign feeds it, a caller waits in it or another queue overflows into it. See Call queues.What to do: Move those first — route its numbers elsewhere (PATCH /v1/numbers/{numberId}), point other queues’ overflow away from it, let waiting callers be served — then delete it again. |
QUEUE_NAME_TAKEN | 409 | Another call queue of the organization already has that name.What to do: Choose another name, or change the existing queue instead (PATCH /v1/queues/{queueId}). |
QUEUE_NOT_FOUND | 404 | A transfer’s to.queueId names no call queue of this organization. Nothing changed on the call. On /v1/queues/{queueId}: no queue of this organization (with an active team) has that id. See Call queues.What to do: Pass a queueId from GET /v1/queues. |
QUEUE_VERSION_CONFLICT | 409 | The queue changed since the version you sent (its settings or its members).What to do: Read it again with GET /v1/queues/{queueId} and retry with its new version. |
TEAM_NOT_FOUND | 404 | teamId on POST /v1/queues names no active team of this organization. Nothing was created. See Call queues.What to do: Pass the id of an active team of the organization — the teamId of a queue GET /v1/queues lists is one. |
TEST_MODE_UNSUPPORTED | 422 | A test-mode key (tc_test_…) cannot perform this: either it has no sandbox — managing templates, the WhatsApp account or email domains, writing broadcasts, renting numbers — or it would read or change live data: a recording, a contact export, consent, changing or erasing an existing contact, or changing live call flows, applications and AI agents. (A live customer’s conversation, or a live message to quote or react to, is not refused but not found: 404.) See Authentication.What to do: Repeat the request with a live key (tc_live_…); no test key can do it. In test mode, work on the test records your test key created instead. |
VALIDATION_FAILED | 400 | The request is malformed; message lists each problem. Also a bulk webhook resend whose until is not after since.What to do: Correct every problem message lists, then send the request again; the same body fails the same way. The API reference has each endpoint's fields. |