Trovacast

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.

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.

Place a call to your agent
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, TRANSACTIONAL or PROMOTIONAL, checked before the dial. A promotional call needs one of your assigned 140-series numbers as from, a verified voice DLT header and the 09:00–21:00 window in the called party’s zone; a 140-series from is 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 needs contacts:write). Or name an existing contact with contactId.
  • agent.streamUrl — a public wss:// URL, checked when the call is requested and again when the socket connects (422 AGENT_STREAM_URL_INVALID otherwise). agent.token is sent as Authorization: Bearer <token> on the upgrade; it is stored sealed and never returned. agent.audio is { "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, as GET /v1/calls/channels names 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’s start frame. 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.

201 Created (json)
{
  "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`BlockWhat runs the call
FLOWflow: 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_AGENTaiAgent: agentId, optional objectiveOne of your AI agents. The call reads mode: "ai" with aiAgentId.
BRIDGEbridge: to (exactly one of number or agentMembershipId), ringFirst (contact default, or agent), prompt, whisper, noAnswerMessage, ringTimeoutSecBy 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.
A call that runs a published call flow
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 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.

List the call channels
curl 'https://api.trovacast.com/v1/calls/channels' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 OK (json)
{
  "data": [
    {
      "object": "call_channel",
      "provider": "plivo",
      "label": "Plivo",
      "default": true,
      "externalAgent": true,
      "ready": true,
      "callerIdSelection": true,
      "remoteHangup": true,
      "machineDetection": true,
      "sensitiveGather": false,
      "flows": true
    }
  ]
}
FlagMeans
providerThe value POST /v1/calls takes as provider.
defaultWhere a call that names no provider dials for this organization.
externalAgentThe channel can stream a call to your agent.
readyA call can be placed on it now: it is set up for the organization and everything the deployment needs is in place.
callerIdSelectionThe request may name from.
remoteHangupThe 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.
machineDetectionThe 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).
sensitiveGatherA 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).
flowsThe 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.

