Trovacast

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, and numbers:write to route a number (or calls:write to place a call).
  • A number of your own that takes inbound calls — Buy a number — and, for the hours step, 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.

Validate the flow
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

Create the flow (version 1, a draft)
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:

Publish version 1
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

Route the number’s inbound calls to the flow
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).

Call a contact into the IVR
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
}'