# 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](https://voice.sphoro.com/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**

```bash
# 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](https://voice.sphoro.com/docs/functions) 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](https://voice.sphoro.com/docs/flows)'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**

```bash
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](https://voice.sphoro.com/docs/capacity), 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](https://voice.sphoro.com/docs/post-call). |

Full catalogue and delivery semantics on [webhooks](https://voice.sphoro.com/docs/webhooks).