Bridge, but only to a person
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`StatusMeaning
NO_ANSWER / BUSY / CANCELLEDno_answer / busy / cancelledThe contact did not answer, the line was busy, or the call was ended before it was answered.
FAILEDfailedThe call failed and the carrier gave no cause.
PROVIDER_REJECTEDfailedThe carrier refused to place the call.
PROVIDER_RATE_LIMITEDfailedThe carrier was rate-limiting calls; nothing was dialled.
SUBMISSION_UNKNOWNfailedThe carrier never confirmed the dial; it was not retried, to avoid ringing the contact twice.
WATCHDOG_EXPIREDfailedThe 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_FAILEDfailedThe carrier answered but the call’s audio never reached Trovacast.
MEDIA_OWNER_LOSTfailedThe 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_UNAVAILABLEfailedA 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_*failedAn 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_UNAVAILABLEfailedAn 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>_…failedA carrier’s own cause (PLIVO_STREAM_SESSION_EXPIRED, TWILIO_ANSWERING_MACHINE, …), explained in plain language.
FLOW_CONNECT_FAILEDanyThe party a connect (or a BRIDGE) dials could not be dialled; call.flow.failed names the refusal (flow.cause).
FLOW_TTS_UNAVAILABLE / FLOW_AUDIO_UNAVAILABLEanyText 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_FOUNDanyThe application’s answer URL could not be reached, answered instructions that do not validate, or no longer exists.
FLOW_MEDIA_NOT_CONNECTED / FLOW_MEDIA_UNAVAILABLEanyThe call’s audio never reached Trovacast, or stopped while the flow ran.
FLOW_STEP_LIMIT / FLOW_LOOP_LIMIT / FLOW_INVALID_BRANCH / FLOW_INVALID_REDIRECTanyThe flow ran too many steps, looped, or branched somewhere it cannot go.
FLOW_INVALID / FLOW_NOT_PUBLISHED / FLOW_ERRORanyThe 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.
endedstatus, failureThe call ended, as the call reads.
flow_step.startedstep, node, verbA step of its flow began.
flow_step.endedstep, node, verb, outcome, fallback, code, nextNodeWhat 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.refusedstep, node, agentId; code when refusedThe 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.leftids, transferType, target, masked to, codeHold, 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.resumedby, recordingA manual pause, by your key (api) or the agent (desk).
transcription.unavailable, transcription.recoveredphaseThe speech-to-text was lost, and came back.
ceiling.reachedmaxDurationSecondsThe call ran to its own ceiling.
ratedchargeThe call’s charge — with its rule and reason, why it was rated as it was — always the last entry, once rated.
Read a call’s timeline
curl 'https://api.trovacast.com/v1/calls/CALL_ID/events' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 OK — an AI step whose agent could not speak, and the fallback it took (json)
{
  "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:

CodeStatusMeaning
VALIDATION_FAILED400A 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_DISABLED403The organization does not have calling.
API_KEY_SCOPE_MISSING403to.phone without contacts:write.
AGENT_STREAM_URL_INVALID422streamUrl is not a public wss:// URL (reason).
DESTINATION_BLOCKED422The 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_REQUIRED422+1 is opened for you but your organization has not acknowledged the TCPA statement in the console.
CONTACT_DO_NOT_CALL / CONTACT_OPTED_OUT409The contact is on the do-not-call list, or opted out of calls.
CONTACT_PHONE_REQUIRED422The contact has no phone number.
CALLING_WINDOW_CLOSED409Outside the calling window; the body carries nextAllowedAt, timeZone and window.
RECORDING_CONSENT_REQUIRED409The call would be recorded and carries no consentEvidence.
AI_CALLS_DISABLED409The organization’s call policy turns machine-run calls off.
CHANNEL_NOT_CONFIGURED409The channel is not one this deployment runs, or is not set up for the organization (provider).
CHANNEL_UNSUPPORTED422The channel cannot carry a call to your agent.
CALLER_ID_UNSUPPORTED422from on a channel that cannot check a chosen caller ID.
CALLER_ID_NOT_OWNED422from is not a voice-capable number the organization owns on the channel.
MACHINE_DETECTION_UNSUPPORTED422machineDetection on a channel that cannot detect an answering machine (machineDetection: false).
SERVICE_UNAVAILABLE503The channel is temporarily unavailable on this deployment. Retry later.
CALL_CONCURRENCY_LIMIT429Over the organization’s or the key’s live-call cap (scope, limit, liveCalls).
BILLING_INSUFFICIENT_CREDIT402The balance cannot cover the call’s ceiling beside the API calls already in flight (minutesRequired, balanceMinor, ratePerMinuteMinor, includedMinutesRemaining).
BILLING_SUBSCRIPTION_PAST_DUE / _SUSPENDED / _CANCELED402The subscription does not allow calling.
BILLING_RATE_UNAVAILABLE503The plan does not price this channel.
DESTINATION_NOT_PRICED422A destination opened beyond the default has no rate of its own on your plan.
DESTINATION_CALLING_WINDOW_CLOSED409A +1 call outside the TCPA window in the called party’s local time (nextAllowedAt) — whatever respectCallingWindow says.
MEDIA_CAPACITY / MEDIA_DRAINING503The server that would carry the call’s stream is full, or restarting; nothing rang. Retry shortly with the same Idempotency-Key.
CARRIER_REJECTED502The carrier refused the dial; nothing rang. The call exists as failed (callId).
CARRIER_RATE_LIMITED429The 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.

Read where your calls may reach
curl 'https://api.trovacast.com/v1/settings/destinations' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 — +1 and the UK opened, +1 acknowledged; transfers to India and the UK (json)
{
  "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.

Ring the agent, then the contact
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 queued until it ends. Over either cap is 429 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 same 429, with livemode: false).
  • Credit. A call is priced, before it is dialled, for what the carrier could bill it for: maxDurationSec plus 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 own maxDurationSec at its own rate (a FLOW or BRIDGE call 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 is 402 BILLING_INSUFFICIENT_CREDIT with minutesRequired and inFlightMinutes — and maxDurationSecAvailable, the longest maxDurationSec that 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

Frames your agent receives (text)
{ "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.last4 is always the last four digits of the number dialled. to.phone is the full number only when your request dialled it by number (to.phone), echoing what you sent; for a call placed by contactId it is null. resumed is true on 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. seq and tsMs keep counting across frames that had to be dropped, so a gap in seq is 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` reasonMeaning
completedThe carrier ended the call normally: the contact hung up.
hangupYour side ended it: POST /v1/calls/{callId}/hangup, or the answer to your own hangup frame.
max_durationThe call reached maxDurationSec.
carrier_reconnectingThe 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_closedThe carrier’s media leg dropped for good.
platform_closedTrovacast 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

