Voice
AI over the API
Read a call’s transcript and the AI’s summary of it, hear when each is ready, let an AI agent answer a number, and switch AI calls on or off.
Every call that streams through Trovacast is transcribed as it happens, and once it ends the AI grades it: a short summary, an outcome, the contact’s mood and any callback time they asked for. Read both with transcripts:read — a transcript is the contact’s own words, so calls:read alone never returns it — and subscribe to the events that say when each is final.
- GET
/v1/calls/{callId}/transcriptReads a call’s transcript, oldest first - GET
/v1/calls/{callId}/summaryReads the AI’s summary, outcome and sentiment of a call - GET
/v1/settings/callsReads the organization’s call settings (whether AI calls are on) - PATCH
/v1/settings/callsTurns AI calls on or off, and recording of every call, for the organization
Read a transcript
Segments come oldest first, a page at a time (limit up to 100, then cursor), each with its speaker — contact, agent, ai, or unknown when a carrier stream mixes both sides — and its offset from the start of the call. While the call is live you get what has been transcribed so far (status: pending); once it ends and the last segments are stored the transcript is ready, or unavailable when nothing was transcribed — and then unavailableReason says why: disabled (a test call no AI agent ran, or an external-agent call — your agent hears it), too_short (not answered, or nothing said long enough), processing_failed (transcribed but not stored), stt_unavailable (the speech-to-text was down) or not_recorded (no audio of the call reached Trovacast). gaps lists when the call’s speech-to-text was down (startedAt, endedAt, phase), readable while the call is up: speech in a gap was not transcribed, so a ready transcript with gaps is a partial one.
curl 'https://api.trovacast.com/v1/calls/2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f/transcript' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "call_transcript",
"callId": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
"status": "ready",
"unavailableReason": null,
"gaps": [],
"finalizedAt": "2026-11-08T10:05:00.000Z",
"data": [
{
"object": "transcript_segment",
"id": "8b7c6d5e-4f3a-4b2c-8d1e-0f9a8b7c6d5e",
"sequence": 1,
"revision": 1,
"speaker": "ai",
"text": "Hello, this is Acme’s delivery assistant calling about order 1042.",
"startMs": 1200,
"endMs": 4800,
"language": "en-IN",
"confidence": 0.94,
"createdAt": "2026-11-08T10:00:06.000Z"
},
{
"object": "transcript_segment",
"id": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
"sequence": 2,
"revision": 1,
"speaker": "contact",
"text": "I’m out today — call me back tomorrow on •••• ••2345.",
"startMs": 5400,
"endMs": 8900,
"language": "en-IN",
"confidence": 0.88,
"createdAt": "2026-11-08T10:00:10.000Z"
}
],
"nextCursor": null
}- A phone number spoken on the call is masked to its last four digits, as it is everywhere the API shows one. No speaker is named: the contact is the call’s
contactId. - A key reads the calls of its own mode only — a live call’s transcript or summary is
404to a test key, and a test call’s to a live key, exactly as an unknown id. An answered test call an AI agent runs (mode: AI_AGENT) gets the sandbox’s scripted eight-line conversation (the sandbox carries no audio), delivered ascall.transcript.segmentevents when it is answered and finalized withcall.transcript.readywhen it ends. AFLOW,BRIDGEorEXTERNAL_AGENTtest call is not scripted — the sandbox runs no flow, so nothing spoke — and its transcript readsunavailable. Another organization’s call is404.
Read the summary
The summary is what the platform computes once a call ends, nothing more: the AI’s summary, its disposition (one of eight outcomes), the contact’s sentiment, its confidence, and followUpAt when the contact named a callback time. outcome is the call’s result as Trovacast reports it — the agent’s wrap-up when a person filed one (source: agent), else the AI’s verdict; when the agent picked one of your own wrap-up codes, code and label name it as they picked it, and value is the standard outcome it counts as. Every field is null until the call is graded (status: pending); unavailable means it never will be (nothing to grade, or no AI provider on the deployment).
curl 'https://api.trovacast.com/v1/calls/2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f/summary' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "call_summary",
"callId": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
"status": "ready",
"summary": "The customer is out today and asked to be called back tomorrow afternoon.",
"disposition": "callback_requested",
"sentiment": "neutral",
"confidence": 0.86,
"followUpAt": "2026-11-09T08:30:00.000Z",
"analyzedAt": "2026-11-08T10:05:20.000Z",
"outcome": {
"value": "callback_requested",
"source": "ai",
"code": null,
"label": null
}
}Hear when they are ready
call.transcript.ready fires once, when the transcript is complete and something was transcribed. It carries the call and a transcript block with segmentCount and finalizedAt — never the text, which is the contact’s words and can run to hundreds of segments: read it with GET /v1/calls/{callId}/transcript. call.summary.ready fires once, when the summary is written, and carries the call and the same summary object the GET returns. Subscribing an endpoint to either needs calls:read and transcripts:read.
| Event | When it is sent | Key scopes |
|---|---|---|
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 |
Follow a live transcript
Two ways to hear a call’s words while it is live, both under calls:read and transcripts:read (transcripts:read alone for the stream). Each carries a final segment exactly as the transcript read lists it — phone numbers in it masked to their last four digits — and nothing said while a sensitive gather is open is ever transcribed (the recording pauses for it too).
call.transcript.segment— a webhook per stored segment. Opt-in: an endpoint gets it only when you list it (the console’s Select all leaves it out), because it fires once per utterance of every call — typically 10 to 30 a minute of conversation. Deliveries are not ordered and may be retried: order bysegment.sequenceand dedupe by the eventid. A leg dialled from a call tells none of its own.livemodesays which mode the call is.GET /v1/calls/{callId}/transcript/stream— the same segments as Server-Sent Events, in order:event: segment(the eventidis the transcript cursor, so a reconnect withLast-Event-IDresumes after the last one you saw; opening late first replays what was already said),event: pingevery 15 seconds of quiet, andevent: endonce the transcript is final (status,finalizedAt), after two hours (reason: max_duration) or if the stream is interrupted (reason: interrupted— reconnect). New segments arrive about a second after they are stored. At most 20 streams may be open per project at a time (429 RATE_LIMITED). The stream is outside the typed SDKs (they read every answer as one JSON document): use any SSE client with your key.
curl -N https://api.trovacast.com/v1/calls/$CALL_ID/transcript/stream \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Accept: text/event-stream"Let an AI agent answer a number
Route a number to an AI agent (route.kind: ai) and the agent answers its inbound calls itself, on the same media path as an AI call you place: the call reads mode: ai, direction: inbound, with aiAgentId set, fires call.inbound, is transcribed, graded and billed per minute as an AI call. The agent must be active, and AI calls switched on for the organization (409 AI_CALLS_DISABLED otherwise).
curl -X PATCH 'https://api.trovacast.com/v1/numbers/1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 4,
"route": {
"kind": "ai",
"targetId": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a"
}
}'- If AI calls are switched off later, or the agent is switched off, the number keeps its route and its callers hear a short apology before the line closes. The call is recorded —
failedwithfailure.code: AI_AGENT_UNAVAILABLE, andcall.failedfires — and never billed. The number says so first, on every read:warningsAI_AGENT_UNAVAILABLEwithreasonAI_CALLS_DISABLEDorAGENT_INACTIVE. Switching an agent off stays allowed — new calls, new AI steps, re-attaches and campaign dials stop using it at once, while a conversation it is already having finishes (hang that call up to stop it now) — and thePATCH /v1/agents/{agentId}answer lists the numbers it leaves refusing their calls (warnings, each with itsnumberId, andflowIdfor a flow’s AI step). So doDELETE /v1/agents/{agentId}— archiving an agent only a routed flow’s AI step names is allowed, and answers200with the archived agent and itswarnings— andPATCH /v1/settings/calls. A route or step that fails for more than one cause carries one warning per cause, under the samenumberId(2026-11-07). An archived agent cannot be switched back on, so its warning says to route the step or the number to another agent; a switched-off one’s says to switch it on (2026-11-07). A key withoutnumbers:readis told only which number fails and why (numberId,code,reason;detail: false). Archiving an agent a number’sairoute answers with is409 AI_AGENT_IN_USE: route the number elsewhere first. Pointing a number at a new AI agent that cannot take calls is refused with the codePOST /v1/callsanswers the same cause with:409 AI_CALLS_DISABLED,409 AI_AGENT_INACTIVE,404 AI_AGENT_NOT_FOUND(a test agent reads as an unknown one),422 AI_PROVIDER_UNAVAILABLE. - Your plan must price inbound AI calls on the number’s channel (
GET /v1/pricing,direction: inbound,callType: full_ai). When it does not, the route is still saved and the number says so inwarnings(BILLING_RATE_UNAVAILABLE); with billing enforced each call is refused with the same apology and recordedfailedwith that code. A call whose AI voice never started — the caller was answered and no AI voice came up (AI_PROVIDER_UNAVAILABLE) — is charged at the channel’s manual rate, not the AI rate; an AI voice that started and stayed silent is billed as AI. A number whose agent can no longer speak here (a key or credential alias it needs is gone) says so inwarningstoo (AI_PROVIDER_UNAVAILABLE, with the agent’savailability.reason). - Inbound routing runs on numbers from the Trovacast inventory on channels that stream inbound media. An AI agent can also take a step inside a call flow — the
aiverb, orconnectto an AI agent — and hand the caller back or to a person afterwards (Call flows → An AI agent as a step).
Turn AI calls on or off
aiCallsEnabled is the organization’s switch for machine-run calls — AI_AGENT and EXTERNAL_AGENT calls, AI campaigns and numbers routed to an AI agent; the console’s calling policy is the same switch. Read it with settings:read; change it with settings:write, sending the version you read (409 SETTINGS_VERSION_CONFLICT when the organization changed since). Every change is audited against the key. A test key reads it but cannot change it. Calls already live are not ended. While AI calls are off, the answer’s warnings name every number whose ai route or routed flow’s AI step now refuses its callers (AI_AGENT_UNAVAILABLE, reason: AI_CALLS_DISABLED) — only numberId, code and reason for a key without numbers:read. Either way they also name every other cause those routes and steps fail on, one warning each (2026-11-07): switched on, the answer lists the numbers that still cannot take AI calls, and why.
curl -X PATCH 'https://api.trovacast.com/v1/settings/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"aiCallsEnabled": false,
"version": 12
}'{
"object": "call_settings",
"aiCallsEnabled": false,
"recordingRequired": true,
"version": 13,
"updatedAt": "2026-11-08T10:05:00.000Z",
"warnings": [
{
"numberId": "5b0c2d6e-8f4a-4b1c-9d2e-3f4a5b6c7d8e",
"code": "AI_AGENT_UNAVAILABLE",
"direction": "inbound",
"provider": "plivo",
"callType": "full_ai",
"agentId": "0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f",
"reason": "AI_CALLS_DISABLED",
"step": null,
"flowId": null,
"detail": true,
"message": "AI calls are switched off for your organization (AI_CALLS_DISABLED), so calls to this number are refused (AI_AGENT_UNAVAILABLE): the caller hears a short apology and the call is recorded failed until they are switched on (PATCH /v1/settings/calls)."
}
]
}Errors
| Code | Status | Meaning and what to do |
|---|---|---|
AI_AGENT_IN_USE | 409 | A number routes its inbound calls to this AI agent, so it cannot be archived. See AI over the API.What to do: Route the number elsewhere first (PATCH /v1/numbers/{numberId}), then archive the agent again. |
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. |
API_KEY_SCOPE_MISSING | 403 | The key lacks the scope the endpoint (or a webhook event) requires; requiredScope names it. See Scopes.What to do: Use a key that holds requiredScope: a project administrator creates one in Settings → Developers (an existing key's scopes can be narrowed, never widened). Retrying with this key cannot succeed. |
SETTINGS_VERSION_CONFLICT | 409 | The organization changed since the version you sent to PATCH /v1/settings/calls. See AI over the API.What to do: Read the settings again (GET /v1/settings/calls) and retry with their current version. |
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. |