Making calls

Give Dairo a destination, a caller id you own, and instructions, and an AI agent makes the call. This page walks the whole lifecycle: place, poll, read, hang up.

Operation	Method & path	Scope
Place a call	`POST /v1/phone/calls`	`phone:call`
List calls	`GET /v1/phone/calls`	`phone:read`
Get one call	`GET /v1/phone/calls/{id}`	`phone:read`
Transcript	`GET /v1/phone/calls/{id}/transcript`	`phone:read`
Recording	`GET /v1/phone/calls/{id}/recording`	`phone:read`
Hang up	`POST /v1/phone/calls/{id}/hangup`	`phone:call`

Place a call

Pass to, from, and instructions — everything else is optional. from must be a number your account owns with status active; buy one on Phone numbers.

curl -X POST https://api.dairo.app/v1/phone/calls \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: api-recovered-2026-07-09" \
  -d '{
    "to": "+4915112345678",
    "from": "+13125550100",
    "instructions": "Tell {{customerName}} the API recovered at 14:02 and all alarms are green. Answer questions about the outage window if asked. Keep it under twenty seconds.",
    "greeting": "Hallo {{customerName}}, hier ist der Dairo-Agent von Acme.",
    "language": "de",
    "maxDurationSeconds": 300,
    "variables": { "customerName": "Luka" },
    "metadata": { "incidentId": "inc_482" }
  }'

const call = await dairo.calls.create({
  to: "+4915112345678",
  from: "+13125550100",
  instructions:
    "Tell {{customerName}} the API recovered at 14:02 and all alarms are green. " +
    "Answer questions about the outage window if asked. Keep it under twenty seconds.",
  greeting: "Hallo {{customerName}}, hier ist der Dairo-Agent von Acme.",
  language: "de",
  maxDurationSeconds: 300,
  variables: { customerName: "Luka" },
  metadata: { incidentId: "inc_482" },
  idempotencyKey: "api-recovered-2026-07-09",
});
console.log(call.id, call.status); // … queued

call = dairo.calls.create(
    to="+4915112345678",
    from_="+13125550100",
    instructions=(
        "Tell {{customerName}} the API recovered at 14:02 and all alarms are green. "
        "Answer questions about the outage window if asked. Keep it under twenty seconds."
    ),
    greeting="Hallo {{customerName}}, hier ist der Dairo-Agent von Acme.",
    language="de",
    max_duration_seconds=300,
    variables={"customerName": "Luka"},
    metadata={"incidentId": "inc_482"},
    idempotency_key="api-recovered-2026-07-09",
)
print(call.id, call.status)  # … queued

dairo phone call +4915112345678 \
  --from +13125550100 \
  --instructions "Tell {{customerName}} the API recovered at 14:02. Keep it under twenty seconds." \
  --greeting "Hallo {{customerName}}, hier ist der Dairo-Agent von Acme." \
  --language de \
  --max-duration 300 \
  --variables '{"customerName":"Luka"}' \
  --idempotency-key api-recovered-2026-07-09 \
  --wait

Tool: make_phone_call  (scope phone:call, confirm required)
Args: { "to": "+4915112345678", "from": "+13125550100", "instructions": "Tell Luka the API recovered at 14:02. Keep it under twenty seconds.", "confirm": true }

You get back a phone_call at status: "queued" — the request returns before the phone rings, and the call proceeds on its own:

{
  "object": "phone_call",
  "id": "7c9e6679-7425-40de-963d-04cf43a4b1c3",
  "direction": "outbound",
  "status": "queued",
  "fromNumber": "+13125550100",
  "toNumber": "+4915112345678",
  "instructions": "Tell {{customerName}} the API recovered at 14:02…",
  "greeting": "Hallo {{customerName}}, hier ist der Dairo-Agent von Acme.",
  "language": "de",
  "maxDurationSeconds": 300,
  "durationSeconds": null,
  "summary": null,
  "costUsd": null,
  "error": null,
  "metadata": { "incidentId": "inc_482" },
  "idempotencyKey": "api-recovered-2026-07-09",
  "createdAt": "2026-07-09T14:03:20Z"
}

The CLI’s --wait flag polls the call for you until it reaches a terminal status, then prints the transcript — the fastest way to try your first call end to end.

Request fields

Field	Required	Description
`to`	Yes	Destination, E.164 (e.g. `+4915112345678`).
`from`	Yes	Caller id, E.164. Must be a number your account owns with status `active` — anything else is rejected with `400`.
`instructions`	Yes	What the agent should accomplish, up to 8,000 characters. This is the whole conversation brief: goal, tone, facts it may share, length.
`greeting`		The opening line, spoken when the callee answers.
`voice`		A voice id from the catalog; unset, calls use Dairo’s default conversational English voice. See Voices.
`language`		ISO language code, e.g. `de`. Calls default to English.
`backgroundAudio`		`silence` (default), `office`, or `none`. Any other value is rejected with `400`.
`maxDurationSeconds`		Hard cap on call length, 30–1800 seconds (default 600). Dairo ends the call at the cap.
`record`		Record the call audio. Default `true`; recording consent rules apply in many places.
`variables`		Values for `{{handlebars}}` placeholders in `instructions` and `greeting`.
`metadata`		Opaque key/value object, stored and echoed back on the call.
`idempotencyKey`		Also accepted as an `Idempotency-Key` header; when both are set they must match.

from is not decoration. The caller id must be a number your account owns with status active — that rule is what keeps a key with phone:call from impersonating someone else’s number. Pick a from your recipient’s carrier will display: for German recipients that means a German local or national number, and Compliance explains why.

Fill in per-call values with variables

instructions and greeting support {{placeholder}} syntax, filled from variables at call time. Keep the brief as a stable template and inject the per-call facts:

