Inbound calls

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.

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"
  }'

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",
});

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",
)

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.
`inboundVoice`	One of the Dairo Live voice ids, 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, 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:

{
  "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. Its notes field carries the same notes as the inbox message:

{
  "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.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Set up the inbound agent

What lands in your inbox

The call itself

​Set up the inbound agent

​What lands in your inbox

​The call itself

Set up the inbound agent

What lands in your inbox

The call itself