Trovacast

Get started

Place a call to your agent

Dial a contact through Trovacast and run the conversation from your own voice agent over a WebSocket — then follow the call, hang up and fetch the recording.

In this quickstart Trovacast dials a phone number and, when the contact answers, streams the call’s audio to a WebSocket server you run. Your server hears the contact, plays audio back and decides when the call ends. The full reference is Calls.

Before you start

  • Calling enabled for your organization (GET /v1/me shows entitlements.calling: true). Organizations provisioned through the API start messaging-only; talk to us to switch calling on.
  • A calling channel that can stream to your agent, and a funded prepaid wallet.
  • Your agent’s WebSocket endpoint: a public wss:// URL with a valid TLS certificate, and a secret token it will check on every connection.
  • Recording consent. Organizations record every call by default, so each call carries the consent evidence you collected — the notice the contact heard or saw, when and how.
  • AI calls switched on — for a live call. An EXTERNAL_AGENT call is machine-run, so it answers to the organization’s AI-call switch, which is off for a new organization: until it is on, a live key’s call is refused 409 AI_CALLS_DISABLED. Switch it on once, with a live key holding settings:write — PATCH /v1/settings/calls with { "aiCallsEnabled": true, "version": … } (the version from GET /v1/settings/calls) — or in the console under Settings → Calls. Test keys never need it: a test call goes to the sandbox.
Switch AI calls on (live key)
curl -X PATCH 'https://api.trovacast.com/v1/settings/calls' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "aiCallsEnabled": true,
  "version": 1
}'

Create a key

In the console, under Settings → Developers, create a key with calls:write and calls:read. Add contacts:write to dial a number that is not yet a contact, and recordings:read to fetch recordings. See Authentication.

Check your channels

List the channels a call can use. Pick one where externalAgent and ready are both true; the one marked default is used when a call names none.

List the call channels
curl 'https://api.trovacast.com/v1/calls/channels' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"

Run an agent

Your agent is a WebSocket server. Trovacast connects with Authorization: Bearer <token>, sends a start frame, then the contact’s audio in 20 ms media frames (base64 PCM16, 16 kHz mono); you send media frames back to be played. This minimal agent, written with the ws package for Node.js, plays the contact’s own voice back to them and hangs up when they press #. Run it behind a TLS-terminating proxy so it is reachable as wss://.

agent.mjs — an echo agent (javascript)
import { timingSafeEqual } from 'node:crypto';
import { WebSocketServer } from 'ws';

const expected = Buffer.from(`Bearer ${process.env.AGENT_STREAM_TOKEN}`);

const server = new WebSocketServer({
  port: 8080,
  // Refuse any connection that does not carry your token.
  verifyClient: ({ req }) => {
    const given = Buffer.from(req.headers.authorization ?? '');
    return given.length === expected.length && timingSafeEqual(given, expected);
  },
});

server.on('connection', (socket) => {
  socket.on('message', (data) => {
    const frame = JSON.parse(data.toString());
    switch (frame.event) {
      case 'start':
        console.log('call', frame.callId, 'to …' + frame.to.last4, 'resumed:', frame.resumed);
        break;
      case 'media':
        // 20 ms of the contact's audio. Play it straight back.
        socket.send(JSON.stringify({ event: 'media', payload: frame.payload }));
        break;
      case 'dtmf':
        if (frame.digit === '#') {
          socket.send(JSON.stringify({ event: 'hangup', reason: 'caller_pressed_hash' }));
        }
        break;
      case 'stop':
        console.log('stream ended:', frame.reason);
        break;
    }
  });
});

The ws package answers Trovacast’s keep-alive pings for you. Trovacast sends one every 10 seconds, and a stream that misses a pong is treated as a lost agent: the contact hears a short apology and the call ends.

Place the call

Ask for the call with your agent’s URL and token. Send an Idempotency-Key — a retry with the same key answers the call already placed instead of dialling twice.

