AI outbound calls: make your first call

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.

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.

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:

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

Estimate the cost of a batch with the voice agent cost calculator, and check pricing for current rates. For a first call to your own phone, follow Make your first AI phone call.