Outbound calls
Placing a call, and reading what happened.
curl "$TONE_API/v1/calls" -X POST \
-H "Authorization: Bearer $TONE_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'content-type: application/json' \
-d "{\"agentId\":\"$AGENT\",\"numberId\":\"$NUMBER\",\"toE164\":\"+919876543210\"}"agentId is required on a number that routes to a Tone agent and
forbidden on a BYO number — the number decides which, and either mistake is a
422.
What happens before the carrier is called
The compliance gate runs inside the same transaction as the call
record. So a refusal is a 403 with the audit rows already written and no
carrier contacted — the block and its evidence are the same event.
One thing runs before the gate: your concurrency quota. Over it, you get
429 concurrent_call_limit_reached with no verdict recorded, because no dial was
attempted. That is a different failure from a rate limit and needs a different
response — see Limits.
Lifecycle
status | |
|---|---|
queued | Accepted; the carrier has not connected it yet |
in_progress | Connected |
ended | Finished. disposition now says how |
disposition | |
|---|---|
answered | A person picked up |
no_answer | Rang out |
busy | Engaged |
voicemail | An answering machine took it |
failed | The carrier could not complete it |
unknown | We genuinely do not know |
Treat both as open sets — new values can appear and are not a breaking change.
Two honesty rules worth knowing: a call abandoned in queued reads as ended
after 15 minutes, and one stuck in_progress past 65 minutes reads as ended with
unknown and bills nothing. We would rather report "we do not know" than
invent an outcome or charge for one.
Reading it back
Poll if you must, but the call log is not where you should learn a call ended:
curl "$TONE_API/v1/calls/$CALL" -H "Authorization: Bearer $TONE_KEY"Subscribe to call.completed instead. See Webhooks.
To find every call one campaign placed — retries included — filter the call log rather than reading the recipient list, which names only each recipient's last attempt:
curl -H "Authorization: Bearer $TONE_KEY" \
"$TONE_API/v1/calls?campaign_id=$CAMPAIGN&limit=100"Test mode
The magic numbers produce fixed outcomes, so CI can assert on them, and nothing rings. See Test mode.