Trovacast

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.

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).

Create a queue
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
}'
201 (json)
{
  "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

FieldWhat it does
strategylongest_idle (the seat idle longest), round_robin (in turn) or ring_all (every free seat at once).
ringTimeoutSeconds5–120: how long a seat rings before the caller is offered on.
maxWaitSeconds, maxSize10–3600 and 1–1000: the longest wait, and how many may wait at once.
wrapUpSeconds0–900: a seat’s wrap-up after each call.
serviceLevelSeconds5–600: the answer-time target the service level is measured against.
scheduleIdThe opening hours (a business schedule set up in the console); null for always open.
holdAudio, holdAudioAssetIdUp to five say/play call-flow verbs looped on hold, or an uploaded hold file of the team or project.
overflowActionqueue (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, announceWaitTimeTell waiting callers their place and the expected wait, every announceEverySeconds (20–600).
callbackEnabledOffer “press 1 to be called back”: a callback task in the console instead of waiting.
requiredSkill, skillFallbackSecondsOffer callers only to members at or above this skill (1–10) for the first 0–3600 seconds, then to anyone.
alertThresholdsSupervisor alerts on the live desk: longestWaitSeconds, waitingCallers, serviceLevelBelowPercent, agentsAvailableBelow. null or {} clears them.
transferBoostA caller an agent transfers in waits ahead of new callers (default on).
activeOff, 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.

Route by skill
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.

Set the members
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

CodeStatusMeaning and what to do
QUEUE_IN_USE409The 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_TAKEN409Another 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_FOUND404A 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_CONFLICT409The 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_FOUND404teamId 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_UNSUPPORTED422A 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_FAILED400The 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.