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.

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. 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 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.

Caller ID

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

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

POST/v1/calls

Shell

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

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 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.

Where to go next

Receiving calls and placing calls are the two directions in detail. Concurrency is what happens when more calls arrive than your account can carry at once.