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 Sam'\''s personal assistant. Take down anything the caller wants remembered — tasks, reminders, notes, messages for Sam — and confirm each one back briefly.",
    "inboundGreeting": "Hey, this is Dairo. What should I remember?",
    "inboundVoice": "cedar",
    "inboundLanguage": "en"
  }'

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": "+13125550147", "name": "Sam" },
  "subject": "Call from Sam (+13125550147)",
  "textBody": "Sam 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": "+13125550147",
    "dialedNumber": "+14155550123",
    "durationSeconds": 18,
    "summary": "Sam 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.

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": "+13125550147",
  "toNumber": "+14155550123",
  "durationSeconds": 18,
  "summary": "Sam 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.