Trovacast

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`FieldsAnswers
speaktext (≤ 1,000 characters), voice, language (BCP 47, e.g. en-IN)started — spoken by speech synthesis
playurl: an https WAV filestarted
gatherinput (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_dtmfdigits: up to 32 of 0-9 * #, w for a half-second pausecompleted
holdaudioUrl: 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
transferto: exactly one of number, queueId, callFlowId, applicationId; ringTimeoutSec (5–120, default 30) for a numberstarted — ends with call.transferred
recordstate: pause or resumecompleted
hangup—completed — the hang-up route’s own rules
Ask for an order number
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
}'
200 — under way on the call (json)
{
  "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.

Hand the call to the main menu
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.

ChannelA sensitive gather on a recorded call
TwilioThe carrier’s recording is paused (the span kept as silence) before the action answers, and resumed when the gather ends.
TelnyxThe carrier’s recording is paused before the action answers, and resumed when the gather ends.
PlivoRefused, 409 RECORDING_NOT_CONTROLLABLE: Plivo’s recording of the call cannot be paused.
ExotelRefused, 409 RECORDING_NOT_CONTROLLABLE: Exotel’s recording cannot be paused.
Airtel IQRefused, 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 is in_progress (after call.answered). An ended call is 409 CALL_NOT_LIVE.
  • One prompt at a time — while a speak, play or gather (or a call flow) is speaking, another is 409 CALL_ACTION_IN_PROGRESS. A transfer pre-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 same Idempotency-Key (safe: it runs at most once).
  • Not on this deployment — speak without speech synthesis configured is 503 TTS_UNAVAILABLE (never silence); an option the call or deployment cannot do is CALL_ACTION_UNSUPPORTED with a reason.

Limits

  • Speech gather. input: speech (or dtmf_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 of language; it ends after speechTimeoutSec of quiet following speech, at most 60 seconds. call.gather.completed carries speech: { text, confidence } (confidence is null when the recognizer gives none). hints are accepted for every recognizer but applied only by one that takes them — today’s do not. A sensitive gather is keys-only. A deployment without speech recognition answers 422 CALL_ACTION_UNSUPPORTED with reason: speech_recognition_unavailable.
  • WAV only. play, a gather prompt.url and 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 is 422 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 is hangup: 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 transfer has 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 is ai (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) is 422 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.

EventWhen it is sentKey scopes
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

Errors

CodeStatusMeaning and what to do
AI_PROVIDER_UNAVAILABLE422mode: 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_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.
AUDIO_UNAVAILABLE422The 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_PROGRESS409Another 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_UNSUPPORTED409 or 422The 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_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.
CALL_NOT_ANSWERED409The 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_CONTROLLABLE409The 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_HELD409resume on a call that is not on hold.What to do: Nothing to resume: send resume only after a hold (call.held).
CALL_NOT_LIVE409The 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_REPLICA409The 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_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.
CHILD_LEG_LIMIT409The 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_UNSUPPORTED503The 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_INVALID422digits 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_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.
RECORDING_NOT_CONTROLLABLE409The 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_FAILED503A 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_UNSUPPORTED422A test-mode key (tc_test_…) cannot perform this: either it has no sandbox — managing templates, the WhatsApp account or email domains, writing broadcasts, renting numbers — or it would read or change live data: a recording, a contact export, consent, changing or erasing an existing contact, or changing live call flows, applications and AI agents. (A live customer’s conversation, or a live message to quote or react to, is not refused but not found: 404.) See Authentication.What to do: Repeat the request with a live key (tc_live_…); no test key can do it. In test mode, work on the test records your test key created instead.
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.