Receiving calls
A number your workspace holds can answer an incoming call in one of three ways: deliver it to one of your SIP trunks, forward it to a number you have verified, or reject it. The answer is a setting on the number, and a number has exactly one answer at a time.
Every number starts on reject, so a number nobody has configured turns callers away rather than having no answer at all.
Prerequisites
Before you point a number at an answer:
- A number that can receive calls. Open Voice > Numbers and check the Directions column for an inbound mark. A number you registered as a caller ID from another carrier does not receive calls here: that carrier routes the calls made to it, so it carries no answer.
- For delivery to a trunk: a SIP trunk with inbound calling on and at least one delivery gateway.
- For a forward: a verified caller ID to forward to.
- To change the setting over the API or CLI: an API key holding the voice_management scope at write level. That scope covers voice configuration; the voice scope covers call traffic and statistics, so reading the call log needs the other one.
Deliver calls to a SIP trunk
Delivery dials your own phone system at addresses you declare on the trunk. Turn the direction on first, because a number can only be pointed at a trunk that already accepts inbound calls.
- Open Voice > SIP Trunks, open the trunk, and under Inbound calling select Enable inbound.
- Add at least one gateway under the same section. A trunk with no gateway refuses every incoming call to the numbers it answers.
- Open Voice > Numbers, open the number, and under Inbound routing choose Deliver to a SIP trunk.
- Pick the trunk and select Save. Only trunks with inbound calling on appear in the list.
The Used for column on the Numbers list then shows the number as delivered to that trunk, and the trunk's own page lists the numbers it answers.
What a gateway needs
A gateway is one address a call is delivered to, and how that peer wants the call's two numbers spelled:
| Setting | What it is |
|---|---|
| SIP URI | The host of your phone system, with an optional port, as in sip:pbx.example.com:5060. Give the host only: a URI carrying a user part is refused |
| Priority | The order gateways are tried in, lowest first |
| Destination format | How the dialed number is spelled to this peer. Defaults to E.164 |
| Origination format | How the calling number is spelled to this peer, in the delivered call's P-Asserted-Identity header. Defaults to E.164 |
Gateways sharing a priority take an equal share of calls, and any of them may be tried first on a given call. To fail delivery over to a second address, give that gateway a larger priority number: it is tried when the first does not answer.
Both number formats are templates over one placeholder, {number}, which stands for the number without its leading +. The destination format is placed before the SIP URI host, so 1234#{number} delivers a call to +31201234567 as sip:1234#31201234567@pbx.example.com:5060. The default for both is +{number}, which is E.164. A format containing no {number} at all sends every number the trunk answers to one fixed address.
Warning: turning inbound calling off on a trunk, or deleting the trunk, puts every number pointing at it back on reject. Turning inbound back on does not restore them, so each number has to be pointed at a trunk again.
Forward calls to another number
A forward answers the incoming call and places a second call to a number you have verified, then connects the two.
- Open Voice > Numbers, open the number, and under Inbound routing choose Forward to another number.
- Pick the number to forward to. The list holds your verified caller IDs, because a forward may only target a number you have proven you control.
- Choose which number the forwarded call shows as the caller, then select Save.
The forward target is checked when you set it and again on every call it forwards. A caller ID you later remove stops forwarding rather than carrying on, and the incoming calls are rejected from that point.
The forwarded call rings for 45 seconds before it is given up on, which is longer than a trunk delivery rings because the far end is usually a person's phone rather than a phone system.
Forwarding places a call, so the outbound rules apply to the second leg: forwarding to a country you have not turned on under Destinations is refused with destination_not_enabled.
One forward, two call records
A forwarded call produces two records that share a session_id:
| Record | What it is |
|---|---|
| The arriving call | direction is inbound, and route says the number was set to forward, to which number, and which number the forwarded leg presented |
| The forwarded call | direction is outbound, from the number the leg presented to the number you forward to. It carries no route of its own |
Group them by session_id to see the whole call. The arriving record is the one that says what the number was configured to do.
Choose which number a forwarded call shows as the caller
A forwarded call has two numbers it could present to whoever answers, and the choice changes both what they see and how likely a carrier is to interfere with the call:
- Calling number is the caller's own number, so the phone rings as though they had dialed it directly and the call can be returned from the call log. Because the number is not one you own, some carriers, most often in the US and parts of Europe, mark such calls as unverified, replace the number, or screen them.
- Dialed number is the number the caller dialed, which is one of yours. Whoever answers sees which of your numbers was called rather than who called it.
There is no default. State the choice on every forward you write over the API or CLI.
Which values your workspace may set is stated on the number itself, in forward_as_options on its inbound_configuration. Presenting the dialed number needs your workspace approved to place calls from numbers you bought from us, and that approval is not available yet, so forward_as_options offers the calling number alone and a forward presents the caller's own number. Setting the dialed number is refused until then.
On a read, forward_as is the value the calls actually carry, which can differ from the value last written.
Read what a number did with a call
An incoming call's record carries a route alongside its status, and route is what the number was set to do at the moment the call was handled. Changing the number's setting afterwards does not change what its past calls say.
| route.type | What the number did |
|---|---|
| trunk | The call was delivered to the SIP trunk named in trunk_id |
| forward | The call was forwarded to the number in forward_to, presenting the number in forward_as |
| reject | The number turned the call away |
route says what the number was set to do, not that it worked. A trunk route on a call that never connected is a number pointed at a trunk that did not take the call, and the call's status is what carries the outcome. route is absent on outbound calls and on calls recorded before the field existed.
In the dashboard, open the call from Voice > Calls and read the Inbound route row, which links to the number whose settings decided it. Over the API, route is on GET /v1/voice/calls/{call_id} and GET /v1/voice/calls, and direction filters the list to incoming calls.
Diagnose a refused incoming call
An incoming call that was refused is recorded with the status rejected. Two different things produce it, and rejection_reason is what separates them:
- Rejected with no rejection_reason. The number itself turned the call away. The call failed no check of ours, so it names no reason, and route says what the number was set to do. A reject route is a number nobody has pointed anywhere, or one deliberately set to refuse.
- Rejected with a rejection_reason. The call failed one of our checks before reaching your phone system. The reason names the check. Rejected calls lists every reason and its fix.
failed is a different status and does not mean refused: it means the call was attempted and did not work, with sip_response_code carrying the response that came back.
Read route and rejection_reason together to tell the refusals apart:
| route and reason | Cause |
|---|---|
| reject, no reason | The number is not pointed at an answer. Deleting a trunk, or turning its inbound calling off, puts every number pointing at it back here, so a number that used to work can land on it |
| trunk, no_route_found | The number is pointed at a trunk, and that trunk has no gateway to deliver the call to. Add one on the trunk page |
| forward, no reason | The forward target is no longer a verified caller ID. Re-verify it under Caller IDs, or forward to another number |
| forward, destination_not_enabled | The second leg could not be placed to the forward target's country. Turn that country on under Destinations |
The account ceilings apply to incoming calls as well: past your wallet balance, your organization's daily voice spend limit, or your concurrency and per-second ceilings, an incoming call is rejected with the matching reason. Voice overview covers the ceilings themselves.
Check what a received call costs
Receiving a call is charged. The rate depends on the country and type of the number receiving it, and is published per country under Receiving calls on the voice pricing page, alongside the rates for calls you place.
A forward is billed as two calls: the arriving call at the receiving rate, and the leg we place at the outbound rate for the number you forward to. A single handling fee is charged once for the call rather than once per leg.
The wallet is checked before an incoming call is delivered, so a balance that cannot cover it means the call is rejected rather than billed to you afterwards. Cost and billing covers how billable time, rates, and the wallet work for both directions.
Next steps
| Page | What it covers |
|---|---|
| SIP trunks | Creating a trunk, its two directions, and controlling who may send |
| Caller IDs | Registering a number and proving you control it |
| Call log | Every field on a call record, and every rejection reason |
| Voice events | Getting call outcomes pushed to your own systems |
| Voice troubleshooting | Diagnosing a call that does not go through, from its symptom |