Voice
Call flows
Build an IVR as a JSON document — menus, prompts, key presses, queues, transfers, business hours — validate it, publish it and point numbers or calls at it.
A call flow is a JSON document of named nodes, each a list of verbs that run in order. Trovacast runs it on the call: no server of your own is needed. Store one with call-flows:write, publish a version, then route a number to it (PATCH /v1/numbers/{numberId}), place a call that runs it (POST /v1/calls with mode: FLOW) or transfer a live call into it. Every step is an object named by its verb field — { "verb": "say", "text": "…" } — never by type.
- POST
/v1/call-flowsCreates a call flow, optionally with its first (draft) version - GET
/v1/call-flowsLists call flows, newest first - GET
/v1/call-flows/{callFlowId}Retrieves a call flow - PATCH
/v1/call-flows/{callFlowId}Renames or redescribes a call flow - POST
/v1/call-flows/validateValidates a call-flow document without saving it - GET
/v1/call-flows/{callFlowId}/versionsLists a call flow’s versions, newest first (the last 100) - POST
/v1/call-flows/{callFlowId}/versionsDrafts a new version of a call flow (publish it to make it run) - POST
/v1/call-flows/{callFlowId}/versions/{versionId}/publishPublishes a call flow version - POST
/v1/call-flows/{callFlowId}/archiveArchives a call flow
A flow document
{
"version": 1,
"start": "main",
"nodes": {
"main": [
{
"verb": "menu",
"prompt": [
{
"verb": "say",
"text": "Thanks for calling Acme. Press 1 for sales, 2 for support."
}
],
"options": {
"1": {
"node": "sales"
},
"2": {
"node": "support"
}
},
"onTimeout": {
"node": "goodbye"
}
}
],
"sales": [
{
"verb": "connect",
"to": {
"number": "+918031150000"
},
"onNoAnswer": {
"node": "goodbye"
}
}
],
"support": [
{
"verb": "enqueue",
"queue": "8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c",
"onNoAgents": {
"node": "goodbye"
}
}
],
"goodbye": [
{
"verb": "say",
"text": "Sorry we missed you. Please call again."
},
{
"verb": "hangup"
}
]
}
}versionis1;startnames the first node. Node ids are lower-case slugs. At most 64 KB, 100 nodes and 50 verbs a node.- A branch (
onTimeout, a menu option,onNoAnswer, …) is{ "node": "<id>" }in a stored flow. Every node a branch names must exist. - Every queue, schedule, seat, AI agent, voice application and caller ID a flow names is checked against your organization when it is saved, before it can run.
- A call runs at most 200 steps; a flow that loops past that ends the call.
Verbs
| Verb | Does | Fields |
|---|---|---|
say | Speaks text | text, voice, language, loop (1–10) |
play | Plays a WAV file | url (https), loop |
pause | Silence | seconds (1–60) |
gather | Collects key presses into digits, or what the caller says into speech | input (dtmf default, speech or dtmf_speech — or the list ["dtmf", "speech"]), prompt, numDigits, finishOnKey, timeoutSeconds, interDigitTimeoutSeconds, speech: language, hints, speechTimeoutSeconds (1–10), maxAttempts, sensitive (keys only), onResult, onTimeout |
menu | A prompt with one branch per key | prompt, options ("1"…"9", "0", "*", "#"), timeoutSeconds, maxAttempts, onInvalid, onTimeout |
connect | Connects the caller to a seat (agent), a number or a queue | to, callerId (one of your own numbers), timeoutSeconds, mode (bridge), whisper, record, onNoAnswer, onComplete |
enqueue | Waits in a queue for an agent | queue, priority, waitPrompt, onTimeout, onFull, onNoAgents |
ai | Hands the caller to one of your AI agents for a step: it ends the call, hands the caller back (the next verb), or — with onEscalate — passes them to a person. Its outcome is the ai variable for a switch. See An AI agent as a step | agent, objective, maxDurationSeconds (30 minutes by default), onEscalate |
record | Records the caller | maxSeconds, beep, finishOnKey, onComplete |
voicemail | Takes a voicemail for a queue’s agents | prompt, maxSeconds, queue |
send_dtmf | Presses keys on the call | digits (0-9 * #, w) |
hours | Branches on a business schedule | schedule, open, closed, holiday |
set / switch | Sets variables / branches on one (digits, or one you set) | variables / on, cases, default |
redirect | Hands the call to a voice application | application |
goto | Jumps to a node | node |
hangup | Ends the call | reason (completed, rejected, busy) |
An AI agent as a step
The ai verb (or connect with to: { ai: agentId }) hands the caller to one of your AI agents for a step of the flow, inbound or outbound: the agent hears the caller, speaks to them with its own voice, instructions and tools (plus the step's objective), and its lines join the call's transcript. The step ends one of four ways, which is also the ai variable a later switch can read:
ended— the agent finished the conversation (an end-call phrase, its turn limit, its end-call tool): its goodbye plays, then the call ends.handed_back— the agent called itshand_backtool (it is told to when its part is done, or the caller wants something it does not handle): its last line plays and the flow carries on with the next verb (onCompletefor aconnect).escalated— the agent calledtransfer_to_person, offered only when the step says where a person is (onEscalate, or aconnect'sonComplete); the flow takes that branch.max_duration—maxDurationSecondsran out (30 minutes when unset, an hour at most); the flow carries on with the next verb.failed— the agent could not run (AI calls switched off for the organization, the agent switched off or archived, its voice unable to run here — itsavailability.runnableis false, checked before the step starts,cause: AI_PROVIDER_UNAVAILABLE— its provider failing, the wallet unable to pay for an AI call): the flow takesonEscalate(onNoAnswerfor aconnect) when it has one, else the next verb — a caller is never hung up on because an agent could not answer.
Validate, store and publish
Check a document without saving it. The answer lists every problem with its path; the same problems on create are 422 CALL_FLOW_INVALID.
curl -X POST 'https://api.trovacast.com/v1/call-flows/validate' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"definition": {
"version": 1,
"start": "main",
"nodes": {
"main": [
{
"verb": "menu",
"prompt": [
{
"verb": "say",
"text": "Thanks for calling Acme. Press 1 for sales, 2 for support."
}
],
"options": {
"1": {
"node": "sales"
},
"2": {
"node": "support"
}
},
"onTimeout": {
"node": "goodbye"
}
}
],
"sales": [
{
"verb": "connect",
"to": {
"number": "+918031150000"
},
"onNoAnswer": {
"node": "goodbye"
}
}
],
"support": [
{
"verb": "enqueue",
"queue": "8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c",
"onNoAgents": {
"node": "goodbye"
}
}
],
"goodbye": [
{
"verb": "say",
"text": "Sorry we missed you. Please call again."
},
{
"verb": "hangup"
}
]
}
}
}'{
"object": "call_flow_validation",
"valid": false,
"issues": [
{
"path": "nodes.support.0.queue",
"message": "no queue 8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c in this organization"
}
]
}Create the flow with its first version, a draft. Publishing a version makes it the one calls run; until a version is published, numbers cannot route to the flow and mode: FLOW calls are 409 CALL_FLOW_NOT_PUBLISHED.
curl -X POST 'https://api.trovacast.com/v1/call-flows' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"name": "Main menu",
"description": "Sales, support and a goodbye",
"definition": {
"version": 1,
"start": "main",
"nodes": {
"main": [
{
"verb": "menu",
"prompt": [
{
"verb": "say",
"text": "Thanks for calling Acme. Press 1 for sales, 2 for support."
}
],
"options": {
"1": {
"node": "sales"
},
"2": {
"node": "support"
}
},
"onTimeout": {
"node": "goodbye"
}
}
],
"sales": [
{
"verb": "connect",
"to": {
"number": "+918031150000"
},
"onNoAnswer": {
"node": "goodbye"
}
}
],
"support": [
{
"verb": "enqueue",
"queue": "8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c",
"onNoAgents": {
"node": "goodbye"
}
}
],
"goodbye": [
{
"verb": "say",
"text": "Sorry we missed you. Please call again."
},
{
"verb": "hangup"
}
]
}
}
}'curl -X POST 'https://api.trovacast.com/v1/call-flows/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/versions/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/publish' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 1
}'{
"object": "call_flow",
"id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"name": "Main menu",
"description": "Sales, support and a goodbye",
"published": {
"versionId": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
"version": 1,
"publishedAt": "2026-11-05T10:00:00.000Z",
"definitionSha256": "3f5a…"
},
"archivedAt": null,
"version": 2,
"createdAt": "2026-11-05T10:00:00.000Z",
"updatedAt": "2026-11-05T10:00:00.000Z"
}POST /v1/call-flows/{callFlowId}/versionsadds a draft (versions are numbered 1, 2, 3… and never reused); publish it when it is ready.GET …/versionslists the latest 100.- Every change takes the flow’s
version(optional): a flow that moved since is409 FLOW_VERSION_CONFLICT. POST /v1/call-flows/{callFlowId}/archiveretires a flow no number routes to (409 FLOW_IN_USEotherwise); an archived flow takes no new version.
Put it to work
- Inbound — route a number to it:
PATCH /v1/numbers/{numberId}withroute: { kind: "flow", targetId }. See Phone numbers. - Outbound — place a call that runs it:
POST /v1/callswithmode: FLOWandflow: { callFlowId }— orflow: { definition }for a one-off document that is validated but not stored. See Calls. - Mid-call —
transfera live call to it withto: { callFlowId }. See Call control.
The step-by-step version is the IVR in 5 minutes quickstart.
Build and validate with the SDKs
The Node.js and Python SDKs build both kinds of document — a stored flow, and what an answer URL returns — with one method per verb, and check them the way the API will before you send them. A branch is node("<id>") in a flow and url("https://…") in an answer document.
import { answer, callFlow, node, url, verbs } from '@trovacast/sdk/flows';
const definition = callFlow({ start: 'main' })
.node('main', (n) =>
n.menu({
prompt: [verbs.say('Thanks for calling Acme. Press 1 for sales, 2 for support.')],
options: { '1': node('sales'), '2': node('support') },
onTimeout: node('goodbye'),
}),
)
.node('sales', (n) => n.connect({ number: '+918031150000' }, { onNoAnswer: node('goodbye') }))
.node('support', (n) => n.enqueue('8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c', { onNoAgents: node('goodbye') }))
.node('goodbye', (n) => n.say('Sorry we missed you. Please call again.').hangup())
.toJSON(); // throws CallFlowValidationError, with every issue's path
await trovacast.createCallFlow({ body: { name: 'Main menu', definition } });
// An answer URL: res.json() calls toJSON(), which validates.
app.post('/answer', (req, res) => {
res.json(
answer()
.gather({ numDigits: 1, prompt: [verbs.say('Press 1 to track an order.')], onResult: url('https://voice.example.com/track') })
.say('We did not hear anything. Goodbye.')
.hangup(),
);
});from trovacast.flows import AnswerBuilder, CallFlowBuilder, node, say, url
flow = CallFlowBuilder(start="main")
flow.node("main").menu(
prompt=[say("Thanks for calling Acme. Press 1 for sales, 2 for support.")],
options={"1": node("sales"), "2": node("support")},
on_timeout=node("goodbye"),
)
flow.node("sales").connect({"number": "+918031150000"}, on_no_answer=node("goodbye"))
flow.node("support").enqueue("8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c", on_no_agents=node("goodbye"))
flow.node("goodbye").say("Sorry we missed you. Please call again.").hangup()
# to_dict() raises CallFlowValidationError, with every issue's path
client.create_call_flow(body={"name": "Main menu", "definition": flow.to_dict()})
# An answer URL (Flask):
@app.post("/answer")
def answer():
return (
AnswerBuilder()
.gather(num_digits=1, prompt=[say("Press 1 to track an order.")], on_result=url("https://voice.example.com/track"))
.say("We did not hear anything. Goodbye.")
.hangup()
.to_dict()
)- Options are the API's fields — camelCase in Node.js, snake_case keyword arguments in Python (
timeout_seconds,on_result;set_andswitch_). - What is checked: the published JSON Schemas (
CallFlowDocument,CallFlowAnswerDocumentand oneCallFlowVerb…per verb, inGET /v1/openapi.json), and the rules a schema cannot carry — a flow branches only to its own nodes and redirects only to an application; an answer document branches only to URLs, has nogotoand redirects only to a URL; asensitivegather takes keys only; at most 64 KB, 100 nodes and 50 verbs a node. validateCallFlow(document)/validate_call_flow(document)check a document built any other way and return{ ok, issues }— each issue apathand amessage, asPOST /v1/call-flows/validateanswers.- The API still checks what only it can — that the queues, schedules, seats and numbers a document names are your organization's — so keep handling
422 CALL_FLOW_INVALID.
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
CALL_FLOW_INVALID | 422 | The call-flow document does not validate; issues lists each problem with its path. See Call flows.What to do: Fix each problem in issues at its path and send the document again; check drafts first with POST /v1/call-flows/validate. |
CALL_FLOW_NOT_FOUND | 404 | flow.callFlowId (or a transfer’s to.callFlowId) names no call flow of this organization, or an archived one.What to do: Pass the id of a call flow that is not archived (GET /v1/call-flows), using a key of the same mode as the flow. |
CALL_FLOW_NOT_PUBLISHED | 409 | The call flow has no published version to run.What to do: Publish a version with POST /v1/call-flows/{callFlowId}/versions/{versionId}/publish, then retry. |
FLOW_ARCHIVED | 409 | The call flow is archived: it takes no new version and cannot be published.What to do: Do not retry: create a new call flow (POST /v1/call-flows) with the document instead. |
FLOW_INVALID | 422 | The call-flow service refused the document on save or publish (the backstop of CALL_FLOW_INVALID), for example a target that no longer exists.What to do: Validate the document again (POST /v1/call-flows/validate), fix what it names, then save or publish again. |
FLOW_IN_USE | 409 | Numbers still route to the call flow, so it cannot be archived.What to do: Route those numbers elsewhere first (PATCH /v1/numbers/{numberId}), then archive it again. |
FLOW_NAME_TAKEN | 409 | Another call flow of the organization already has that name.What to do: Choose another name, or change the existing flow instead (PATCH /v1/call-flows/{callFlowId}). |
FLOW_VERSION_CONFLICT | 409 | The call flow changed since the version you sent.What to do: Read it again (GET /v1/call-flows/{callFlowId}) and retry with its new version. |