# Numbers and carriers

A carrier is who actually places and receives the call. Sphoro Voice speaks six of them, and which one you are on decides three things: whether you can dial out, whether a live call can be handed to a person, and what a caller's number looks like when it arrives.

## The carriers

| Carrier | Answers inbound | Places outbound | Transfers a live call |
| --- | --- | --- | --- |
| **Twilio** | Yes | Yes | Yes |
| **Plivo** | Yes | Yes | Yes |
| **Vobiz** | Yes | Yes | Yes |
| **Vonage** | Yes | — | — |
| **Telnyx** | Yes | — | — |
| **SignalWire** | Yes | — | — |

All media is 8 kHz μ-law over the carrier's own media stream, in both directions, on every one of them. Machine detection runs asynchronously on the three that dial — see [conversation behaviour](https://voice.sphoro.com/docs/behaviours).

> **Browser calls need no carrier and no number at all.** If you are building a web or in-app calling experience, none of this page applies — go to [talk from a browser](https://voice.sphoro.com/docs/browser). It is also the fastest way to test an agent before a number is provisioned.

## Getting a number

Numbers are provisioned onto your account and then pointed at an agent. Two routes:

| Route | What it means |
| --- | --- |
| **Bring your own carrier account** | You already have Twilio, Plivo or Vobiz. Your credentials are added to your account in the portal, and your existing numbers become usable here. You keep the carrier relationship and the carrier bill. |
| **Numbers from Sphoro Voice** | We provision the number and the carrier behind it. Nothing for you to configure. |

Either way, the mapping from a number to the agent that answers it is managed in [the portal](https://voice.sphoro.com/portal) under phone numbers, and a number carries the agent, the direction it is for, and its carrier.

> **Point the number at the agent, not the other way round.** An agent can answer several numbers; a number answers with exactly one agent. That is what makes "the same script on three lines" work — see [personas](https://voice.sphoro.com/docs/personas).

## Caller ID

Outbound calls need a number to be *from*. It comes from one of three places, most specific first:

1. `from` on `POST /v1/calls` — this call only.
2. The caller IDs configured on the agent.
3. `TWILIO_FROM_NUMBER` — or its Plivo and Vobiz equivalents — on the deployment.

`POST /v1/calls`

**Shell**

```bash
curl -s -X POST https://voice.sphoro.com/v1/calls \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "to": "+919876543210",
    "from": "+912261234567"
  }'
```

A `from` the carrier will not let you present is refused by the carrier, not by us, so the call fails with `carrier_failure` rather than a validation error. Verify the number with your carrier first.

## Numbers are always E.164 to us

Everything this API takes and returns is E.164: a plus, a country code, then the number, with no spaces, brackets or leading zeroes.

```
+919876543210     correct
+91 98765 43210   refused — no spaces
09876543210       refused — national format, no country code
9876543210        refused — no country code
```

> **Carriers do not always send E.164.** Several deliver an inbound caller's number in national format — a bare Indian mobile arrives as `09876543210`. Sphoro Voice normalises what arrives to E.164 before the call record is written, so `{{from_number}}` and the call record are consistent whatever the carrier did. What this means for you: an inbound number you match against your own database will be in E.164, even if your carrier's own dashboard shows it differently.

## Choosing the carrier for an agent

`PATCH /v1/agents/{id}`

**Shell**

```bash
curl -s -X PATCH https://voice.sphoro.com/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"carrier": "vobiz"}'
```

Unset uses the deployment's default. Setting it matters when your account has more than one carrier configured — a different route for domestic and international, say, or a fallback you keep credentials for.

## What is not supported yet

Stated plainly, because both are commonly asked for and finding out late is expensive:

| Not available | What to do instead |
| --- | --- |
| **Bring-your-own SIP trunk (BYOT).** Connecting a SIP trunk directly, without one of the carriers above in front of it. | Terminate the trunk on Twilio, Plivo or Vobiz and connect that account. [Talk to us](https://voice.sphoro.com/docs/support) if the trunk is the requirement. |
| **Warm transfer.** Introducing the caller to the person taking over, with all three on the line. | A cold transfer, which hands the call over directly — see [transfers and endings](https://voice.sphoro.com/docs/transfers). |

## Where to go next

[Receiving calls](https://voice.sphoro.com/docs/inbound) and [placing calls](https://voice.sphoro.com/docs/outbound) are the two directions in detail. [Concurrency](https://voice.sphoro.com/docs/capacity) is what happens when more calls arrive than your account can carry at once.