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(andcontacts:writeto dial a number that is not yet a contact). - Calling enabled, a funded wallet, and a channel with
flows: trueinGET /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
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"
}
}'{
"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.totakes exactly one ofnumberoragentMembershipId(a seat: the call is offered to that agent’s softphone).promptis spoken to the customer while the target rings;whisperto the target only, before they are connected;noAnswerMessageto the customer when the target does not answer withinringTimeoutSec, 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
parentCallIdset: list both withGET /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.