{
  "instructions": "Remind {{customerName}} that invoice {{invoiceId}} ({{amount}}) is due Friday. Offer to resend it by email.",
  "variables": { "customerName": "Frau Weber", "invoiceId": "INV-2201", "amount": "EUR 1,240" }
}

Retry safely

Pass an Idempotency-Key header (or idempotencyKey in the body). A retried request with the same key returns the original call and never dials twice — with phones, a duplicate isn’t a wasted API call, it’s a human being rung a second time. Use a key derived from the reason for the call, such as an incident id or an invoice id; Retries & idempotency has the general contract.

Poll the call

Fetch the call until it reaches a terminal status: completed, failed, no_answer, busy, or canceled.

curl https://api.dairo.app/v1/phone/calls/7c9e6679-7425-40de-963d-04cf43a4b1c3 \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const call = await dairo.calls.get("7c9e6679-7425-40de-963d-04cf43a4b1c3");
console.log(call.status, call.durationSeconds, call.costUsd);

call = dairo.calls.get("7c9e6679-7425-40de-963d-04cf43a4b1c3")
print(call.status, call.duration_seconds, call.cost_usd)

dairo phone calls get 7c9e6679-7425-40de-963d-04cf43a4b1c3

Tool: list_phone_calls  (scope phone:read)
Args: { "action": "get", "callId": "7c9e6679-7425-40de-963d-04cf43a4b1c3" }

A finished call carries everything you need to reason about what happened — how long it ran, what it cost, and a one-paragraph summary of the conversation:

{
  "object": "phone_call",
  "id": "7c9e6679-7425-40de-963d-04cf43a4b1c3",
  "status": "completed",
  "fromNumber": "+13125550100",
  "toNumber": "+4915112345678",
  "durationSeconds": 42,
  "summary": "Reached Luka, relayed that the API recovered at 14:02 with all alarms green. He acknowledged and had no questions.",
  "costUsd": 0.14,
  "createdAt": "2026-07-09T14:03:20Z"
}

Dairo writes the summary from the transcript, in the language the conversation was held in. On a call that just ended, summary can be null for a moment — poll once more and it fills in. List recent calls with GET /v1/phone/calls, filtered by status or to; limit is 1–100 and defaults to 50:

cURL

curl "https://api.dairo.app/v1/phone/calls?status=completed&limit=20" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Read the transcript

Every conversation produces a turn-by-turn transcript. Roles are agent (your AI), caller (the human who answered), and tool. A call that hasn’t produced any conversation yet returns empty turns.

curl https://api.dairo.app/v1/phone/calls/7c9e6679-7425-40de-963d-04cf43a4b1c3/transcript \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const transcript = await dairo.calls.transcript("7c9e6679-7425-40de-963d-04cf43a4b1c3");
for (const turn of transcript.turns) console.log(turn.role, turn.content);

transcript = dairo.calls.transcript("7c9e6679-7425-40de-963d-04cf43a4b1c3")
for turn in transcript.turns:
    print(turn.role, turn.content)

dairo phone calls transcript 7c9e6679-7425-40de-963d-04cf43a4b1c3

Tool: list_phone_calls  (scope phone:read)
Args: { "action": "transcript", "callId": "7c9e6679-7425-40de-963d-04cf43a4b1c3" }

{
  "object": "phone_call.transcript",
  "callId": "7c9e6679-7425-40de-963d-04cf43a4b1c3",
  "turns": [
    { "role": "agent", "content": "Hallo Luka, hier ist der Dairo-Agent von Acme.", "timestamp": "2026-07-09T14:03:41Z" },
    { "role": "caller", "content": "Ja, hallo?", "timestamp": "2026-07-09T14:03:44Z" },
    { "role": "agent", "content": "Kurze gute Nachricht: die API läuft seit 14:02 wieder, alle Alarme sind grün.", "timestamp": "2026-07-09T14:03:47Z" }
  ]
}

Fetch the recording

When a call has a recording, GET /v1/phone/calls/{id}/recording resolves it to a storage object you can download or share:

{
  "object": "phone_call.recording",
  "callId": "7c9e6679-7425-40de-963d-04cf43a4b1c3",
  "objectId": "obj_9f2c4a7d"
}

A call with no recording returns 404 — because it was placed with record: false, never connected, or the audio isn’t available yet.

Hang up

End a live call early. Hanging up works at any point before a terminal status — a queued call is canceled before it ever dials, and a call that is already talking stops immediately.

curl -X POST https://api.dairo.app/v1/phone/calls/7c9e6679-7425-40de-963d-04cf43a4b1c3/hangup \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const call = await dairo.calls.hangup("7c9e6679-7425-40de-963d-04cf43a4b1c3");
console.log(call.status); // canceled

call = dairo.calls.hangup("7c9e6679-7425-40de-963d-04cf43a4b1c3")
print(call.status)  # canceled

dairo phone calls hangup 7c9e6679-7425-40de-963d-04cf43a4b1c3

Tool: manage_phone_calls  (scope phone:call, confirm required)
Args: { "action": "hangup", "callId": "7c9e6679-7425-40de-963d-04cf43a4b1c3", "confirm": true }

The call settles as canceled. If it had connected, the time already spoken is still billed and transcribed. Hanging up a call that already reached a terminal status returns 409.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Place a call

Request fields

Fill in per-call values with variables

Retry safely

Poll the call

Read the transcript

Fetch the recording

Hang up

​Place a call

​Request fields

​Fill in per-call values with variables

​Retry safely

​Poll the call

​Read the transcript

​Fetch the recording

​Hang up

Place a call

Request fields

Fill in per-call values with variables

Retry safely

Poll the call

Read the transcript

Fetch the recording

Hang up