Voice
Calls
Place a phone call and choose what runs it: your own agent over a WebSocket, a call flow, one of your AI agents, or a bridge to a number or a person.
You ask for a call; Trovacast dials the contact and, when they answer, hands the conversation to what mode names: your own agent over a WebSocket (EXTERNAL_AGENT), a call flow or a voice application (FLOW), one of your AI agents (AI_AGENT), or a bridge to a number or an agent’s softphone (BRIDGE, click-to-call). Once it is answered you can act on it — speak, gather keys, hold, transfer — with Call control.
Calls need four scopes: calls:write to place and end them, calls:read to read and list them and the channels, recordings:read for a recording’s download link and recordings:write to erase recordings. Dialling a number that is not yet a contact also needs contacts:write.
- POST
/v1/callsPlaces a call run by your agent’s stream, a call flow, an AI agent, or bridged to a number or agent - GET
/v1/callsLists calls newest first, or — with updatedAfter — every change since, oldest first - GET
/v1/calls/channelsLists the channels a call can be placed over, and which one is the default - GET
/v1/calls/{callId}Retrieves a call - POST
/v1/calls/{callId}/hangupEnds a live call - GET
/v1/calls/{callId}/recordingMints a download link to a call’s recording - DELETE
/v1/calls/{callId}/recordingPermanently erases a call’s recordings
Place a call
POST /v1/calls takes the contact — exactly one of contactId or to.phone — the mode, the block that mode needs (agent, flow, aiAgent or bridge, and no other), recording and maxDurationSec. A request missing one, or naming a block of another mode, is 400 VALIDATION_FAILED and dials nothing. This page’s example is a call to your own agent; the other modes are below.
curl -X POST 'https://api.trovacast.com/v1/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: call-order-1042' \
-H 'Content-Type: application/json' \
-d '{
"mode": "EXTERNAL_AGENT",
"to": {
"phone": "+919876543210"
},
"agent": {
"streamUrl": "wss://agent.example.com/trovacast/stream",
"token": "AGENT_STREAM_TOKEN",
"audio": {
"encoding": "pcm_s16le",
"sampleRate": 16000
}
},
"recording": {
"enabled": true,
"consentEvidence": {
"source": "VERBAL",
"text": "This call is recorded for quality and training.",
"capturedAt": "2026-11-05T09:30:00.000Z"
}
},
"maxDurationSec": 900,
"metadata": {
"orderId": "1042"
}
}'mode—EXTERNAL_AGENT: Trovacast dials and your server runs the conversation (other modes).purpose— what the call is for under India’s TRAI/DLT rules:SERVICE,TRANSACTIONALorPROMOTIONAL, checked before the dial. A promotional call needs one of your assigned 140-series numbers asfrom, a verified voice DLT header and the 09:00–21:00 window in the called party’s zone; a 140-seriesfromis for promotional calls only. Omitted: undeclared (never read as promotional).to.phone— the number in international format. A number that is not yet a contact creates one (and then needscontacts:write). Or name an existing contact withcontactId.agent.streamUrl— a publicwss://URL, checked when the call is requested and again when the socket connects (422 AGENT_STREAM_URL_INVALIDotherwise).agent.tokenis sent asAuthorization: Bearer <token>on the upgrade; it is stored sealed and never returned.agent.audiois{ "encoding": "pcm_s16le", "sampleRate": 16000 }.maxDurationSec— the hard ceiling on the conversation, from the moment your stream opens (for the other modes, from the moment the call’s audio connects): at least 30 seconds, up to the deployment’s bound (3,525 seconds by default).provider— which channel to dial over, asGET /v1/calls/channelsnames it. Omitted: the organization’s default channel for machine-placed calls.ringTimeoutSec— how long the phone rings (5–120 seconds, carrier permitting).respectCallingWindow— on by default: the call is placed only inside the calling window (09:00–21:00 in the organization’s time zone unless the deployment sets another).metadata— your own identifiers (string values), echoed on the call, its webhooks and the stream’sstartframe. It is stored unencrypted: never put personal data in it.
The 201 is the call: initiating once the carrier accepted the dial, or queued when the carrier has not confirmed it yet. A queued call is never dialled again for you; what happens next arrives as events. The call never carries the contact’s number — it names contactId.
{
"object": "call",
"id": "CALL_ID",
"contactId": "CONTACT_ID",
"direction": "outbound",
"mode": "external_agent",
"status": "initiating",
"from": "+918031152580",
"fromSource": "organization_number",
"recordingEnabled": true,
"agent": {
"streamUrl": "wss://agent.example.com/trovacast/stream",
"maxDurationSec": 900,
"audio": {
"encoding": "pcm_s16le",
"sampleRate": 16000
}
},
"metadata": {
"orderId": "1042"
},
"purpose": null,
"parentCallId": null,
"rootCallId": null,
"legRole": "primary",
"aiAgentId": null,
"flow": null,
"bridge": null,
"createdAt": "2026-11-05T10:00:00.000Z",
"updatedAt": "2026-11-05T10:00:00.000Z"
}Other modes
| `mode` | Block | What runs the call |
|---|---|---|
FLOW | flow: exactly one of definition (an inline document, validated before the dial), callFlowId (a stored flow’s published version) or applicationId (a voice application’s answer URL; answerUrl asks another URL on the same origin first) | A call flow or your answer URL. The call reads mode: "flow" with flow: { source, callFlowId, applicationId }. |
AI_AGENT | aiAgent: agentId, optional objective | One of your AI agents. The call reads mode: "ai" with aiAgentId. |
BRIDGE | bridge: to (exactly one of number or agentMembershipId), ringFirst (contact default, or agent), prompt, whisper, noAnswerMessage, ringTimeoutSec | By default the contact is dialled first, then connected to the number or the agent’s softphone (click-to-call). With ringFirst: agent the agent’s own phone rings first and the contact is dialled once they answer — see below. The call reads mode: "bridge" with bridge: { target, numberLast4, agentMembershipId, ringFirst } — never the number. |
curl -X POST 'https://api.trovacast.com/v1/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: reminder-order-1042' \
-H 'Content-Type: application/json' \
-d '{
"mode": "FLOW",
"contactId": "CONTACT_ID",
"flow": {
"callFlowId": "CALL_FLOW_ID"
},
"purpose": "TRANSACTIONAL",
"recording": {
"enabled": false
},
"maxDurationSec": 300
}'FLOW and BRIDGE need a channel that streams the call into Trovacast (flows: true in GET /v1/calls/channels; elsewhere 422 CHANNEL_UNSUPPORTED). Everything else on this page — the checks, billing, exactly-once, events — applies to every mode. A flow or application that is not yours, not published or not valid is refused before the dial (404 CALL_FLOW_NOT_FOUND, 409 CALL_FLOW_NOT_PUBLISHED, 422 CALL_FLOW_INVALID with issues, 404 APPLICATION_NOT_FOUND, 422 ANSWER_URL_INVALID), as is an AI agent (404 AI_AGENT_NOT_FOUND, 409 AI_AGENT_INACTIVE) or a bridge target (404 BRIDGE_AGENT_NOT_FOUND, 422 CHILD_DIAL_DESTINATION_NOT_ALLOWED).
Recording and consent evidence
Recording follows the organization’s call policy. A new organization records every call, so every request needs recording.consentEvidence — the text the contact saw or heard, when they consented and how (WEB_FORM, WRITTEN, VERBAL or OTHER) — even with recording.enabled: false. Without it the call is 409 RECORDING_CONSENT_REQUIRED. The evidence is stored encrypted on the call; capturedAt may not be in the future.
Once an administrator turns “record every call” off, the request decides: recording.enabled: false places an unrecorded call with no evidence, and recording.enabled: true still needs it.
Caller ID
from sets the number the contact sees: one of the organization’s own voice-capable numbers on the call’s channel, in international format. It is accepted only on a channel whose callerIdSelection is true — one that publishes the organization’s numbers, so Trovacast can check the number is theirs. A number that is not is 422 CALLER_ID_NOT_OWNED; from on any other channel is 422 CALLER_ID_UNSUPPORTED (it is never passed through unchecked). When the carrier cannot answer for its inventory right now the request is 503: retry. **Without from** the call presents one of your own numbers on the channel — an assigned, outbound-capable one of a series the call may present (a 140-series number for a PROMOTIONAL call only), one in the contact’s own country first (the same country calling code — a +91 number for an Indian contact, however old your +1 one), then the oldest — with its numberId; only when you hold none there does the channel’s own caller ID apply (your carrier account’s, else the platform’s shared number, which a contact cannot call you back on). fromSource on the call and every call.* event says which it was: request, organization_number, agent_number, carrier_account or platform.
Choose a channel
GET /v1/calls/channels lists the channels a call may name, with what each can do for this organization. ready: false is what 409 CHANNEL_NOT_CONFIGURED (or 422 CHANNEL_UNSUPPORTED) would answer.
curl 'https://api.trovacast.com/v1/calls/channels' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"data": [
{
"object": "call_channel",
"provider": "plivo",
"label": "Plivo",
"default": true,
"externalAgent": true,
"ready": true,
"callerIdSelection": true,
"remoteHangup": true,
"machineDetection": true,
"sensitiveGather": false,
"flows": true
}
]
}| Flag | Means |
|---|---|
provider | The value POST /v1/calls takes as provider. |
default | Where a call that names no provider dials for this organization. |
externalAgent | The channel can stream a call to your agent. |
ready | A call can be placed on it now: it is set up for the organization and everything the deployment needs is in place. |
callerIdSelection | The request may name from. |
remoteHangup | The carrier ends a call on request, ringing or answered. Without it, a hang-up closes the call’s stream, so a call not yet answered may be 409 HANGUP_NOT_READY until it is. |
machineDetection | The channel can tell an answering machine from a person: the request may send machineDetection (below). Plivo, Twilio and Telnyx can; Airtel and Exotel cannot (422 MACHINE_DETECTION_UNSUPPORTED). |
sensitiveGather | A sensitive gather can run on the channel’s recorded calls: the carrier pauses its own recording for it (Live call control). Twilio and Telnyx can; Plivo, Exotel and Airtel cannot (409 RECORDING_NOT_CONTROLLABLE on a recorded call). |
flows | The channel can carry mode: FLOW and mode: BRIDGE (it streams the call into Trovacast). |
Answering-machine detection
On a channel whose machineDetection is true, POST /v1/calls may ask the carrier to tell an answering machine from a person once the call is answered. detect: the call goes ahead, and the verdict arrives as call.machine_detected — the call’s machineDetection.result is human, machine or unknown (the carrier could not tell). detect_and_hangup: the carrier ends a call a machine answered. Elsewhere the request is 422 MACHINE_DETECTION_UNSUPPORTED and nothing is dialled. A test-mode key’s call sandbox detects nothing.
curl -X POST 'https://api.trovacast.com/v1/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: bridge-order-1042' \
-H 'Content-Type: application/json' \
-d '{
"mode": "BRIDGE",
"to": {
"phone": "+919876543210"
},
"bridge": {
"to": {
"number": "+918031150000"
}
},
"provider": "plivo",
"machineDetection": "detect",
"recording": {
"enabled": false
},
"maxDurationSec": 600
}'The call carries machineDetection: { mode, result, detectedAt } from the start (result null until the verdict); a call that did not ask carries null.
Statuses and endings
A call moves queued (created, not yet accepted by the carrier) → initiating (accepted) → ringing → in_progress → ending → completed; or ends busy, no_answer, cancelled or failed, with failure: { code, reason }. A call whose flow failed carries a FLOW_* failure whatever its status — it was answered, so it usually reads completed — and call.flow.failed says so as it happens.
| `failure.code` | Status | Meaning |
|---|---|---|
NO_ANSWER / BUSY / CANCELLED | no_answer / busy / cancelled | The contact did not answer, the line was busy, or the call was ended before it was answered. |
FAILED | failed | The call failed and the carrier gave no cause. |
PROVIDER_REJECTED | failed | The carrier refused to place the call. |
PROVIDER_RATE_LIMITED | failed | The carrier was rate-limiting calls; nothing was dialled. |
SUBMISSION_UNKNOWN | failed | The carrier never confirmed the dial; it was not retried, to avoid ringing the contact twice. |
WATCHDOG_EXPIRED | failed | The carrier never reported the outcome and Trovacast closed the call, hanging up its line and legs (four hours after answer, or — on a carrier that cannot be polled — 375 seconds past the call’s own maxDurationSec; a supervisor clearing a stuck seat closes it the same way). Billed for the time known: up to its ceiling when it passed it, otherwise from answer to close, capped at its ceiling or the deployment’s limit. A stuck call a supervisor cleared because it went silent is billed from answer to its last sign of life plus 60 seconds, capped at its ceiling; one cleared past its ceiling, to its ceiling. |
MEDIA_STREAM_FAILED | failed | The carrier answered but the call’s audio never reached Trovacast. |
MEDIA_OWNER_LOST | failed | The server carrying the call’s audio stopped during the call, and Trovacast ended it once its audio had been silent for 90 seconds; it is rated up to the last moment its audio was heard. |
DESTINATION_BLOCKED, HANDOFF_TIMEOUT, AI_PROVIDER_UNAVAILABLE | failed | A blocked destination, a hand-off to an agent that timed out, an AI agent whose voice provider was down (answered with no AI voice, it is charged at the manual rate). |
BILLING_* | failed | An inbound call Trovacast refused: your plan does not price the calls the number’s route answers, or the wallet cannot pay for one. The caller heard a short apology; nothing was charged. The number’s warnings say so ahead of any call. |
AI_AGENT_UNAVAILABLE | failed | An inbound call to a number routed to an AI agent that could not answer: the agent is switched off or archived, it is a test agent (a live call never runs one), AI calls are switched off for the organization, or its voice cannot run here (availability.runnable: false — the number’s warnings say so first, AI_PROVIDER_UNAVAILABLE). The caller heard a short apology. |
<CARRIER>_… | failed | A carrier’s own cause (PLIVO_STREAM_SESSION_EXPIRED, TWILIO_ANSWERING_MACHINE, …), explained in plain language. |
FLOW_CONNECT_FAILED | any | The party a connect (or a BRIDGE) dials could not be dialled; call.flow.failed names the refusal (flow.cause). |
FLOW_TTS_UNAVAILABLE / FLOW_AUDIO_UNAVAILABLE | any | Text to speak on a deployment with no speech synthesis (only from an application’s run-time instructions — a stored flow or a definition that speaks is refused when saved or placed); audio that could not be fetched or played. |
FLOW_APPLICATION_UNREACHABLE / _INVALID / _NOT_FOUND | any | The application’s answer URL could not be reached, answered instructions that do not validate, or no longer exists. |
FLOW_MEDIA_NOT_CONNECTED / FLOW_MEDIA_UNAVAILABLE | any | The call’s audio never reached Trovacast, or stopped while the flow ran. |
FLOW_STEP_LIMIT / FLOW_LOOP_LIMIT / FLOW_INVALID_BRANCH / FLOW_INVALID_REDIRECT | any | The flow ran too many steps, looped, or branched somewhere it cannot go. |
FLOW_INVALID / FLOW_NOT_PUBLISHED / FLOW_ERROR | any | The flow no longer validates, has no published version, or stopped on an unexpected error. |
An ended call carries hangup: { side, reason }. side is agent (your hangup frame, or POST /v1/calls/{callId}/hangup; also a person in the console: an agent hanging up, reason agent-hangup, or a supervisor’s End call, reason supervisor-end), application (the call’s own instructions: a flow’s or answer URL’s hangup verb, the instructions running out, an ai step’s agent finishing), contact (the caller left while a flow ran), platform (the ceiling, a lost agent or a failed flow) or unknown — only what Trovacast recorded is reported, so a carrier ending nothing recorded is unknown, never assumed to be the contact. reason is api-hangup, agent-hangup, supervisor-end, hangup, max_duration, agent_lost, hangup_verb, instructions_ended, ai_ended, callback_requested, flow_failed or caller_hung_up when Trovacast knows it.
A call’s timeline
GET /v1/calls/{callId}/events (calls:read) answers what happened on a call, oldest first, paged with limit and cursor like every list. Each entry has a type, occurredAt, a rising sequence, and data carrying only what its type names. Nothing personal or private is on it: no transcript text, no digits pressed, no secrets, and a transfer number masked to its last four digits. Flow outcomes, AI admissions, recording pauses and the ceiling are kept from 2026-11-07.
A test call has the timeline a live call of its mode has, as the call sandbox walks it: created, queued, ringing, answered and ended (a busy, unanswered or failed test number without the steps it never reached) — and each action taken on it writes what the same action writes on a live call, in the transaction that fires its webhook: held and resumed (resume is refused 409 CALL_NOT_HELD when the caller is not on hold); a transfer to a number the caller held, the target’s leg.joined and resumed (leg.left once the call ends; the sandbox dials no leg, so childCallId is null); a transfer to a queue transfer.started, transfer.ringing and queue.entered (queue.left and transfer.failed when the caller hangs up waiting) — or, to a queue nobody staffs (2026-11-07), no queue.entered, as live, and transfer.failed (NO_AGENTS) when the call ends or another transfer takes the caller; a recording pause and resume. A gather, speak or play writes no entry on any call. The sandbox runs no flow and connects no AI, so there are no flow or AI steps (nor the voicemail a live caller gets from a queue nobody staffs); a test call talks for 3 s, under the lowest ceiling, so it never reaches one; and it is never rated, so there is no rated entry.
| `type` | `data` | When |
|---|---|---|
created, queued, ringing, answered | — | The call was written, the carrier has the dial (outbound), it rang, it was answered. |
ended | status, failure | The call ended, as the call reads. |
flow_step.started | step, node, verb | A step of its flow began. |
flow_step.ended | step, node, verb, outcome, fallback, code, nextNode | What an ai, connect, enqueue, gather, menu or hours step came to; fallback: true when it took its failure path, code the reason. |
ai_step.admitted, ai_step.refused | step, node, agentId; code when refused | The AI agent took the caller, or the step was refused first (AI_PROVIDER_UNAVAILABLE, AI_AGENT_UNAVAILABLE, AI_CALLS_DISABLED, a BILLING_… code). |
held, resumed, queue.*, transfer.*, leg.joined, leg.left | ids, transferType, target, masked to, code | Hold, queue waits, transfers and the legs that joined and left — a leg still on when the call ends leaves with it (2026-11-07). |
recording.paused, recording.resumed | by, recording | A manual pause, by your key (api) or the agent (desk). |
transcription.unavailable, transcription.recovered | phase | The speech-to-text was lost, and came back. |
ceiling.reached | maxDurationSeconds | The call ran to its own ceiling. |
rated | charge | The call’s charge — with its rule and reason, why it was rated as it was — always the last entry, once rated. |
curl 'https://api.trovacast.com/v1/calls/CALL_ID/events' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"data": [
{
"object": "call_timeline_event",
"id": "EVENT_ID_1",
"callId": "CALL_ID",
"sequence": 4,
"type": "flow_step.started",
"occurredAt": "2026-11-10T09:30:02.010Z",
"data": {
"step": 2,
"node": "main",
"verb": "ai"
}
},
{
"object": "call_timeline_event",
"id": "EVENT_ID_2",
"callId": "CALL_ID",
"sequence": 5,
"type": "ai_step.refused",
"occurredAt": "2026-11-10T09:30:02.042Z",
"data": {
"step": 2,
"node": "main",
"agentId": "AGENT_ID",
"code": "AI_PROVIDER_UNAVAILABLE"
}
},
{
"object": "call_timeline_event",
"id": "EVENT_ID_3",
"callId": "CALL_ID",
"sequence": 6,
"type": "flow_step.ended",
"occurredAt": "2026-11-10T09:30:02.044Z",
"data": {
"step": 2,
"node": "main",
"verb": "ai",
"outcome": "failed",
"fallback": true,
"code": "AI_PROVIDER_UNAVAILABLE",
"nextNode": "human"
}
},
{
"object": "call_timeline_event",
"id": "EVENT_ID_4",
"callId": "CALL_ID",
"sequence": 7,
"type": "flow_step.started",
"occurredAt": "2026-11-10T09:30:02.051Z",
"data": {
"step": 3,
"node": "human",
"verb": "enqueue"
}
}
],
"nextCursor": null
}While the call is live the last page ends with what has happened so far: read it again for what follows. A call of the other mode — a live call to a test key, a test call to a live key — is 404, exactly as an unknown id. v1 adds types over time: skip one you do not know.
What is checked, in order
A refused call dials nothing. The checks run in this order, so the first rule a request breaks is the one it hears about:
| Code | Status | Meaning |
|---|---|---|
VALIDATION_FAILED | 400 | A required field is missing or malformed, two recipients or none, maxDurationSec above the deployment’s bound, consent captured in the future, bad metadata. |
ENTITLEMENT_CALLING_DISABLED | 403 | The organization does not have calling. |
API_KEY_SCOPE_MISSING | 403 | to.phone without contacts:write. |
AGENT_STREAM_URL_INVALID | 422 | streamUrl is not a public wss:// URL (reason). |
DESTINATION_BLOCKED | 422 | The number is in a country code your organization may not call — anywhere outside the home market (+91) and what the platform opened for you; +1 (North America) on every path unless opened (GET /v1/settings/destinations). |
DESTINATION_ACKNOWLEDGEMENT_REQUIRED | 422 | +1 is opened for you but your organization has not acknowledged the TCPA statement in the console. |
CONTACT_DO_NOT_CALL / CONTACT_OPTED_OUT | 409 | The contact is on the do-not-call list, or opted out of calls. |
CONTACT_PHONE_REQUIRED | 422 | The contact has no phone number. |
CALLING_WINDOW_CLOSED | 409 | Outside the calling window; the body carries nextAllowedAt, timeZone and window. |
RECORDING_CONSENT_REQUIRED | 409 | The call would be recorded and carries no consentEvidence. |
AI_CALLS_DISABLED | 409 | The organization’s call policy turns machine-run calls off. |
CHANNEL_NOT_CONFIGURED | 409 | The channel is not one this deployment runs, or is not set up for the organization (provider). |
CHANNEL_UNSUPPORTED | 422 | The channel cannot carry a call to your agent. |
CALLER_ID_UNSUPPORTED | 422 | from on a channel that cannot check a chosen caller ID. |
CALLER_ID_NOT_OWNED | 422 | from is not a voice-capable number the organization owns on the channel. |
MACHINE_DETECTION_UNSUPPORTED | 422 | machineDetection on a channel that cannot detect an answering machine (machineDetection: false). |
SERVICE_UNAVAILABLE | 503 | The channel is temporarily unavailable on this deployment. Retry later. |
CALL_CONCURRENCY_LIMIT | 429 | Over the organization’s or the key’s live-call cap (scope, limit, liveCalls). |
BILLING_INSUFFICIENT_CREDIT | 402 | The balance cannot cover the call’s ceiling beside the API calls already in flight (minutesRequired, balanceMinor, ratePerMinuteMinor, includedMinutesRemaining). |
BILLING_SUBSCRIPTION_PAST_DUE / _SUSPENDED / _CANCELED | 402 | The subscription does not allow calling. |
BILLING_RATE_UNAVAILABLE | 503 | The plan does not price this channel. |
DESTINATION_NOT_PRICED | 422 | A destination opened beyond the default has no rate of its own on your plan. |
DESTINATION_CALLING_WINDOW_CLOSED | 409 | A +1 call outside the TCPA window in the called party’s local time (nextAllowedAt) — whatever respectCallingWindow says. |
MEDIA_CAPACITY / MEDIA_DRAINING | 503 | The server that would carry the call’s stream is full, or restarting; nothing rang. Retry shortly with the same Idempotency-Key. |
CARRIER_REJECTED | 502 | The carrier refused the dial; nothing rang. The call exists as failed (callId). |
CARRIER_RATE_LIMITED | 429 | The carrier is throttling dials; nothing rang (callId, retryAfterSeconds, also Retry-After). |
The calling window is evaluated in the called party’s local time when their number is outside India — in the zone you state for them (calledPartyTimeZone), else every zone a +1 number’s area code serves, else every time zone of their country — and in the organization’s time zone otherwise. There is no DND registry scrub on the platform yet: calls into India are only as clean as each contact’s own consent and do-not-call state.
Where your calls may reach
By default your calls reach the home market only — India (+91, defaultCountryCodes) — and a leg dialled from a live call — a transfer to a number, a conference party, a BRIDGE number — may go to India (+91) only; any other country is refused with DESTINATION_BLOCKED, and +1 (North America) is blocked on every path. The platform can open another country, +1, or more destinations for those legs, for your organization; anything opened beyond the home market must be priced on your plan with a rate of its own (DESTINATION_NOT_PRICED otherwise — never the standard home rate), and +1 also needs your organization’s TCPA acknowledgement (the Destinations section of the console’s calling policy). GET /v1/settings/destinations (settings:read) says where you may dial right now.
curl 'https://api.trovacast.com/v1/settings/destinations' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "destination_settings",
"defaultCountryCodes": [
"91"
],
"blockedCountryCodes": [],
"openedCountryCodes": [
"1",
"44"
],
"childLegPrefixes": [
{
"prefix": "+91",
"needsRate": false
},
{
"prefix": "+44",
"needsRate": true
}
],
"tcpa": {
"required": true,
"acknowledged": true,
"acknowledgedAt": "2026-11-05T10:00:00.000Z",
"statementVersion": "2026-11-05",
"currentStatementVersion": "2026-11-05",
"callingWindow": {
"start": "08:00",
"end": "21:00",
"days": []
}
}
}Ring the agent first (click-to-call)
A BRIDGE to an agent with ringFirst: agent rings the agent’s own phone first; once they answer, the contact is dialled and bridged in, and the agent hears ringback meanwhile. It is one manual call assigned to that agent — they cannot be rung for another meanwhile — and every rule a dial meets is asked of the contact before anything rings. It needs a channel that bridges two phone legs (agentFirst: true in GET /v1/calls/channels) and a phone on file for the agent (422 AGENT_PHONE_REQUIRED). Nothing is spoken by the platform on it, so prompt, whisper, noAnswerMessage and machineDetection are refused with it.
curl -X POST 'https://api.trovacast.com/v1/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: click-to-call-1042' \
-H 'Content-Type: application/json' \
-d '{
"contactId": "8f6a2b1c-3d4e-4f5a-9b6c-7d8e9f0a1b2c",
"mode": "BRIDGE",
"bridge": {
"to": {
"agentMembershipId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
},
"ringFirst": "agent"
},
"recording": {
"enabled": false
},
"maxDurationSec": 1800
}'Exactly once
Send an Idempotency-Key on every attempt. POST /v1/calls is re-runnable: a retry with the same key and body first looks for the call that key placed and answers it (201, its current state) before any rule is asked again — so a retry after a 500 that came once the carrier had accepted the dial gets that call, never a second dial, even after the 24-hour idempotency window. Only when the carrier definitely dialled nothing (502 CARRIER_REJECTED, 429 CARRIER_RATE_LIMITED) does a retry under the same key dial afresh. A dial whose submission is unknown keeps its call: the retry answers it (queued) rather than risk ringing the contact twice.
A different body under the same key is 422 IDEMPOTENCY_KEY_REUSED. Without an Idempotency-Key, a retried request is a second call.
Limits and billing
- Live calls. An organization may hold 10 live API calls at once, all keys together, and one key 10 of them, unless the deployment sets other caps. A call is live from
queueduntil it ends. Over either cap is429 CALL_CONCURRENCY_LIMIT; place the call when another ends. Test-mode calls are counted apart: they never count against these caps, and live calls never count against the sandbox’s own cap of 10 test calls at once (the same429, withlivemode: false). - Credit. A call is priced, before it is dialled, for what the carrier could bill it for:
maxDurationSecplus the 75 seconds the carrier’s own time limit sits past it, in started minutes —ceil((maxDurationSec + 75) / 60), so 900 seconds is 17 minutes — beside what the organization’s live API calls already in flight can still run to, each from its ownmaxDurationSecat its own rate (aFLOWorBRIDGEcall at the manual rate, an AI or external-agent call at the AI rate), less what an answered one has used. Test calls are never priced. Included plan minutes pay first; the prepaid balance must cover the rest, or the call is402 BILLING_INSUFFICIENT_CREDITwithminutesRequiredandinFlightMinutes— andmaxDurationSecAvailable, the longestmaxDurationSecthat would be placed now, when a shorter call would fit at all. - Rating. Every call that ends is charged per started minute, as described on Pricing.
The agent stream
When the contact answers, Trovacast opens one WebSocket per call to agent.streamUrl, with Authorization: Bearer <agent.token>. Frames are JSON text. Audio is PCM16 little-endian mono at 16 kHz, base64-encoded, whatever the carrier carries — Trovacast transcodes.
Trovacast to your agent
{ "event": "start", "callId", "to": { "phone", "last4" }, "provider", "audio": { "encoding": "pcm_s16le", "sampleRate": 16000, "frameMs": 20 }, "metadata", "resumed" }
{ "event": "media", "seq", "tsMs", "payload" }
{ "event": "dtmf", "digit" }
{ "event": "mark", "name" }
{ "event": "stop", "reason" }start—to.last4is always the last four digits of the number dialled.to.phoneis the full number only when your request dialled it by number (to.phone), echoing what you sent; for a call placed bycontactIdit isnull.resumedistrueon a stream that continues the call after the carrier’s media leg dropped and was redialled.media— the contact’s audio in 20 ms (640-byte) frames.seqandtsMskeep counting across frames that had to be dropped, so a gap inseqis audio you did not get.dtmf— a key the contact pressed.mark— a mark you sent has finished playing.stop— the stream is ending, with a reason (below).
| `stop` reason | Meaning |
|---|---|
completed | The carrier ended the call normally: the contact hung up. |
hangup | Your side ended it: POST /v1/calls/{callId}/hangup, or the answer to your own hangup frame. |
max_duration | The call reached maxDurationSec. |
carrier_reconnecting | The carrier’s media leg dropped and the call is held up to 45 seconds for the carrier’s redial: a new connection with start.resumed: true and the same callId follows — or nothing, and the call’s events say how it ended. |
carrier_closed | The carrier’s media leg dropped for good. |
platform_closed | Trovacast ended it (a shutdown drain, an operator, a watchdog closing the stream). |
agent_lost is never sent — by then your socket is gone — but it is the call’s hangup.reason when Trovacast gave up on your stream.
Your agent to Trovacast
{ "event": "media", "payload" }
{ "event": "mark", "name" }
{ "event": "clear" }
{ "event": "hangup", "reason" }media— audio to play to the contact, any even length up to about six seconds a frame. Audio plays at real time and you may send up to 30 seconds ahead of it; a frame that would queue more is dropped silently (marks follow only what was accepted), so stream at about real time, or sendclearbefore a new turn.mark— named marker: you get amarkback when the audio before it has played.clear— drop queued playback (barge-in).hangup— end the call.
Keeping the stream healthy
- Liveness is the WebSocket ping alone: a ping every 10 seconds, and a ping with no pong by the next one is a lost agent. Sending frames does not keep alive a stream that answers no ping.
- Backpressure. Past about 256 KB queued on your socket (some six seconds of audio) the contact’s audio is dropped rather than buffered — the
seqgap shows it — and a socket that stays that congested for 10 seconds is a lost agent. - Loss. If the socket cannot be opened, is refused, drops or is lost as above, the contact hears a short apology and the call is hung up with
hangup.side: "platform"— never a silent line. - Ceiling. The conversation ends at
maxDurationSecfrom the moment your stream first opened (stopwithmax_duration, then the hang-up). A resumed stream keeps the original deadline. - Malformed frames are dropped. Audio, tokens and full numbers are never logged.
Hang up
POST /v1/calls/{callId}/hangup answers 200 with the call as ending once the line is being ended; a call already over is returned as it stands. A call that can be ended but not yet — the carrier has not answered the dial with the id it is ended by, or, on a channel without remoteHangup, the contact has not answered — is 409 HANGUP_NOT_READY: retry after Retry-After. 503 HANGUP_FAILED means the line may still be up: retry, with the same Idempotency-Key if you sent one (the endpoint runs again rather than replaying the error).
curl -X POST 'https://api.trovacast.com/v1/calls/CALL_ID/hangup' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: hangup-order-1042'Your side is recorded on the call before the carrier is asked, so call.completed says hangup: { side: "agent", reason: "api-hangup", apiKeyId } even when the carrier’s own callback wins the race, and your agent hears stop with reason hangup. Reads, lists and hang-ups do not need the calling entitlement: a live call stays endable after calling is switched off.
Recordings
A call read and every webhook carry a recording’s metadata only — recording.url is always null there. When call.recording.ready arrives, ask GET /v1/calls/{callId}/recording for a download link minted for this request and audited against your key.
curl 'https://api.trovacast.com/v1/calls/CALL_ID/recording' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "call_recording",
"id": "RECORDING_ID",
"callId": "CALL_ID",
"status": "available",
"format": "audio/mpeg",
"durationSeconds": 61,
"url": "https://…",
"expiresAt": "2026-11-05T10:20:00.000Z"
}DELETE /v1/calls/{callId}/recording (recordings:write) permanently erases every recording of the call — the stored audio itself — and audits each erasure against your key. It answers 204, a repeat answers 204 too, and afterwards the call reads recording: null. A 503 means storage refused the delete: retry with the same key.
curl -X DELETE 'https://api.trovacast.com/v1/calls/CALL_ID/recording' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: erase-recording-order-1042'List and reconcile
GET /v1/calls lists every call of the organization newest first, whichever path placed it (a console call reads as mode: "manual", "ai" or "hybrid"), filtered by status, contactId, direction, createdAfter (inclusive) and createdBefore (exclusive).
With updatedAfter it becomes a reconciliation read: every call changed at or after that instant, oldest change first, with a cursor of its own kind. Changes from the last two minutes are held back until no earlier change can still commit. Page until nextCursor is null, remember the largest updatedAt you saw, resume from there, and deduplicate on id + status. The filters combine with it.
The call graph. A transfer target, a bridged number or a conference party is a call of its own, dialled from a live call: its parentCallId is that call, rootCallId the call graph’s root, and legRole says what it is (transfer_target, conference, consult, agent_phone, carrier_bleg; primary for a call itself). GET /v1/calls lists root calls only unless you add include=legs; rootCallId={callId} lists one graph — its root and every leg.
curl 'https://api.trovacast.com/v1/calls?rootCallId=CALL_ID' \
-H "Authorization: Bearer $TROVACAST_API_KEY"curl 'https://api.trovacast.com/v1/calls?updatedAfter=2026-11-05T00%3A00%3A00.000Z&limit=100' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Events
Subscribe a webhook endpoint to follow calls as they happen. Each event embeds the call as GET /v1/calls/{callId} returns it.
| Event | When it is sent | Key scopes |
|---|---|---|
call.queued | A call was handed to the carrier. The call was created and its dial handed to the carrier.data: call | calls:read |
call.ringing | The contact’s phone is ringing — or a routed inbound call is ringing someone. The carrier reports the contact’s phone ringing (ringing: null). On an inbound call its number’s flow routes, a connect step started ringing: ringing names who — each party by its place in the step’s targets and your reference, a number by its last four digits and the registered phone it is — and how (strategy). Once per party in a sequence, once for all at once.data: call, ringing | calls:read |
call.answered | The contact answered — or someone took a routed inbound call. The conversation is live (answeredBy: null for an outbound call’s own answer). On an inbound call its number’s flow routes, someone took the caller: answeredBy.target says who (a number by its last four digits and the registered phone it is, a seat, an app, the queue a seat took the caller from) and confirmed whether they pressed the connect’s confirm key. A pickup that never confirmed is never told.data: answeredBy, call | calls:read |
call.completed | A connected call ended. With call.durationSeconds and who hung up (call.hangup.side).data: call | calls:read |
call.failed | A call failed, or was cancelled before an answer. call.failure says why.data: call | calls:read |
call.no_answer | The contact did not answer. The call rang out unanswered.data: call | calls:read |
call.busy | The contact’s line was busy. The carrier reported the line busy.data: call | calls:read |
call.recording.ready | A call’s recording is stored. call.recording has its id, format and duration. No link rides on the event: fetch one from GET /v1/calls/{callId}/recording (recordings:read, which subscribing to this event also needs).data: call | calls:readrecordings:read |
call.inbound | A call to one of your numbers reached its route. The caller is on the line, routed to a flow, an application, a queue or an agent: the call has direction: inbound, to the number of yours they dialled (international format) with its numberId, and from the caller masked to their last four digits (•••• ••3210).data: call | calls:read |
call.held | A hold action put the caller on hold. Fired by the hold action.data: actionId, call | calls:read |
call.resumed | A resume action took the caller off hold. Fired by the resume action.data: actionId, call | calls:read |
call.transferred | A transfer connected the caller elsewhere. An outside number answered (its last four digits), or a call flow, a voice application or a queue took the call over.data: actionId, call, transfer | calls:read |
call.gather.completed | A gather action finished. With the keys pressed or what the caller said — never the digits of a sensitive gather.data: actionId, call, gather | calls:read |
call.flow.failed | A call’s flow failed and the call was hung up. The platform hung up rather than leave the caller on a silent line. call.failure carries the documented FLOW_* code; flow says where it failed.data: call, flow | calls:read |
call.machine_detected | The carrier told a person from an answering machine. On a call that asked (machineDetection): call.machineDetection.result is human, machine or unknown. Once per call.data: call | calls:read |
call.transcript.ready | A call’s transcript is complete. Read it with GET /v1/calls/{callId}/transcript (transcripts:read, which subscribing also needs): the event counts the segments, never carries the text. Fires only when something was transcribed.data: call, transcript | calls:readtranscripts:read |
call.summary.ready | The AI summarised and graded a call. summary is what GET /v1/calls/{callId}/summary returns (status: ready). Once per call; an agent’s later wrap-up fires no second event. An AI agent’s test call fires it too, with the sandbox’s mock summary of its scripted conversation (summary.mock: true).data: call, summary | calls:readtranscripts:read |
call.transcript.segmentOpt-in | One line of a live call’s transcript. As soon as it is stored: the item GET /v1/calls/{callId}/transcript lists, phone numbers masked to their last four digits. Opt-in — sent only to an endpoint that names it — because it fires once per utterance. Deliveries are not ordered: order by segment.sequence. Never sent for what is said while a sensitive gather is open.data: callId, livemode, segment | calls:readtranscripts:read |
call.rated | A call’s charge was written. call.charge is the charge as GET /v1/calls/{callId} reads it — status (charged, waived or not_connected), amount, minutes, and the rule and reason it was rated by. A call is rated after its final call.* event, which carries charge: null. Once when it is rated; an unrated charge (no price yet) fires nothing until a re-rate or the backfill charges it, and a charged call fires again only when it is re-rated on corrected minutes. A test call is never rated, so it never fires.data: call | calls:read |
call.missed | An inbound caller reached nobody. Every route the call tried went unanswered, the caller hung up waiting, or the business was closed. missed.reason says which; missed.voicemail is the message they left, when they left one (its audio is the call’s recording). Once per call, when its flow ends — the call’s own final event (call.completed) is separate. Text them back, or call them back, from here.data: call, missed | calls:read |
call.voicemail.ready | A caller’s message is ready, with its transcript. The voicemail a caller left: its audio (voicemail.recordingId, fetched with GET /v1/calls/{callId}/recording?recordingId=), the key they pressed (voicemail.key) and — when the voicemail step asked — their words from the call’s live transcript (voicemail.transcript, phone numbers masked to their last four digits). Once per voicemail, a few seconds after the message ends, when the transcript of it has landed; it can come after the call’s call.missed. Needs transcripts:read as well as calls:read.data: call, voicemail | calls:readtranscripts:read |
call.ai.transfer | An AI call’s agent handed the caller to a person. The call names a transfer (its own, its ai route’s, or its session webhook’s) and its agent asked for a person. transfer.outcome is answered (the person has the caller and the agent left the call), no_answer or failed (cause says why: NO_ANSWER, BUSY, UNCONFIRMED, or the dial’s refusal such as DESTINATION_BLOCKED) — then the caller is back with the agent (returnedToAi). Once per hand-off (transfer.id); a call can hand off again after coming back.data: call, transfer | calls:read |
call.ai.opt_out | An AI call’s caller opted out and was marked do-not-call. The caller pressed the call’s opt-out key (optOut.method: dtmf, key) or said one of its phrases (speech, phrase — the configured phrase, never their words). The contact was marked do-not-call in the same transaction (optOut.doNotCall; the contact reads doNotContact: true and every call to them is refused CONTACT_DO_NOT_CALL), then the agent said the reply and the call ended. Once per call.data: call, optOut | calls:read |
call.dtmfOpt-in | A key the caller pressed during an AI conversation, or a flow that tells keys. Opt-in: sent only to endpoints that name it. One per key the caller pressed during an AI conversation (an AI call, or an AI step of a flow) or — P7 — during the steps of a flow that opts in (events: { dtmf: true }) — never one pressed into a sensitive gather.data: call, dtmf | calls:read |
Not yet supported
- Transcripts. Trovacast does not transcribe calls to your agent: the conversation, and its transcript, are yours.
- Agent-first click-to-call to a browser.
ringFirst: agentrings the agent’s own phone; ringing their browser softphone first is not built yet. - Inbound calls to an external agent’s stream. Inbound calls go to a flow, an application, a queue or a person (Inbound calls). Your agent cannot send key presses over its own stream: use
send_dtmfin Call control.
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
AGENT_PHONE_REQUIRED | 422 | A BRIDGE call with ringFirst: agent names a seat with no phone on file to ring first.What to do: An administrator adds the agent’s phone to their team membership in the console, or ring the contact first (ringFirst: contact). |
AGENT_STREAM_URL_INVALID | 422 | agent.streamUrl is not a public wss:// URL (credentials in it, a private host or address); reason says which. Checked again every time the socket connects. See Calls.What to do: Use a wss:// URL on a public host that resolves to public addresses, with no credentials in it — put your secret in agent.token, which arrives as Authorization: Bearer. |
AI_AGENT_INACTIVE | 409 | aiAgent.agentId — or (2026-11-07) a new ai route on PATCH /v1/numbers/{numberId} — names an AI agent that is switched off (active: false) or archived. Nothing was dialled, and the route was not changed. See AI voice agents.What to do: Switch a switched-off agent on with PATCH /v1/agents/{agentId} (active: true); for an archived one, name another agent. |
AI_AGENT_NOT_FOUND | 404 | aiAgent.agentId — or (2026-11-07) a new ai route on PATCH /v1/numbers/{numberId} — names no AI agent of this organization of the request's mode (GET /v1/agents lists them; a test agent on a live call or number reads exactly as an unknown one). Nothing was dialled, and the route was not changed.What to do: Pass an agentId from GET /v1/agents, using a key of the same mode as the agent (a number takes live calls: route it to a live agent). |
AI_CALLS_DISABLED | 409 | The organization's call policy turns machine-run calls off.What to do: Turn AI calls on with PATCH /v1/settings/calls (aiCallsEnabled: true and the version from GET /v1/settings/calls; a live key with settings:write), or in the console under Settings → Calling policy, then retry. See Turn AI calls on or off. |
ANSWER_URL_INVALID | 422 | flow.answerUrl is not an https URL on the voice application’s own origin (the answer or fallback URL’s), or not one Trovacast will call (a private host, a service port). Nothing was dialled. See Inbound calls.What to do: Use an https URL on the application’s own origin, on a public host and an allowed port — or leave flow.answerUrl out to ask the application’s answer URL. |
APPLICATION_NOT_FOUND | 404 | flow.applicationId (or a transfer’s to.applicationId) names no voice application of this organization.What to do: Pass an id from GET /v1/applications, using a key of the same mode as the application. |
BRIDGE_AGENT_NOT_FOUND | 404 | bridge.to.agentMembershipId names no active seat of this organization. Nothing was dialled.What to do: Pass the membership id of an active seat of this organization, or bridge to an outside number (bridge.to.number). |
CALLER_ID_NOT_OWNED | 422 | from is not a voice-capable number the organization owns on the call's channel. When the carrier cannot answer for its inventory right now the call is a 503 instead.What to do: Set from to one of your assigned voice numbers on the call's channel (GET /v1/numbers), or leave it out to use the channel's own caller ID. Retry the 503 with backoff. |
CALLER_ID_UNSUPPORTED | 422 | from was sent on a channel that cannot check a chosen caller ID (callerIdSelection: false in GET /v1/calls/channels); provider names the channel.What to do: Leave from out to use the channel's own caller ID, or set provider to a channel with callerIdSelection: true. |
CALLING_WINDOW_CLOSED | 409 | respectCallingWindow is on and it is outside the calling window (09:00–21:00 in the organization's time zone, unless the deployment sets another). The body carries nextAllowedAt, timeZone and window.What to do: Place the call again at or after nextAllowedAt. |
CALL_CONCURRENCY_LIMIT | 429 | Over the organization's or the key's cap on live API calls (scope is organization or key, with limit and liveCalls) — or, with livemode: false and testCalls in place of liveCalls, over the sandbox's own cap on test calls. Each mode counts only its own calls.What to do: Place the call again once one of your calls in the same mode ends (watch call.completed), backing off between attempts. See Limits and billing. |
CALL_FLOW_INVALID | 422 | The call-flow document does not validate; issues lists each problem with its path. See Call flows.What to do: Fix each problem in issues at its path and send the document again; check drafts first with POST /v1/call-flows/validate. |
CALL_FLOW_NOT_FOUND | 404 | flow.callFlowId (or a transfer’s to.callFlowId) names no call flow of this organization, or an archived one.What to do: Pass the id of a call flow that is not archived (GET /v1/call-flows), using a key of the same mode as the flow. |
CALL_FLOW_NOT_PUBLISHED | 409 | The call flow has no published version to run.What to do: Publish a version with POST /v1/call-flows/{callFlowId}/versions/{versionId}/publish, then retry. |
CARRIER_RATE_LIMITED | 429 | The carrier is throttling dials and nothing rang. The body names the call (callId) and retryAfterSeconds, also sent as Retry-After.What to do: Wait retryAfterSeconds, then retry under the same Idempotency-Key: the retry dials afresh. |
CARRIER_REJECTED | 502 | The carrier refused the dial and nothing rang. The call exists as failed (callId).What to do: Retry with backoff under the same Idempotency-Key, which dials afresh. If the carrier keeps refusing, read the call's failure (GET /v1/calls/{callId}) and check the number. |
CHANNEL_NOT_CONFIGURED | 409 | The project has not set the channel up — email: no email account of its own (the platform’s mail never sends for it); SMS: no SMS settings or DLT entity id — or the deployment does not carry it. On a call, the provider is not a channel this deployment runs or the organization has set up. Also a message.failed code when the account was disconnected after the message was queued; nothing was sent.What to do: Set the channel up in Settings → Channels (WhatsApp, Email or SMS) — for a call in Settings → Calling, or leave provider out — then retry. A message that failed with this code was never sent: send it again once the account is connected. |
CHANNEL_UNSUPPORTED | 422 | The channel cannot carry this kind of call: it does not stream the call's media to your agent (externalAgent: false in GET /v1/calls/channels) or into a flow or bridge (flows: false), or it cannot ring an agent first (agentFirst: false); provider names it.What to do: Set provider to a channel whose GET /v1/calls/channels entry has what the call needs; for an agent-first bridge, ring the contact first instead. |
CHILD_DIAL_DESTINATION_NOT_ALLOWED | 422 | The number a BRIDGE call or a transfer would dial is outside the organization’s list of destinations for connected parties (India by default). Nothing was dialled.What to do: Dial a number inside that list, or contact us to widen it for your organization. |
CONTACT_DO_NOT_CALL | 409 | The contact is on the do-not-call list; no call is placed.What to do: Do not retry or dial the number another way. If the contact asks to be called again, a project member changes their state in the console. |
CONTACT_OPTED_OUT | 409 | On a send, the contact opted out of all contact or asked not to be contacted — it outranks every channel's consent. On a call, they opted out of calls themselves.What to do: Do not retry, and do not reach them another way. If the contact asks to hear from you again, a project member changes their state in the console. |
CONTACT_PHONE_REQUIRED | 422 | The contact has no phone number — they are known by their WhatsApp user id alone — so they cannot be called.What to do: Do not retry: reach them on WhatsApp instead. If WhatsApp later shares their number, it lands on the contact by itself. See Contacts without a phone number. |
DESTINATION_ACKNOWLEDGEMENT_REQUIRED | 422 | +1 is opened for your organization, but it has not acknowledged the TCPA statement yet (or the statement changed since). GET /v1/settings/destinations shows tcpa.acknowledged.What to do: Acknowledge the statement — with your key (POST /v1/settings/destinations/tcpa with its currentStatementVersion) or in the console, under the calling policy’s Destinations — then retry. |
DESTINATION_BLOCKED | 422 | The number is in a country code your organization may not call: a call to a contact reaches the home market (+91, defaultCountryCodes) and the countries the platform opened for you (openedCountryCodes) only, and +1 (North America) is blocked on every path, transfers included. The platform can open a country for your organization (priced on your plan with a rate of its own); GET /v1/settings/destinations says what applies (countryCallingCode names the code, absent when the number's country could not be read).What to do: Retrying will not help: call a number you may reach, or contact us to open the country for your organization. See Destinations. |
DESTINATION_CALLING_WINDOW_CLOSED | 409 | A +1 call outside 08:00–21:00 (or a narrower window this deployment sets) in the called party’s local time — the zone the request states (calledPartyTimeZone), else every zone the number’s area code serves — on every path, respectCallingWindow: false included. nextAllowedAt says when it opens.What to do: Place the call again at or after nextAllowedAt; no request option lifts this window. If you know the called party’s time zone, state it in calledPartyTimeZone. |
DESTINATION_NOT_PRICED | 422 | The destination lies beyond the default your calls reach (a country code opened for you, or a leg to a widened prefix) and your plan has no rate of its own for it — the home market’s rate never prices a call abroad. GET /v1/pricing shows your rates.What to do: Retrying will not help until the destination is priced: contact us to have it added to your plan. |
DLT_HEADER_REQUIRED | 422 | The 140-series number has no verified DLT voice header of this organization — on a call from it, or on activating it.What to do: Register a voice header for this exact number under Settings → DLT registrations and wait for it to be verified, then retry; until then the same request fails the same way. |
HANGUP_FAILED | 503 | The carrier (or the server carrying the call's stream) did not confirm the hang-up, so the line may still be up.What to do: Retry POST /v1/calls/{callId}/hangup — with the same Idempotency-Key if you sent one: the endpoint runs again rather than replaying the error. A hangup call action stores this error against its key, so retry that with a new key. |
HANGUP_NOT_READY | 409 | The call can be ended, but not yet: the carrier has not answered the dial with the id it is ended by, or — on a channel without remoteHangup — the contact has not answered.What to do: Retry after retryAfterSeconds (also Retry-After); once the call can be ended, the retry ends it. |
HANGUP_UNSUPPORTED | 409 | The call's channel can never end it remotely: it has no remote hang-up and no stream the platform holds or awaits to close.What to do: Do not retry: this call ends only when a party on it hangs up. |
MACHINE_DETECTION_UNSUPPORTED | 422 | machineDetection was sent on a channel that cannot tell an answering machine from a person (machineDetection: false in GET /v1/calls/channels); provider names the channel. See Calls.What to do: Leave machineDetection out, or set provider to a channel with machineDetection: true. |
MEDIA_CAPACITY | 503 | The server carries as many streamed calls as it may right now. Nothing was dialled or connected.What to do: Retry shortly with backoff. POST /v1/calls runs again under the same Idempotency-Key; a call action or a conference write stores this error against its key, so retry those with a new one. |
MEDIA_DRAINING | 503 | The server is shutting down and takes no new streamed calls or legs. Another server takes them.What to do: Retry in a moment. POST /v1/calls runs again under the same Idempotency-Key; a call action or a conference write stores this error against its key, so retry those with a new one. |
PROMOTIONAL_NUMBER_REQUIRED | 422 | A call declared PROMOTIONAL must be placed from one of the organization's assigned 140-series numbers.What to do: Set from to one of your assigned 140-series numbers (GET /v1/numbers), or declare another purpose when the call is not promotional. |
PROMOTIONAL_PURPOSE_REQUIRED | 422 | A 140-series caller ID may place only calls declared PROMOTIONAL.What to do: Use another number as from for service or transactional calls, or send purpose: "PROMOTIONAL" when the call is promotional. |
PROMOTIONAL_WINDOW_CLOSED | 422 | Promotional calls are allowed only between 09:00 and 21:00 in the called party's time zone.What to do: Place the call again inside the window; the message names the called party's time zone. |
RECORDING_CONSENT_REQUIRED | 409 | The call would be recorded — recording.enabled, or the organization records every call (the default) — and the request carries no recording.consentEvidence.What to do: Send recording.consentEvidence — source, text and capturedAt of the contact's agreement — with the call. See Recording and consent evidence. |
RECORDING_NOT_AVAILABLE | 409 | The call's recording is not stored yet, or storing it failed; status is pending, processing or failed.What to do: While status is pending or processing, ask again after call.recording.ready; a failed recording does not become available. |
TTS_UNAVAILABLE | 503 | Speech synthesis is not configured on this deployment, so speak (and spoken prompts) are refused rather than played as silence. Nothing was played.What to do: Use play with a WAV URL instead (a gather’s prompt.url likewise); retrying speak will not help on this deployment. |