Trovacast

Voice

Inbound calls

Answer calls to your numbers with a call flow, a queue, a person or your own server: a voice application whose answer URL tells Trovacast what to do.

A call to one of your numbers goes where the number’s route says: a published call flow, a queue, one person, or a voice application — your own server, asked what to do over HTTPS. Set the route with PATCH /v1/numbers/{numberId} (Phone numbers). When the call reaches its route, call.inbound fires with the call: direction: inbound, to your number they dialled (international format) with its numberId, and from the caller masked to their last four digits (•••• ••3210) — the way an outbound call’s to names its contact.

Create a voice application

An application is an answer URL, an optional fallback URL, a deadline of at most 4 seconds and a signing secret. The secret is shown once, in the answer that creates the application (and in the answer to rotate-secret) — store it then. Applications need applications:write.

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": "Support line",
  "answerUrl": "https://voice.example.com/answer",
  "fallbackUrl": "https://voice.example.com/fallback",
  "timeoutMs": 3000
}'
201 — with the secret, this once (json)
{
  "object": "voice_application",
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "name": "Support line",
  "answerUrl": "https://voice.example.com/answer",
  "fallbackUrl": "https://voice.example.com/fallback",
  "timeoutMs": 3000,
  "secretLast4": "a1B2",
  "secret": "whsec_…",
  "version": 1,
  "createdAt": "2026-11-05T10:00:00.000Z",
  "updatedAt": "2026-11-05T10:00:00.000Z"
}

What your answer URL receives

When a call routed to the application is answered (or a mode: FLOW call naming it connects), Trovacast POSTs JSON to the answer URL:

POST https://voice.example.com/answer (http)
Content-Type: application/json
User-Agent: Trovacast-Voice/1
Trovacast-Request-Id: 6f0c2d8e-…
Trovacast-Signature: t=1762336800,v1=5d41402a…

{
  "version": 2,
  "event": "call.answer",
  "requestId": "6f0c2d8e-…",
  "applicationId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "livemode": true,
  "call": {
    "object": "call",
    "id": "2c9d8e7f-…",
    "organizationId": "…",
    "livemode": true,
    "direction": "inbound",
    "from": "•••• ••3210",
    "to": "+918035550100",
    "numberId": "5a6b7c8d-…",
    "contactId": "3f1c2a9e-…"
  },
  "timestamp": "2026-11-05T10:00:00.000Z"
}
  • call reads as the call resource does: from is the calling number and to the number dialled, whichever way the call goes — on an inbound call from is the caller masked to the last four digits (never the number itself) and to your number; on an outbound mode: FLOW call from is your caller ID and to the contact, masked. numberId is your number’s id, contactId the contact’s.
  • This is payload 2 (version: 2), what every application made from 2026-11-06 22:35 UTC is sent (payloadVersion on the application). Payload 1 is deprecated and removed after 2027-02-08: an older application keeps it — call.from is the contact { contactId, last4 } whichever way the call goes, call.to the business number, direction in upper case, no livemode — until you switch it with PATCH /v1/applications/{applicationId} { "payloadVersion": 2 }.
  • Test keys can create their own test applications and place test calls naming them (held to every rule a live call is), but the call sandbox never fetches an answer URL — it carries no audio and runs no instructions — so the first request your server gets is a live call’s. Test your handler by posting this request shape to it yourself.
  • Trovacast-Signature signs the raw body with the application’s secret, exactly as webhooks are signed: verify it before you act, and reject an old t.
  • Trovacast-Request-Id identifies the request (and is requestId in the body).

What it answers

Reply 200 with { "verbs": [ … ] } — the verbs of a call flow, run in order. A branch goes to a URL of the same application ({ "url": "https://voice.example.com/menu" }), which Trovacast POSTs to when the branch is taken; there are no nodes and no goto, and redirect takes a url.

200 — a menu that branches back to your server (json)
{
  "verbs": [
    {
      "verb": "menu",
      "prompt": [
        {
          "verb": "say",
          "text": "Press 1 to track an order, 2 to speak to us."
        }
      ],
      "options": {
        "1": {
          "url": "https://voice.example.com/track"
        },
        "2": {
          "url": "https://voice.example.com/agent"
        }
      }
    }
  ]
}

A branch request carries event naming what led to it — call.menu, call.gather, call.record, call.connect, call.enqueue, call.redirect or call.other — and result: digits and speech — { text, confidence } after a speech gather, else null — after a gather or menu, timedOut: true when nothing was pressed, recordingId and durationSeconds after a recording, outcome after a connect or enqueue.

Deadlines and failures

  • Deadline. Each request must be answered within the application’s timeoutMs — at most 4 seconds, connection to last byte.
  • Rules. https on a public host and a web or unprivileged port; redirects are not followed; at most 64 KB of response; a branch URL on another origin than the answer or fallback URL is refused.
  • Fallback. When the answer URL fails — no answer in time, a non-2xx status, a response that is too large, not JSON or not a valid document — the fallback URL is asked once with the same request. When that fails too, or there is none, the caller hears “We are sorry, we cannot take your call right now. Please try again later.” and the call ends.
  • Nothing in your responses is logged.

Outbound with an application

POST /v1/calls with mode: FLOW and flow: { applicationId } asks the application’s answer URL what to do when the contact answers. flow.answerUrl asks another URL instead for the first instructions — it must be on the application’s own origin (422 ANSWER_URL_INVALID otherwise), and is signed with the same secret.

Manage applications

  • PATCH /v1/applications/{applicationId} changes the name, URLs or deadline; send the version you read to refuse a lost update (409 VOICE_APPLICATION_VERSION_CONFLICT).
  • POST /v1/applications/{applicationId}/rotate-secret issues a new secret, shown in that answer only.
  • DELETE /v1/applications/{applicationId} is refused while numbers route to it (409 VOICE_APPLICATION_IN_USE).

Events

EventWhen it is sentKey scopes
call.inboundA call to one of your numbers reached its route. The caller is on the line, routed to a flow, an application, a queue or an agent: the call has direction: inbound, to the number of yours they dialled (international format) with its numberId, and from the caller masked to their last four digits (•••• ••3210).data: callcalls:read

Errors

CodeStatusMeaning and what to do
ANSWER_URL_INVALID422flow.answerUrl is not an https URL on the voice application’s own origin (the answer or fallback URL’s), or not one Trovacast will call (a private host, a service port). Nothing was dialled. See Inbound calls.What to do: Use an https URL on the application’s own origin, on a public host and an allowed port — or leave flow.answerUrl out to ask the application’s answer URL.
APPLICATION_NOT_FOUND404flow.applicationId (or a transfer’s to.applicationId) names no voice application of this organization.What to do: Pass an id from GET /v1/applications, using a key of the same mode as the application.
VOICE_APPLICATION_IN_USE409Numbers still route to the voice application, so it cannot be deleted.What to do: Route those numbers elsewhere first (PATCH /v1/numbers/{numberId}), then delete it again.
VOICE_APPLICATION_NAME_TAKEN409Another voice application of the organization already has that name.What to do: Choose another name, or change the existing application instead (PATCH /v1/applications/{applicationId}).
VOICE_APPLICATION_VERSION_CONFLICT409The voice application changed since the version you sent.What to do: Read it again (GET /v1/applications/{applicationId}) and retry with its new version.