Frames your agent sends (text)
{ "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 send clear before a new turn.
  • mark — named marker: you get a mark back 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 seq gap 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 maxDurationSec from the moment your stream first opened (stop with max_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).

End a call
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.

Get a recording link
curl 'https://api.trovacast.com/v1/calls/CALL_ID/recording' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 OK (json)
{
  "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.

Erase a call’s recordings
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.

A call and every leg dialled from it
curl 'https://api.trovacast.com/v1/calls?rootCallId=CALL_ID' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
Calls changed since a moment
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.

EventWhen it is sentKey scopes
call.queuedA call was handed to the carrier. The call was created and its dial handed to the carrier.data: callcalls:read
call.ringingThe 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, ringingcalls:read
call.answeredThe 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, callcalls:read
call.completedA connected call ended. With call.durationSeconds and who hung up (call.hangup.side).data: callcalls:read
call.failedA call failed, or was cancelled before an answer. call.failure says why.data: callcalls:read
call.no_answerThe contact did not answer. The call rang out unanswered.data: callcalls:read
call.busyThe contact’s line was busy. The carrier reported the line busy.data: callcalls:read
call.recording.readyA 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: callcalls:readrecordings:read
call.inboundA 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: callcalls:read
call.heldA hold action put the caller on hold. Fired by the hold action.data: actionId, callcalls:read
call.resumedA resume action took the caller off hold. Fired by the resume action.data: actionId, callcalls:read
call.transferredA 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, transfercalls:read
call.gather.completedA gather action finished. With the keys pressed or what the caller said — never the digits of a sensitive gather.data: actionId, call, gathercalls:read
call.flow.failedA 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, flowcalls:read
call.machine_detectedThe 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: callcalls:read
call.transcript.readyA 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, transcriptcalls:readtranscripts:read
call.summary.readyThe 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, summarycalls:readtranscripts:read
call.transcript.segmentOpt-inOne 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, segmentcalls:readtranscripts:read
call.ratedA 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: callcalls:read
call.missedAn 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, missedcalls:read
call.voicemail.readyA 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, voicemailcalls:readtranscripts:read
call.ai.transferAn 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, transfercalls:read
call.ai.opt_outAn 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, optOutcalls:read
call.dtmfOpt-inA 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, dtmfcalls: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: agent rings 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_dtmf in Call control.

Errors

CodeStatusMeaning and what to do
AGENT_PHONE_REQUIRED422A 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_INVALID422agent.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_INACTIVE409aiAgent.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_FOUND404aiAgent.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_DISABLED409The 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_INVALID422flow.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_FOUND404flow.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_FOUND404bridge.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_OWNED422from 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_UNSUPPORTED422from 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_CLOSED409respectCallingWindow 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_LIMIT429Over 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_INVALID422The 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_FOUND404flow.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_PUBLISHED409The 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_LIMITED429The 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_REJECTED502The 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_CONFIGURED409The 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_UNSUPPORTED422The 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_ALLOWED422The 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_CALL409The 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_OUT409On 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_REQUIRED422The 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_REQUIRED422+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_BLOCKED422The 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_CLOSED409A +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_PRICED422The 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_REQUIRED422The 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_FAILED503The 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_READY409The 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_UNSUPPORTED409The 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_UNSUPPORTED422machineDetection 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_CAPACITY503The 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_DRAINING503The 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_REQUIRED422A 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_REQUIRED422A 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_CLOSED422Promotional 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_NOT_AVAILABLE409The 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_UNAVAILABLE503Speech 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.