Voice
Call control
Act on a live call: speak or play to it, collect key presses, press keys, hold and resume, mute your agent, transfer, pause the recording and hang up.
Every action is one POST /v1/calls/{callId}/actions with calls:write, naming the action and the fields it takes. It works on any answered call whose audio streams through Trovacast — calls to your own agent, AI agent calls, flow calls, click-to-call bridges and inbound calls routed to a flow or an application — and is refused with a clear code everywhere else. A refused action changes nothing.
Actions
| `action` | Fields | Answers |
|---|---|---|
speak | text (≤ 1,000 characters), voice, language (BCP 47, e.g. en-IN) | started — spoken by speech synthesis |
play | url: an https WAV file | started |
gather | input (dtmf default, speech or dtmf_speech), prompt (text or url), numDigits (1–32), finishOnKey (#, * or ""), timeoutSec (1–60, default 5), interDigitTimeoutSec, sensitive; speech: language, hints, speechTimeoutSec (1–10, default 2) | started — ends with call.gather.completed |
send_dtmf | digits: up to 32 of 0-9 * #, w for a half-second pause | completed |
hold | audioUrl: a WAV played on a loop (a soft tone when unset) | completed — call.held |
resume | — | completed — call.resumed |
mute / unmute | — (your own leg: an external agent’s audio) | completed |
transfer | to: exactly one of number, queueId, callFlowId, applicationId; ringTimeoutSec (5–120, default 30) for a number | started — ends with call.transferred |
record | state: pause or resume | completed |
hangup | — | completed — the hang-up route’s own rules |
curl -X POST 'https://api.trovacast.com/v1/calls/2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f/actions' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: gather-2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f-1' \
-H 'Content-Type: application/json' \
-d '{
"action": "gather",
"prompt": {
"text": "Please enter your six-digit order number."
},
"numDigits": 6,
"finishOnKey": "#",
"timeoutSec": 10
}'{
"object": "call_action",
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"callId": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
"action": "gather",
"status": "started",
"call": {
"object": "call",
"id": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
"status": "in_progress"
}
}The answer’s id is the action’s; the events it leads to carry it as actionId. completed means it is done; started means it is running on the call — a gather ends in call.gather.completed (outcome complete, finish_key, timeout or hangup, with digits), a transfer in call.transferred. Send an Idempotency-Key: a retry is answered with the first response and never acts twice.
Transfer
A transfer to a number dials it as a leg of the call (its parentCallId is the call; legRole: transfer_target) and holds the caller until it answers, then connects them — or takes them off hold again after ringTimeoutSec. The number must be on the organization’s list of destinations for connected parties (India by default), or the transfer is 422 CHILD_DIAL_DESTINATION_NOT_ALLOWED. A transfer to a callFlowId or an applicationId hands the call to that published flow or that application’s answer URL — see Call flows. A transfer to a queueId puts the caller in one of your call queues at once (call.transferred with target: queue): they wait like any queued caller — its hold audio, announcements and overflow, voicemail if nobody takes them — ahead of new callers while the queue’s transferBoost is on (the default), and the agent who accepts sees the call was transferred. 404 QUEUE_NOT_FOUND for a queue of another organization, 409 QUEUE_CLOSED for one switched off.
curl -X POST 'https://api.trovacast.com/v1/calls/2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f/actions' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: transfer-2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f' \
-H 'Content-Type: application/json' \
-d '{
"action": "transfer",
"to": {
"callFlowId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}'Sensitive input
gather with sensitive: true is for card numbers and PINs: the digits are never stored, logged or sent — call.gather.completed carries digits: null — and it runs only while every recording of the call is paused for its whole length. Trovacast’s own recording pauses itself. When the call is recorded, its carrier usually keeps a recording of its own too, and that one must pause as well: where it can (sensitiveGather: true in GET /v1/calls/channels), the action answers only once the carrier has confirmed the pause, and the recording resumes when the gather ends; where it cannot, the gather is refused (409 RECORDING_NOT_CONTROLLABLE). A pause the carrier did not confirm is 503 RECORDING_PAUSE_FAILED, and nothing is collected. A call that is not recorded takes a sensitive gather on every channel.
| Channel | A sensitive gather on a recorded call |
|---|---|
| Twilio | The carrier’s recording is paused (the span kept as silence) before the action answers, and resumed when the gather ends. |
| Telnyx | The carrier’s recording is paused before the action answers, and resumed when the gather ends. |
| Plivo | Refused, 409 RECORDING_NOT_CONTROLLABLE: Plivo’s recording of the call cannot be paused. |
| Exotel | Refused, 409 RECORDING_NOT_CONTROLLABLE: Exotel’s recording cannot be paused. |
| Airtel IQ | Refused, 409 RECORDING_NOT_CONTROLLABLE: Airtel’s own copy of the call cannot be paused (Trovacast’s recording of the stream can). |
record with state: pause pauses Trovacast’s own recording while something sensitive is said; resume restarts it. A call recorded by its carrier cannot be paused that way (409 RECORDING_NOT_CONTROLLABLE).
When an action is refused
- Not answered yet —
409 CALL_NOT_ANSWERED: act once the call isin_progress(aftercall.answered). An ended call is409 CALL_NOT_LIVE. - One prompt at a time — while a
speak,playorgather(or a call flow) is speaking, another is409 CALL_ACTION_IN_PROGRESS. Atransferpre-empts it. - Audio not streamed through Trovacast — a phone-leg or SIM call cannot be controlled (
409 CALL_NOT_CONTROLLABLE). - The server carrying the call did not answer —
409 CALL_ON_ANOTHER_REPLICA: it is restarting or failed; retry shortly with the sameIdempotency-Key(safe: it runs at most once). - Not on this deployment —
speakwithout speech synthesis configured is503 TTS_UNAVAILABLE(never silence); an option the call or deployment cannot do isCALL_ACTION_UNSUPPORTEDwith areason.
Limits
- Speech gather.
input: speech(ordtmf_speech, where the first key wins and the words are dropped) transcribes what the caller says with the platform’s speech recognition, in the primary language oflanguage; it ends afterspeechTimeoutSecof quiet following speech, at most 60 seconds.call.gather.completedcarriesspeech: { text, confidence }(confidenceis null when the recognizer gives none).hintsare accepted for every recognizer but applied only by one that takes them — today’s do not. Asensitivegather is keys-only. A deployment without speech recognition answers422 CALL_ACTION_UNSUPPORTEDwithreason: speech_recognition_unavailable. - WAV only.
play, a gatherprompt.urland hold music take an https URL of a WAV file — 16-bit PCM or µ-law, mono or stereo, 8, 16, 24 or 48 kHz, at most 5 MB (about five minutes), fetched within 8 seconds through the platform’s SSRF guard. Anything else is422 AUDIO_UNAVAILABLE. - Any server. An action runs on the server that carries the call’s audio; a request that reaches another one is forwarded there and answered exactly as if it had landed there. Only when that server cannot be reached in time is it
409 CALL_ON_ANOTHER_REPLICA. - Test keys. A test key acts on its own test calls, which the call sandbox answers as a live call would (the events included) without any audio. A call of the other mode is a call that does not exist: a test key acting on a live call, or a live key on a test call, is
404 NOT_FOUND, exactly as an unknown id. The one exception ishangup: any key may end a test call — it touches no person, carrier or wallet, and frees one of your test-call slots. - AI agents. A
transferhas no AI-agent target of its own: to hand a live call to one of your AI agents, transfer it to a call flow whose step isai(An AI agent as a step). A transfer to a call flow that hands callers to an agent whose voice cannot run here (availability.runnable: false) is422 AI_PROVIDER_UNAVAILABLE—reason,provider,leg,agentId— before anything happens to the call.
Events
Subscribe a webhook endpoint with calls:read to follow actions. Each event embeds the call and the actionId.
| Event | When it is sent | Key scopes |
|---|---|---|
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 |
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
AI_PROVIDER_UNAVAILABLE | 422 | mode: AI_AGENT named an AI agent whose voice cannot run on this deployment — or (2026-11-07) a transfer action named a call flow that hands callers to such an agent (agentId names it; nothing was changed on the call): reason is voice_key_missing (its provider has no key here), agent_id_missing (an ElevenLabs voice with no ElevenLabs agent id), transcription_key_missing or reasoning_key_missing (a composite voice without its speech-to-text or reasoning key); provider and leg name the leg. Nothing was written or dialled — no call, no call.* event. The same code is a call’s failure.code when its voice could not start once the call existed. See AI voice agents.What to do: Do not retry the same request: it is refused the same until the agent or the deployment changes. Check GET /v1/agents/{agentId} (availability), then choose an agent that reads runnable: true, or switch this one to a voice GET /v1/models marks available. On a test key, build the agent on the mock voice. |
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. |
AUDIO_UNAVAILABLE | 422 | The audio for play, a gather prompt or hold music could not be fetched, or is not a playable WAV (16-bit PCM or µ-law, mono or stereo, 8–48 kHz, at most 5 MB); reason says which. Nothing was played.What to do: Host a WAV that fits those limits at a public https URL that answers within 8 seconds, then send the action again. See Limits. |
CALL_ACTION_IN_PROGRESS | 409 | Another prompt or gather (or a call flow) is still speaking on the call; runningActionId or reason says which. A transfer does not wait: it pre-empts the prompt.What to do: Wait for it to finish — a gather ends with call.gather.completed, a transfer with call.transferred — then act again. |
CALL_ACTION_UNSUPPORTED | 409 or 422 | The action, or one of its options, is not available on this call or this deployment (reason): for example a speech gather where the deployment has no speech recognition, a stored audio asset, a leg the call does not have, a mode the deployment does not offer, or connecting a live call to an AI agent. See Call control.What to do: Change the request as reason says — gather dtmf, play a WAV URL, act on the root call (rootCallId) rather than a leg — since retrying it unchanged fails the same way. |
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. |
CALL_NOT_ANSWERED | 409 | The call is not answered yet: actions start once it is in_progress (after call.answered).What to do: Act again once call.answered has arrived. |
CALL_NOT_CONTROLLABLE | 409 | The call’s audio does not stream through Trovacast (a phone-leg or SIM call), so it cannot be spoken to, held or transferred from the API.What to do: Do not retry. Only calls whose audio streams through Trovacast can be controlled — every POST /v1/calls mode, and inbound calls routed to a flow or an application. |
CALL_NOT_HELD | 409 | resume on a call that is not on hold.What to do: Nothing to resume: send resume only after a hold (call.held). |
CALL_NOT_LIVE | 409 | The call has ended, or never went live. Nothing was done.What to do: Do not retry: read the call (GET /v1/calls/{callId}) for how it ended. |
CALL_ON_ANOTHER_REPLICA | 409 | The Trovacast server carrying the call’s audio could not be reached in time (it is restarting or failed). Any other server forwards actions to it, so this is rare.What to do: Retry shortly with the same Idempotency-Key, which is safe: the action runs at most once. |
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. |
CHILD_LEG_LIMIT | 409 | The call already has as many live legs dialled from it as it may (transfer targets, bridged numbers).What to do: End one of its legs first (POST /v1/calls/{callId}/hangup on the leg), then add the party again. |
CHILD_LEG_UNSUPPORTED | 503 | The call’s channel cannot stream a leg dialled from a live call, so it cannot bridge or transfer to a number on this deployment.What to do: Retrying will not help on this channel: transfer to a queue, a call flow or a voice application instead, which dials no leg. |
DTMF_INVALID | 422 | digits uses keys other than 0-9 * # and w (a half-second pause), or more than 32.What to do: Send at most 32 keys from 0-9, *, # and w. |
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. |
RECORDING_NOT_CONTROLLABLE | 409 | The call is recorded by its carrier, which Trovacast cannot pause. record is available only on calls Trovacast records itself; a sensitive gather on such a call is refused — nothing is collected — because the digits would land in a recording nobody can stop (sensitiveGather: false in GET /v1/calls/channels). A flow’s sensitive gather fails its run with this as flow.cause.What to do: Do not retry on this call. Collect card numbers and PINs on a call that is not recorded, or on a channel whose sensitiveGather is true (it pauses the carrier’s recording for the gather). |
RECORDING_PAUSE_FAILED | 503 | A sensitive gather needed the carrier to pause its own recording of the call, and the carrier did not confirm it (it refused, could not be reached, or had no recording to pause yet). Nothing was collected and no prompt was played. A flow’s sensitive gather fails its run with this as flow.cause.What to do: Retry the gather shortly with a new Idempotency-Key (a call action stores this error against its key). If it keeps failing, collect the digits on a call that is not recorded. |
TEST_MODE_UNSUPPORTED | 422 | A test-mode key (tc_test_…) cannot perform this: either it has no sandbox — managing templates, the WhatsApp account or email domains, writing broadcasts, renting numbers — or it would read or change live data: a recording, a contact export, consent, changing or erasing an existing contact, or changing live call flows, applications and AI agents. (A live customer’s conversation, or a live message to quote or react to, is not refused but not found: 404.) See Authentication.What to do: Repeat the request with a live key (tc_live_…); no test key can do it. In test mode, work on the test records your test key created instead. |
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. |