Get started
IVR in 5 minutes
Write a call flow with a menu and business hours, publish it, and answer a number with it — or place a call that runs it.
In this quickstart you build a small IVR — open or closed by your business hours, a menu, a transfer to sales — and put it on a phone number. Trovacast runs it; no server of your own. The full reference is Call flows.
Before you start
- A key with
call-flows:write, andnumbers:writeto route a number (orcalls:writeto place a call). - A number of your own that takes inbound calls — Buy a number — and, for the
hoursstep, a business schedule set up in the console (its id). - Calling enabled and a funded wallet: the transfer to sales is an outbound leg.
1. Write and check the flow
The flow starts at main, branches on the schedule, plays a menu and connects key 1 to sales. Check it first: every node a branch names must exist, and the schedule must be yours.
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": "hours",
"schedule": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
"open": {
"node": "menu"
},
"closed": {
"node": "closed"
}
}
],
"menu": [
{
"verb": "menu",
"prompt": [
{
"verb": "say",
"text": "Welcome to Acme. Press 1 for sales, 2 to hear our hours."
}
],
"options": {
"1": {
"node": "sales"
},
"2": {
"node": "closed"
}
},
"onTimeout": {
"node": "closed"
}
}
],
"sales": [
{
"verb": "connect",
"to": {
"number": "+918031150000"
},
"onNoAnswer": {
"node": "closed"
}
}
],
"closed": [
{
"verb": "say",
"text": "We are open 9 to 6, Monday to Saturday. Goodbye."
},
{
"verb": "hangup"
}
]
}
}
}'2. Create and publish it
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": "Front desk",
"definition": {
"version": 1,
"start": "main",
"nodes": {
"main": [
{
"verb": "hours",
"schedule": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
"open": {
"node": "menu"
},
"closed": {
"node": "closed"
}
}
],
"menu": [
{
"verb": "menu",
"prompt": [
{
"verb": "say",
"text": "Welcome to Acme. Press 1 for sales, 2 to hear our hours."
}
],
"options": {
"1": {
"node": "sales"
},
"2": {
"node": "closed"
}
},
"onTimeout": {
"node": "closed"
}
}
],
"sales": [
{
"verb": "connect",
"to": {
"number": "+918031150000"
},
"onNoAnswer": {
"node": "closed"
}
}
],
"closed": [
{
"verb": "say",
"text": "We are open 9 to 6, Monday to Saturday. Goodbye."
},
{
"verb": "hangup"
}
]
}
}
}'Take the draft’s id from GET /v1/call-flows/{callFlowId}/versions and publish it with the flow’s 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
}'3. Answer a number with it
curl -X PATCH 'https://api.trovacast.com/v1/numbers/6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 3,
"route": {
"kind": "flow",
"targetId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}'Call the number: you hear the menu (or the closing message out of hours), and call.inbound arrives at your webhook. To change the IVR, add a version (POST /v1/call-flows/{callFlowId}/versions) and publish it — the number follows the published version.
Or: place a call that runs it
The same flow can run on an outbound call: when the contact answers, they hear it. The channel must carry flows (flows: true in GET /v1/calls/channels).
curl -X POST 'https://api.trovacast.com/v1/calls' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: ivr-call-1042' \
-H 'Content-Type: application/json' \
-d '{
"mode": "FLOW",
"contactId": "3f1c2a9e-0d4b-4c55-9b1e-2f6a7c8d9e01",
"flow": {
"callFlowId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
},
"purpose": "SERVICE",
"recording": {
"enabled": true,
"consentEvidence": {
"source": "VERBAL",
"text": "This call is recorded for quality and training.",
"capturedAt": "2026-11-05T09:30:00.000Z"
}
},
"maxDurationSec": 600
}'