Tonedocs
API referenceCalls

Hand a live call to a person

Asks the agent on the call to transfer it to one of the destinations it may use, exactly as if it had decided to itself: the caller hears the transfer line, the person hears the brief, and every rule still applies — the destination must be verified, inside its hours and one of the agent's destinations, and a call makes at most two attempts. A transfer that cannot start is accepted: false with a refusal, not an error. 409 call_not_live when no agent is on the call. Send an Idempotency-Key to make a retry safe.

Open in ClaudeOpen in ChatGPTView as Markdown

Requires the write scope. A key with less gets 403 insufficient_scope.

POST
/v1/calls/{id}/transfer

Authorization

AuthorizationBearer <token>

Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.

In: header

Path Parameters

id*string

The call's id.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/calls/string/transfer" \  -H "Content-Type: application/json" \  -d '{    "destinationId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "handoff": "warm",    "note": "Wants the premium plan, ready to pay today.",    "reason": "qualified_lead"  }'
{  "data": {    "accepted": true,    "refusal": null,    "transfer": {      "acceptedAt": null,      "answeredAt": "2026-10-13T10:01:41Z",      "attempt": 1,      "bridgedAt": "2026-10-13T10:01:52Z",      "brief": "Transfer from Acme's digital assistant, about a complaint. This call is recorded. Press 1 to take the call.",      "destination": {        "label": "Delivery team"      },      "endedAt": "2026-10-13T10:05:12Z",      "hasRecording": true,      "hasReturnRecording": false,      "humanSeconds": 200,      "id": "5b2c1e3d-9a4f-4e6b-8c7d-1f2e3a4b5c6d",      "mode": "screened",      "outcome": null,      "reason": "out_of_scope",      "requestedAt": "2026-10-13T10:01:30Z",      "status": "bridged",      "trigger": "model"    }  }}
Was this page helpful?

Fetch a call's audio recording (WAV)

Streams the recording as audio/wav, in stereo: the caller on the left channel, the agent on the right. Not enveloped, and often several megabytes. Absent when recording is off for the number, or when the call never connected.

Fetch a call's transcript

The turn-by-turn transcript, once the call has ended. A call with no audio — a sandbox call, an unanswered one — has no transcript.