# AI outbound calls: make your first call

> Place an AI outbound call with one API request. Learn how AI voice calling works: statuses, webhooks, voicemail, consent, and a reminder call template.

- URL: https://hail.so/blog/ai-outbound-calls
- Type: Tutorial
- Tags: voice-agent, outbound
- Published: 2026-10-26
- Reading time: 5 min

An AI outbound call is a phone call that your software starts and an AI agent runs. You send one API request with the number, the instructions, and a consent flag. The agent dials, talks, and reports the result back to your code.

This tutorial places an AI outbound call with Hail, reads the result, and covers the rules that keep outbound calling safe. For the parts of an agent and the build options, read the [AI phone agent guide](https://hail.so/blog/ai-phone-agent).

## How AI voice calling works

AI voice calling joins a phone line to a conversation loop. Speech to text turns the person's words into text. A large language model (LLM) decides the reply. Text to speech says it on the call.

With Hail, one request does all of this:

1. Your code sends `POST /v1/calls`.
2. Hail returns `201` with a call `id`. The call is queued, not finished.
3. Hail dials. It ends the call when it detects voicemail. It can press keys to get through phone menus. If a person answers, the agent speaks.
4. Hail sends webhooks as the call changes state, and saves the final status.

## Place an AI outbound call

You need an API key in `HAIL_API_KEY` and credits in your workspace. The numbers below are placeholders in E.164 format.

```bash
curl --fail-with-body --silent --show-error \
  https://api.hail.so/v1/calls \
  -H "Authorization: Bearer $HAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: reminder-appt-1042' \
  --data '{
    "to": "+14155550101",
    "recipient_consent": true,
    "consent_source": "Appointment booking form, reminder calls opted in",
    "message_type": "informational",
    "system_prompt": "You call to confirm a dental cleaning on Tuesday at 3 PM. Ask if the time still works. If not, ask for a better day. Do not book anything. Thank the person and end the call.",
    "first_message": "Hi, this is a reminder call from Acme Dental about your appointment on Tuesday.",
    "voice_config": { "language": "en" },
    "metadata": { "appointment_id": "1042" }
  }'
```

What each field does:

- `to` and `recipient_consent` are required. `recipient_consent: true` is your statement that you have a lawful basis to call this person. Hail does not check it.
- `system_prompt` holds the instructions. To reuse a saved agent, send `agent_id` instead.
- `first_message` sets your opening after the AI disclosure. If you omit it, Hail generates an opening.
- `from` is optional. Leave it out and Hail uses one of your numbers, or a number from a shared pool.
- `voice_config` sets `language` and `voice_id`. There are 39 languages.
- `metadata` comes back on every read, so you can match the call to your own record.
- The `Idempotency-Key` header stops a retry from placing the same call twice. Use a new key for a new call.

## Read the result: statuses and webhooks

Save the `id` and read the call:

```bash
curl --fail-with-body --silent --show-error \
  "https://api.hail.so/v1/calls/$HAIL_CALL_ID" \
  -H "Authorization: Bearer $HAIL_API_KEY"
```

A live call shows `queued`, `dialing`, `ringing`, or `in_progress`. A finished call shows `completed`, `failed`, `busy`, `no_answer`, or `canceled`. Read `end_reason` to learn why it ended.

Polling works for a test. In production, register a webhook. Hail sends `call.answered`, `call.completed`, `call.failed`, `call.busy`, and `call.no_answer`. Each event carries the call `id`, `status`, `direction`, `from`, and `to`, and `end_reason` once the call ends. Webhooks are signed, so check the `X-Hail-Signature` header. The [webhooks docs](https://hail.so/docs/webhooks) show how.

A `completed` status means the call ended normally. It does not mean the person agreed. Read the recording or your own records before your code acts on the answer.

## What happens when voicemail answers

Hail runs answering machine detection on every outbound call. It checks the greeting before the agent speaks.

- A person, or an unclear result: the call goes on as normal.
- A voicemail or an unavailable line: the agent hangs up without a word. It never leaves a message.
- The call ends with status `no_answer` and `end_reason` set to `voicemail_reached` or `machine_unavailable`.

Plan a retry for these calls in your own code, or send a text with the [SMS API](https://hail.so/sms) instead. Machine-answered calls are billed, because billing starts when the line connects.

## Build an automated calling system, not one call

One call is a test. An automated calling system decides who to call, when, and what to do with each result. Use this checklist:

- [ ] Store consent for each person: where they gave it and when (`consent_source`, `consent_obtained_at`).
- [ ] Use a stable `Idempotency-Key` for each planned call.
- [ ] Respect opt-outs before every call, not only once a day.
- [ ] Handle `429` responses. Hail rate-limits calls. The response says which limit you hit and sends `Retry-After`.
- [ ] Handle `402`. It means the workspace is out of credits.
- [ ] Treat `no_answer` with `voicemail_reached` as "try another way", not as a refusal.
- [ ] Log `metadata` and the call `id` together, so support can find any call.

## Make your automated phone system honest

An automated phone system must be clear that it is a machine. Hail turns on AI disclosure by default (`ai_disclosure: true`). The agent says it is an AI at the start of the call. If you turn disclosure off, the change is logged and the responsibility is yours. The agent still says it is an AI when someone asks.

Keep each call to one purpose. Let people say no. Do not let the agent invent dates, prices, or promises that your system did not give it.

## AI phone calls: a reminder template
Short, specific AI phone calls work better than long scripts. Copy this template for a reminder call, then replace the parts in braces.

```prompt
You are an AI assistant calling for {business name}.
Purpose: confirm the {appointment type} on {day} at {time}.
Ask one question: "Does this time still work for you?"
If yes: thank them and end the call.
If no: ask for a better day and time. Repeat it back. Do not promise a booking or text. Do not book anything yourself.
If they ask who you are: say you are an AI assistant for {business name}.
If they ask to stop getting calls: say you will pass that on, thank them, and end the call.
Never ask for payment details. Keep each reply under two sentences.
```

Estimate the cost of a batch with the [voice agent cost calculator](https://hail.so/tools/voice-agent-cost-calculator), and check [pricing](https://hail.so/pricing) for current rates. For a first call to your own phone, follow [Make your first AI phone call](https://hail.so/blog/first-ai-phone-call).