Trovacast

Get started

Receive inbound calls

Buy a number, send its calls to a call flow or your own answer URL, and follow every call as it arrives with the call.inbound webhook.

In this quickstart a number of yours answers its callers: with a call flow Trovacast runs for you, or with your own server answering each call. Every call that arrives also reaches your webhook as call.inbound. Renting the number itself is Buy a number; the reference is Inbound calls.

Before you start

  • A live key with numbers:read, numbers:write, call-flows:write or applications:write, calls:read and webhooks:manage.
  • A number of yours, assigned and paid for — follow Buy a number to its 201 and keep its id and version. (A toll-free, 140- or 160-series number in India also needs an accepted letter of authority on file, whoever you are.)
  • A webhook endpoint of yours — see Receive webhooks.

Subscribe to call.inbound

Register the endpoint
curl -X POST 'https://api.trovacast.com/v1/webhook-endpoints' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://api.example.com/trovacast/webhook",
  "events": [
    "call.inbound",
    "call.completed"
  ]
}'

Store the secret from the answer — it is shown once, and every delivery is signed with it.

Choose what answers

A call flow (no server of your own)

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 line",
  "definition": {
    "version": 1,
    "start": "main",
    "nodes": {
      "main": [
        {
          "verb": "say",
          "text": "Thank you for calling Acme. Please hold for the next person."
        },
        {
          "verb": "hangup"
        }
      ]
    }
  }
}'

Publish it (POST /v1/call-flows/{callFlowId}/publish) — a number only runs a published version. The IVR quickstart builds a real menu.

Or your own server (a voice application)

Create an application
curl -X POST 'https://api.trovacast.com/v1/applications' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Main line",
  "answerUrl": "https://voice.example.com/answer",
  "fallbackUrl": "https://voice.example.com/fallback",
  "timeoutMs": 3000
}'

Store its secret (shown once). Each answered call is a signed POST to the answer URL, and your server replies with the verbs to run — { "verbs": [{ "verb": "say", "text": "Hello" }, { "verb": "hangup" }] }. The SDKs build and check these documents for you.

Route the number

Route 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": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b"
  }
}'

Or { "kind": "application", "targetId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b" } for your application. The answer is the number with its new route and version.

Call it

Call the number from any phone. You hear the flow (or what your answer URL replied), and call.inbound arrives at your webhook with the call — direction: inbound, the caller masked to their last four digits — then call.completed when it ends. Verify each delivery’s signature, and dedupe on the event id.

call.inbound (abridged) (json)
{
  "id": "evt_…",
  "type": "call.inbound",
  "createdAt": "2026-11-06T10:00:00.000Z",
  "data": {
    "call": {
      "object": "call",
      "id": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
      "direction": "inbound",
      "status": "in_progress",
      "flow": {
        "source": "call_flow",
        "callFlowId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
        "applicationId": null
      }
    }
  }
}

Next steps