Place the call
curl -X POST 'https://api.trovacast.com/v1/calls' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: call-order-1042' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "EXTERNAL_AGENT",
  "to": {
    "phone": "+919876543210"
  },
  "agent": {
    "streamUrl": "wss://agent.example.com/trovacast/stream",
    "token": "AGENT_STREAM_TOKEN",
    "audio": {
      "encoding": "pcm_s16le",
      "sampleRate": 16000
    }
  },
  "recording": {
    "enabled": true,
    "consentEvidence": {
      "source": "WEB_FORM",
      "text": "I agree to a recorded call about my order.",
      "capturedAt": "2026-11-05T09:30:00.000Z"
    }
  },
  "maxDurationSec": 300,
  "metadata": {
    "orderId": "1042"
  }
}'

The answer is the call, initiating (or queued while the carrier confirms). If it is refused instead, the error’s code says why — outside the calling window, no consent evidence, not enough credit; see What is checked, in order. When the contact answers, your agent receives the start frame.

Follow the call

Subscribe a webhook endpoint to the call events (your key needs calls:read, and recordings:read for call.recording.ready). They arrive as the call rings, is answered and ends — call.completed carries the duration and who hung up. New to webhooks? Start with Receive webhooks.

EventWhen it is sentKey scopes
call.queuedA call was handed to the carrier. The call was created and its dial handed to the carrier.data: callcalls:read
call.ringingThe contact’s phone is ringing — or a routed inbound call is ringing someone. The carrier reports the contact’s phone ringing (ringing: null). On an inbound call its number’s flow routes, a connect step started ringing: ringing names who — each party by its place in the step’s targets and your reference, a number by its last four digits and the registered phone it is — and how (strategy). Once per party in a sequence, once for all at once.data: call, ringingcalls:read
call.answeredThe contact answered — or someone took a routed inbound call. The conversation is live (answeredBy: null for an outbound call’s own answer). On an inbound call its number’s flow routes, someone took the caller: answeredBy.target says who (a number by its last four digits and the registered phone it is, a seat, an app, the queue a seat took the caller from) and confirmed whether they pressed the connect’s confirm key. A pickup that never confirmed is never told.data: answeredBy, callcalls:read
call.completedA connected call ended. With call.durationSeconds and who hung up (call.hangup.side).data: callcalls:read
call.failedA call failed, or was cancelled before an answer. call.failure says why.data: callcalls:read
call.no_answerThe contact did not answer. The call rang out unanswered.data: callcalls:read
call.busyThe contact’s line was busy. The carrier reported the line busy.data: callcalls:read
call.recording.readyA call’s recording is stored. call.recording has its id, format and duration. No link rides on the event: fetch one from GET /v1/calls/{callId}/recording (recordings:read, which subscribing to this event also needs).data: callcalls:readrecordings:read
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
call.heldA hold action put the caller on hold. Fired by the hold action.data: actionId, callcalls:read
call.resumedA resume action took the caller off hold. Fired by the resume action.data: actionId, callcalls:read
call.transferredA transfer connected the caller elsewhere. An outside number answered (its last four digits), or a call flow, a voice application or a queue took the call over.data: actionId, call, transfercalls:read
call.gather.completedA gather action finished. With the keys pressed or what the caller said — never the digits of a sensitive gather.data: actionId, call, gathercalls:read
call.flow.failedA call’s flow failed and the call was hung up. The platform hung up rather than leave the caller on a silent line. call.failure carries the documented FLOW_* code; flow says where it failed.data: call, flowcalls:read
call.machine_detectedThe carrier told a person from an answering machine. On a call that asked (machineDetection): call.machineDetection.result is human, machine or unknown. Once per call.data: callcalls:read
call.transcript.readyA call’s transcript is complete. Read it with GET /v1/calls/{callId}/transcript (transcripts:read, which subscribing also needs): the event counts the segments, never carries the text. Fires only when something was transcribed.data: call, transcriptcalls:readtranscripts:read
call.summary.readyThe AI summarised and graded a call. summary is what GET /v1/calls/{callId}/summary returns (status: ready). Once per call; an agent’s later wrap-up fires no second event. An AI agent’s test call fires it too, with the sandbox’s mock summary of its scripted conversation (summary.mock: true).data: call, summarycalls:readtranscripts:read
call.transcript.segmentOpt-inOne line of a live call’s transcript. As soon as it is stored: the item GET /v1/calls/{callId}/transcript lists, phone numbers masked to their last four digits. Opt-in — sent only to an endpoint that names it — because it fires once per utterance. Deliveries are not ordered: order by segment.sequence. Never sent for what is said while a sensitive gather is open.data: callId, livemode, segmentcalls:readtranscripts:read
call.ratedA call’s charge was written. call.charge is the charge as GET /v1/calls/{callId} reads it — status (charged, waived or not_connected), amount, minutes, and the rule and reason it was rated by. A call is rated after its final call.* event, which carries charge: null. Once when it is rated; an unrated charge (no price yet) fires nothing until a re-rate or the backfill charges it, and a charged call fires again only when it is re-rated on corrected minutes. A test call is never rated, so it never fires.data: callcalls:read
call.missedAn inbound caller reached nobody. Every route the call tried went unanswered, the caller hung up waiting, or the business was closed. missed.reason says which; missed.voicemail is the message they left, when they left one (its audio is the call’s recording). Once per call, when its flow ends — the call’s own final event (call.completed) is separate. Text them back, or call them back, from here.data: call, missedcalls:read
call.voicemail.readyA caller’s message is ready, with its transcript. The voicemail a caller left: its audio (voicemail.recordingId, fetched with GET /v1/calls/{callId}/recording?recordingId=), the key they pressed (voicemail.key) and — when the voicemail step asked — their words from the call’s live transcript (voicemail.transcript, phone numbers masked to their last four digits). Once per voicemail, a few seconds after the message ends, when the transcript of it has landed; it can come after the call’s call.missed. Needs transcripts:read as well as calls:read.data: call, voicemailcalls:readtranscripts:read
call.ai.transferAn AI call’s agent handed the caller to a person. The call names a transfer (its own, its ai route’s, or its session webhook’s) and its agent asked for a person. transfer.outcome is answered (the person has the caller and the agent left the call), no_answer or failed (cause says why: NO_ANSWER, BUSY, UNCONFIRMED, or the dial’s refusal such as DESTINATION_BLOCKED) — then the caller is back with the agent (returnedToAi). Once per hand-off (transfer.id); a call can hand off again after coming back.data: call, transfercalls:read
call.ai.opt_outAn AI call’s caller opted out and was marked do-not-call. The caller pressed the call’s opt-out key (optOut.method: dtmf, key) or said one of its phrases (speech, phrase — the configured phrase, never their words). The contact was marked do-not-call in the same transaction (optOut.doNotCall; the contact reads doNotContact: true and every call to them is refused CONTACT_DO_NOT_CALL), then the agent said the reply and the call ended. Once per call.data: call, optOutcalls:read
call.dtmfOpt-inA key the caller pressed during an AI conversation, or a flow that tells keys. Opt-in: sent only to endpoints that name it. One per key the caller pressed during an AI conversation (an AI call, or an AI step of a flow) or — P7 — during the steps of a flow that opts in (events: { dtmf: true }) — never one pressed into a sensitive gather.data: call, dtmfcalls:read

Hang up from your server

Your agent can end the call with a hangup frame, and so can your server. The call is answered as ending; call.completed follows with hangup.side: "agent".

End the call
curl -X POST 'https://api.trovacast.com/v1/calls/CALL_ID/hangup' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: hangup-order-1042'

Fetch the recording

After call.recording.ready, ask for a download link. It lasts about 15 minutes and is a credential to the contact’s voice: download the audio, then discard the link.

Get the recording link
curl 'https://api.trovacast.com/v1/calls/CALL_ID/recording' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"

Next steps