> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dairo.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone calls

> Give Dairo a number and plain-English instructions, and an AI agent dials, has the conversation, and reports back with a transcript.

Your agent can pick up the phone. Tell Dairo who to call and what to accomplish, and a natural-sounding AI agent dials the number, has the conversation, and hands you back a transcript, a written summary, and the exact cost.

The whole product is the `instructions` field. There is no dialog tree to build, no audio to stream, and no telephony to configure — you write what the call should achieve, the way you would brief a colleague, and the agent handles the conversation:

```bash title="cURL" theme={null}
curl -X POST https://api.dairo.app/v1/phone/calls \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+4915112345678",
    "from": "+13125550100",
    "instructions": "Call Luka. Tell him the API recovered at 14:02 and all alarms are green. Keep it under twenty seconds."
  }'
```

<Note>
  Phone uses three [scopes](/concepts/scopes): `phone:read` for numbers, calls, transcripts, and recordings; `phone:write` for buying, configuring, and releasing numbers; and `phone:call` for placing or hanging up a call. Grant all three to a key that manages numbers and runs calls. Give an agent that should only read outcomes `phone:read` alone — its key can never make anyone's phone ring.
</Note>

## A call is a job, not a live session

Placing a call is asynchronous. The `POST` returns at once with a call `id` and `status: "queued"` — the phone starts ringing after your request has already come back. From there you poll the call; there is no media session to manage and no socket to hold open:

```text theme={null}
POST /v1/phone/calls { to, from, instructions }   ->  200 { "id": "…", "status": "queued" }
GET  /v1/phone/calls/{id}                         ->  { "status": "completed", "durationSeconds": 42, "costUsd": 0.14 }
GET  /v1/phone/calls/{id}/transcript              ->  { "turns": [ { "role": "agent", … }, { "role": "caller", … } ] }
```

When the call ends, its duration, cost, and a one-paragraph summary are stamped onto the call object, and the turn-by-turn transcript is ready to fetch.

A call moves through these statuses:

| Status        | Meaning                                                              |
| ------------- | -------------------------------------------------------------------- |
| `queued`      | Accepted and waiting to be dialed — the status your request returns. |
| `initiating`  | The call is being set up.                                            |
| `ringing`     | The destination phone is ringing.                                    |
| `in_progress` | The call is live; the agent is talking.                              |
| `completed`   | The conversation finished normally. **Terminal.**                    |
| `failed`      | The call could not be completed — see `error`. **Terminal.**         |
| `no_answer`   | Nobody picked up. **Terminal.**                                      |
| `busy`        | The line was busy. **Terminal.**                                     |
| `canceled`    | You ended it with a hangup request. **Terminal.**                    |

Once a call reaches a terminal status it never changes again — `completed`, `failed`, `no_answer`, `busy`, and `canceled` are the five ways a call ends.

## What a call costs

Calls are billed per started minute — a 61-second call bills as two minutes — and the rate depends on the destination. When the call reaches a terminal status, the exact price lands on it as `costUsd`, so you read the cost from the call object with no rate table to reconcile. A call nobody answers costs nothing.

`maxDurationSeconds` (default 600, up to 1800) is your cost ceiling: Dairo ends the call when it hits the cap, so a chatty callee can never run up an open-ended bill. Owning a number also carries a monthly fee, shown as `monthlyCostUsd` when you search for numbers.

## When to pick up the phone

A call is interruptive — it demands attention right now. That is its strength and the reason to use it sparingly:

* **Call** when immediacy matters and you need a human acknowledgment: an on-call escalation, a delivery about to fail, a time-critical confirmation, reaching someone who doesn't watch a screen.
* **[Email](/sending/sending-email)** when you need a record, an attachment, or the recipient should respond on their own schedule.
* **SMS** when a one-line nudge is enough — a phone number bound to a [unified inbox](/receiving/inboxes) sends and receives texts next to your mail.

You are putting an AI on a live line with real people, and that comes with duties: disclosure, consent, recording rules, caller-id rules. The Compliance page covers them — read it before your first production call.

## Next steps

<CardGroup cols={2}>
  <Card title="Making calls" icon="phone-volume" href="/phone/making-calls">
    Place a call, poll it, read the transcript and summary, hang up early.
  </Card>

  <Card title="Phone numbers" icon="hashtag" href="/phone/phone-numbers">
    Search, buy, and configure the numbers your calls come from.
  </Card>

  <Card title="Voices" icon="microphone-lines" href="/phone/voices">
    Choose the voice and language your calls speak.
  </Card>

  <Card title="Compliance" icon="scale-balanced" href="/phone/compliance">
    AI disclosure, consent, recording, and caller-id rules.
  </Card>
</CardGroup>