Phone calls

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:

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

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:

POST /v1/phone/calls { to, from, instructions }   ->  201 { "id": "…", "status": "queued" }
GET  /v1/phone/calls/{id}                         ->  { "status": "completed", "durationSeconds": 42, "costUsd": 0.1362 }
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. Every call runs on Dairo Live (model: "dairo-live"), and the agent hangs up by itself once the person says goodbye.

It works the other way round too: anyone who calls one of your Dairo numbers is answered by that number's inbound agent, and the call — summary, the caller's notes, and transcript — lands in your inbox as a message.

A call moves through these statuses:

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

A call costs the Dairo Live rate of $0.09 per minute plus the telephony rate of the destination, billed per started minute — a 61-second call bills as two minutes. A call to a German mobile, for example, is 9¢ + 4.62¢ = 13.62¢ per minute. 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 that never connects — nobody answers, the line is busy — costs nothing.

maxDurationSeconds (default 600, 30–780) 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 or a chat channel like Telegram when you need a record, an attachment, or the recipient should respond on their own schedule.

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