Trovacast

Get started

Click-to-call

Connect a customer to your team with one request: Trovacast rings the customer, then connects them to a number or an agent’s softphone.

A BRIDGE call dials the customer first. When they answer, they hear your prompt while Trovacast rings the target — an outside number, or an agent’s softphone — and the two are connected when the target answers. To ring the agent first — their own phone, then the customer once they answer — send bridge.ringFirst: "agent" with to.agentMembershipId on a channel with agentFirst: true (Calls).

Before you start

  • A key with calls:write (and contacts:write to dial a number that is not yet a contact).
  • Calling enabled, a funded wallet, and a channel with flows: true in GET /v1/calls/channels — a bridge needs the call’s audio to stream through Trovacast.
  • The target number on your organization’s list of destinations for connected parties (India by default), or the id of an active seat.

Place the call

Connect a customer to the sales desk
curl -X POST 'https://api.trovacast.com/v1/calls' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: click-to-call-T-1042' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "BRIDGE",
  "to": {
    "phone": "+919876543210"
  },
  "bridge": {
    "to": {
      "number": "+918031150000"
    },
    "prompt": "Thanks for your request. Connecting you to our sales team.",
    "whisper": "Web callback: customer asked about the annual plan.",
    "noAnswerMessage": "Sorry, our team is busy. We will call you back shortly.",
    "ringTimeoutSec": 30
  },
  "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": 900,
  "metadata": {
    "ticketId": "T-1042"
  }
}'
201 — the customer’s call (json)
{
  "object": "call",
  "id": "2c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
  "contactId": "3f1c2a9e-0d4b-4c55-9b1e-2f6a7c8d9e01",
  "direction": "outbound",
  "mode": "bridge",
  "status": "initiating",
  "purpose": "service",
  "parentCallId": null,
  "rootCallId": null,
  "legRole": "primary",
  "bridge": {
    "target": "number",
    "numberLast4": "0000",
    "agentMembershipId": null
  },
  "metadata": {
    "ticketId": "T-1042"
  },
  "createdAt": "2026-11-05T10:00:00.000Z",
  "updatedAt": "2026-11-05T10:00:00.000Z"
}
  • bridge.to takes exactly one of number or agentMembershipId (a seat: the call is offered to that agent’s softphone).
  • prompt is spoken to the customer while the target rings; whisper to the target only, before they are connected; noAnswerMessage to the customer when the target does not answer within ringTimeoutSec, before the call ends.
  • The call shows the target by its last four digits only. The leg dialled to the target is a call of its own with parentCallId set: list both with GET /v1/calls?rootCallId={callId}.
  • Send an Idempotency-Key — a retried request answers the call it placed instead of ringing the customer twice.

Follow it

The customer’s call sends the usual call.* events; act on it while it is live — hold, transfer, hang up — with Call control. A target that is not yours or outside your destinations is refused before anything is dialled (BRIDGE_AGENT_NOT_FOUND, CHILD_DIAL_DESTINATION_NOT_ALLOWED); a target that does not answer in time leaves the customer with noAnswerMessage.