> ## 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.
# Inbound calls
> Let your Dairo number answer the phone: an AI agent picks up, takes notes, and drops every call into your inbox.
Anyone who calls one of your Dairo numbers is answered by that number's inbound agent. It holds the conversation, writes down what the caller wants remembered, and delivers the whole call — summary, notes, and transcript — to your inbox as a message your agents already know how to read.
Out of the box, every number answers with a friendly assistant that takes messages and notes. Tell it who it is and what the line is for, and it becomes your receptionist, your support line, or a voice notepad you can call from anywhere.
## Set up the inbound agent
Configure the agent on the number with `PATCH /v1/phone/numbers/{id}` (scope `phone:write`). Bind an `inboxId` too — that is where answered calls land.
```bash title="cURL" theme={null}
curl -X PATCH https://api.dairo.app/v1/phone/numbers/b4e7d9f0-2a1b-4c8e-9f3a-7d0a1f2c5b6e \
-H "Authorization: Bearer $DAIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"inboundInstructions": "You are Luka'\''s personal assistant. Take down anything the caller wants remembered — tasks, reminders, notes, messages for Luka — and confirm each one back briefly.",
"inboundGreeting": "Hey, this is Dairo. What should I remember?",
"inboundVoice": "cedar",
"inboundLanguage": "en"
}'
```
```ts title="TypeScript" theme={null}
const number = await dairo.phoneNumbers.update("b4e7d9f0-2a1b-4c8e-9f3a-7d0a1f2c5b6e", {
inboxId: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
inboundInstructions:
"You are Luka's personal assistant. Take down anything the caller wants remembered — " +
"tasks, reminders, notes, messages for Luka — and confirm each one back briefly.",
inboundGreeting: "Hey, this is Dairo. What should I remember?",
inboundVoice: "cedar",
inboundLanguage: "en",
});
```
```python title="Python" theme={null}
number = dairo.phone_numbers.update(
"b4e7d9f0-2a1b-4c8e-9f3a-7d0a1f2c5b6e",
inbox_id="7c9e6679-7425-40de-944b-e07fc1f90ae7",
inbound_instructions=(
"You are Luka's personal assistant. Take down anything the caller wants remembered — "
"tasks, reminders, notes, messages for Luka — and confirm each one back briefly."
),
inbound_greeting="Hey, this is Dairo. What should I remember?",
inbound_voice="cedar",
inbound_language="en",
)
```
```text title="MCP" theme={null}
Tool: manage_phone_numbers (scope phone:write)
Args: { "action": "update", "phoneNumberId": "b4e7d9f0-2a1b-4c8e-9f3a-7d0a1f2c5b6e", "inboxId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "inboundInstructions": "You are Luka's personal assistant…", "inboundVoice": "cedar" }
```
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inboundInstructions` | Who the agent is and what the line is for, up to 8,000 characters. `null` restores the default assistant that takes messages and notes. |
| `inboundGreeting` | The first thing the agent says, up to 500 characters. `null` uses a short default greeting — by first name when the caller is one of your [contacts](/contacts/contacts). |
| `inboundVoice` | One of the Dairo Live [voice ids](/phone/voices), e.g. `marin` or `cedar`. Any other value is rejected with `400`. |
| `inboundLanguage` | ISO code of the language the agent speaks, e.g. `de`. |
Every field is optional and independent; pass `null` to reset one to its default. The number object returns all four, so `GET /v1/phone/numbers/{id}` always shows how the line is set up.
## What lands in your inbox
When the caller hangs up — or says goodbye and the agent hangs up — Dairo writes a summary, pulls out the caller's structured notes, and delivers the call to the number's bound inbox as a message with `channel: "voice"`. It fires the normal `message.received` [webhook](/webhooks/webhooks), so an agent picks it up with `read_mailbox` or its event loop, exactly like an email or a Telegram message.
Say you call your number and tell it: *"Hey Dairo, remember I need to call the bank tomorrow."* This message arrives in your inbox:
```json theme={null}
{
"object": "message",
"channel": "voice",
"direction": "inbound",
"from": { "address": "+4915112345678", "name": "Luka" },
"subject": "Call from Luka (+4915112345678)",
"textBody": "Luka asked to be reminded to call the bank tomorrow.\n\nNotes:\n- [task] Call the bank (due: tomorrow)\n\nTranscript:\n…",
"channelMetadata": {
"callId": "0e5b7c21-9a4d-4f3e-8b61-2d7c9f1a4e08",
"callerNumber": "+4915112345678",
"dialedNumber": "+14155550123",
"durationSeconds": 18,
"summary": "Luka asked to be reminded to call the bank tomorrow.",
"notes": [
{ "kind": "task", "text": "Call the bank", "due": "tomorrow" }
]
}
}
```
`channelMetadata.notes` is the part your agent acts on. Each note has a `kind` — `task`, `note`, `reminder`, or `message` — the `text`, and a `due` as the caller said it (`"tomorrow"`, `"Friday 3pm"`), or `null` when there is none. The readable `textBody` repeats the summary, the notes, and the full transcript for a human skimming the inbox.
Pair an inbound number with an agent that watches its inbox and you have a voice notepad: call, say what's on your mind, hang up, and the task is already in your agent's queue.
## The call itself
An inbound call is a regular `phone_call` with `direction: "inbound"` — list it with `GET /v1/phone/calls`, fetch its transcript and recording, and follow it with the `call.status_changed` webhook, all as on [Making calls](/phone/making-calls). Its `notes` field carries the same notes as the inbox message:
```json theme={null}
{
"object": "phone_call",
"id": "0e5b7c21-9a4d-4f3e-8b61-2d7c9f1a4e08",
"direction": "inbound",
"status": "completed",
"fromNumber": "+4915112345678",
"toNumber": "+14155550123",
"durationSeconds": 18,
"summary": "Luka asked to be reminded to call the bank tomorrow.",
"notes": [
{ "kind": "task", "text": "Call the bank", "due": "tomorrow" }
],
"costUsd": 0.102,
"createdAt": "2026-07-10T08:12:04Z"
}
```
An answered inbound call is billed like an outbound one: the Dairo Live rate of \$0.09 per started minute plus the telephony rate of your number's country — for a US number, 9¢ + 1.2¢ = 10.2¢ per minute. A call that never connects costs nothing.