# Phone calls

Have Nur call someone and hold the conversation you describe: a reminder, a confirmation, a follow-up. Read back how it went and what was said.

What you get:

- Nur dials a number and has the conversation your instructions describe, in
  the person's language. They can talk over it and ask it anything.
- An exact first sentence when it matters, such as one that names the person.
- Nur hangs up by itself when the conversation is over or the person asks.
- The call's status, length and transcript once it ends.

## Run it

On EESI's shared line, Nur calls only numbers confirmed with a code, so an API
key can make Nur call its owner and never a stranger. Confirm your own number
first, then place the call:

```bash
pip install "eesi-sdk @ git+https://github.com/eesi-ai/eesi-sdk-python"
export EESI_API_KEY=sk-eesi-...
python call.py
```

```python call.py
import asyncio

from eesi import NurClient

NUMBER = "+14155550123"  # yours, in E.164


async def main():
    nur = NurClient()
    await nur.verify_phone_number(NUMBER)  # Nur texts it a six-digit code
    await nur.confirm_phone_number(NUMBER, input("Code: "))
    call = await nur.call(
        NUMBER,
        instructions="You are Nur, calling Sam for Example Deliveries to confirm tomorrow's delivery between 10 and 12. If that doesn't suit, offer 2 to 4 or 4 to 6.",
        greeting="Hi Sam, it's Nur from Example Deliveries.",
    )
    ended = await nur.wait_for_call(call.id)
    print(ended.status)
    for role, text in ended.transcript:
        print(f"{role}: {text}")


asyncio.run(main())
```

A number stays confirmed, so later calls skip the first two steps.
`verify_phone_number(NUMBER, channel="call")` has the code read out on a call
instead of texted.

## Over HTTP

```bash
curl https://api.eesi.ai/v1/phone/calls \
  -H "Authorization: Bearer $EESI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "instructions": "You are Nur, calling Sam for Example Deliveries to confirm tomorrow'\''s delivery between 10 and 12.",
    "greeting": "Hi Sam, it'\''s Nur from Example Deliveries.",
    "metadata": {"order": "A-1042"}
  }'
```

The response is the call, with its `id`. `GET /v1/phone/calls/{id}` reads it
back: `status` is `dialing`, then `in_progress`, then `completed` (or
`not_answered`), and a finished call carries its `duration_seconds` and
`transcript`. `POST /v1/phone/numbers` sends a code and
`POST /v1/phone/numbers/confirm` enters it.

| Field | What it does |
| --- | --- |
| `to` | The number to call, in E.164. |
| `instructions` | What the call is for and everything Nur should know. Up to 16,000 characters. |
| `greeting` | The exact first sentence. Without it, Nur opens the call in its own words. |
| `voice` | A voice id from [Voices](/speech/voices). Nur's own voice when left out. |
| `metadata` | Your own tags, returned with the call. Up to 16. |

## Good to know

- Keys the person presses on their phone reach Nur as a message from them.
- When your organization records calls, each call opens with "This call is
  being recorded.", which nobody can talk over.
- On the shared line, an organization places up to 30 calls an hour and sends
  up to five codes a day. To call your customers from your own number, write to
  founders@eesi.ai.

## Next

<CardGroup cols={2}>
  <Card title="Coding companion" icon="phone" href="/realtime/coding-companion">
    Nur calls you when your coding agent finishes, and takes your next request.
  </Card>
  <Card title="Contact centers" icon="headset" href="/quickstarts/contact-centers">
    Connect your own phone system to Nur.
  </Card>
</CardGroup>