Inbound calls
What happens when somebody rings a number you own.
Inbound needs no API call. Bind an agent to a number and it answers:
curl "$TONE_API/v1/numbers/$NUMBER" -X PATCH \
-H "Authorization: Bearer $TONE_KEY" -H 'content-type: application/json' \
-d "{\"agentId\":\"$AGENT\"}"The call appears in your call log with direction: "inbound" and
initiator: "inbound", and fires the same webhooks as any other call.
Four things that differ from outbound
A draft agent will not answer. Outbound will happily dial with a draft; inbound refuses. Publish before you expect your line to work.
Inbound always uses the live version, even while a campaign elsewhere is running on an older one.
The pre-dial gate does not run. Calling windows and Do-Not-Call protect a
recipient from a call they did not ask for. Answering is not placing, and
refusing to answer your own published line at 21:01 would be absurd. No
compliance_checks rows are written for inbound calls.
The opening line and voicemail handling are stripped. An opening line reads "calling from X about Y" and would greet someone who rang you; voicemail detection is a callee-side judgement that would hang up on a real person.
When a call is refused
Some inbound calls are refused before they become calls. A refusal writes no call record at all — the call never happened, so inventing a row for it would be a lie in your CDR.
| Reason | Fix |
|---|---|
| The number has no agent bound | Bind one |
| The bound agent is a draft | Publish it |
The number is suspended | Top up; it reactivates on its own |
| Insufficient balance | Top up |
| At your concurrency quota | See below |
⚠️ Inbound and outbound currently share one concurrency pool. A campaign
running at your quota can lock out your published line. Keep campaign
maxConcurrent below your quota if the same organization takes inbound calls
that matter.
Environment comes from the number
An inbound call presents no credential of yours, so there is no key to read an environment from. It is taken from the number instead: a number allocated in test mode produces test calls.