# 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**](https://bird.com/dashboard/w/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](/docs/guides/voice/sip-trunks) with inbound calling on and at least one delivery gateway.
- **For a forward:** a [verified caller ID](/docs/guides/voice/caller-ids) 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.

1. Open **Voice** > [**SIP Trunks**](https://bird.com/dashboard/w/voice/sip-trunks), open the trunk, and under **Inbound calling** select **Enable inbound**.
2. Add at least one gateway under the same section. A trunk with no gateway refuses every incoming call to the numbers it answers.
3. Open **Voice** > [**Numbers**](https://bird.com/dashboard/w/voice/numbers), open the number, and under **Inbound routing** choose **Deliver to a SIP trunk**.
4. 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.

1. Open **Voice** > [**Numbers**](https://bird.com/dashboard/w/voice/numbers), open the number, and under **Inbound routing** choose **Forward to another number**.
2. 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.
3. 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](/docs/guides/voice/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**](https://bird.com/dashboard/w/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}`](/docs/api/reference/get-voice-call) and [`GET /v1/voice/calls`](/docs/api/reference/list-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](/docs/guides/voice/call-log#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](/docs/guides/voice/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](/docs/guides/voice/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](/docs/guides/voice/overview#limits) 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](/pricing/voice), 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](/docs/guides/voice/placing-calls#cost-and-billing) covers how billable time, rates, and the wallet work for both directions.

## Next steps

| Page                                                        | What it covers                                                     |
| ----------------------------------------------------------- | ------------------------------------------------------------------ |
| [SIP trunks](/docs/guides/voice/sip-trunks)                 | Creating a trunk, its two directions, and controlling who may send |
| [Caller IDs](/docs/guides/voice/caller-ids)                 | Registering a number and proving you control it                    |
| [Call log](/docs/guides/voice/call-log)                     | Every field on a call record, and every rejection reason           |
| [Voice events](/docs/guides/voice/events)                   | Getting call outcomes pushed to your own systems                   |
| [Voice troubleshooting](/docs/guides/voice/troubleshooting) | Diagnosing a call that does not go through, from its symptom       |