Receiving calls

Point a number at an agent and it answers. Everything else on this page is about the choices around that: whether to ring first, who the caller is, and what to do with the ones you do not want to talk to.

Pointing a number at an agent

Done in the portal, under phone numbers: choose the number, choose the agent, choose the direction. Nothing else is required — the next call to that number is answered by that agent.

Test it before you publish the number. Call it from your own phone. An agent that works perfectly on a browser call can still be pointed at the wrong number, and the way you find out is a customer.

Ringing before answering

By default an inbound call is answered as soon as it arrives and the agent starts speaking. Some lines should ring first: it sets the caller's expectation that a telephone is being picked up, and it is what makes declining a call possible at all.

Behaviour	Right for
Answer immediately	An automated line. The caller dialled a service and wants it to start.
Ring first	A line where a person might take the call instead, and any line that should be declinable.

A simple agent — one where a person in a browser holds the call — always rings, because there is nobody on this end until somebody arrives. The call is created with status: "ringing", an operator claims it, and a call nobody claims inside ring_seconds is recorded missed.

GET/v1/calls/ringing

POST/v1/calls/{id}/claim

POST/v1/calls/{id}/give-up

Shell

# What is ringing right now.
curl -s https://voice.sphoro.com/v1/calls/ringing \
  -H "Authorization: Bearer $SPHORO_API_KEY"

# Take it.
curl -s -X POST https://voice.sphoro.com/v1/calls/$CALL_ID/claim \
  -H "Authorization: Bearer $SPHORO_API_KEY"

Knowing who is calling

The caller's number is available to the prompt as {{from_number}}, in E.164 whatever format the carrier delivered it in. That is enough to greet a known customer by name if you look them up first — but on an inbound call you have not been given the chance to, because the call is already ringing.

Two ways to bridge that:

Approach	How
Let the agent ask, then look up	A function the model calls with the number or the reference the caller reads out.
Look up the number, then decide	Subscribe to `call.started`, which carries the direction and the numbers, and act on it from your own systems in parallel.

Caller ID is not authentication. It is trivially spoofed. Greeting somebody by name from their number is a nice touch; telling them their account balance from it is not. Anything sensitive needs the agent to verify — which is exactly the shape a flow's first node is for.

Refusing a call

Some numbers you do not want to answer at all. The suppression list is checked on outbound calls; for inbound, the tool is to decline the ringing call rather than answer and hang up — answering costs a connected leg and tells the caller they reached something.

Shell

curl -s -X POST https://voice.sphoro.com/v1/calls/$CALL_ID/give-up \
  -H "Authorization: Bearer $SPHORO_API_KEY"

Handling more than one call at once

Every inbound call takes a concurrency slot. Past your ceiling, a caller is held on a hold line and admitted when a slot frees; past the queue too, they hear a busy line. See concurrency, which is worth reading before a campaign drives return calls into an inbound line.

The events an inbound call produces

Event	When
`call.ringing`	The call arrived and is ringing, on a line that rings.
`call.claimed`	An operator took it.
`call.missed`	It rang out with nobody taking it.
`call.started`	Connected and talking. Carries `direction: "inbound"`.
`call.ended`, `call.analysed`	As for any call — see post-call analysis.

Full catalogue and delivery semantics on webhooks.