Trovacast

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.

A flow document

A main menu: sales, a support queue, and a goodbye (json)
{
  "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"
      }
    ]
  }
}
  • version is 1; start names 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

VerbDoesFields
saySpeaks texttext, voice, language, loop (1–10)
playPlays a WAV fileurl (https), loop
pauseSilenceseconds (1–60)
gatherCollects key presses into digits, or what the caller says into speechinput (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
menuA prompt with one branch per keyprompt, options ("1"…"9", "0", "*", "#"), timeoutSeconds, maxAttempts, onInvalid, onTimeout
connectConnects the caller to a seat (agent), a number or a queueto, callerId (one of your own numbers), timeoutSeconds, mode (bridge), whisper, record, onNoAnswer, onComplete
enqueueWaits in a queue for an agentqueue, priority, waitPrompt, onTimeout, onFull, onNoAgents
aiHands 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 stepagent, objective, maxDurationSeconds (30 minutes by default), onEscalate
recordRecords the callermaxSeconds, beep, finishOnKey, onComplete
voicemailTakes a voicemail for a queue’s agentsprompt, maxSeconds, queue
send_dtmfPresses keys on the calldigits (0-9 * #, w)
hoursBranches on a business scheduleschedule, open, closed, holiday
set / switchSets variables / branches on one (digits, or one you set)variables / on, cases, default
redirectHands the call to a voice applicationapplication
gotoJumps to a nodenode
hangupEnds the callreason (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 its hand_back tool (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 (onComplete for a connect).
  • escalated — the agent called transfer_to_person, offered only when the step says where a person is (onEscalate, or a connect's onComplete); the flow takes that branch.
  • max_duration — maxDurationSeconds ran 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 — its availability.runnable is false, checked before the step starts, cause: AI_PROVIDER_UNAVAILABLE — its provider failing, the wallet unable to pay for an AI call): the flow takes onEscalate (onNoAnswer for a connect) 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.

Validate a document
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"
        }
      ]
    }
  }
}'
200 — one problem (json)
{
  "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.

Create a flow
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"
        }
      ]
    }
  }
}'
Publish its first version
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
}'
200 — the flow, published (json)
{
  "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}/versions adds a draft (versions are numbered 1, 2, 3… and never reused); publish it when it is ready. GET …/versions lists the latest 100.
  • Every change takes the flow’s version (optional): a flow that moved since is 409 FLOW_VERSION_CONFLICT.
  • POST /v1/call-flows/{callFlowId}/archive retires a flow no number routes to (409 FLOW_IN_USE otherwise); an archived flow takes no new version.

Put it to work

  • Inbound — route a number to it: PATCH /v1/numbers/{numberId} with route: { kind: "flow", targetId }. See Phone numbers.
  • Outbound — place a call that runs it: POST /v1/calls with mode: FLOW and flow: { callFlowId } — or flow: { definition } for a one-off document that is validated but not stored. See Calls.
  • Mid-call — transfer a live call to it with to: { 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.

Node.js (javascript)
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(),
  );
});
Python (python)
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_ and switch_).
  • What is checked: the published JSON Schemas (CallFlowDocument, CallFlowAnswerDocument and one CallFlowVerb… per verb, in GET /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 no goto and redirects only to a URL; a sensitive gather 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 a path and a message, as POST /v1/call-flows/validate answers.
  • 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

CodeStatusMeaning and what to do
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.
FLOW_ARCHIVED409The 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_INVALID422The 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_USE409Numbers 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_TAKEN409Another 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_CONFLICT409The 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.