# Make your first AI phone call with a voice API

> For your first AI phone call, call your own phone and give the agent one small job. Send one request to Hail's voice API with a system prompt and recipient consent. The call runs after the request returns, so read its status and transcript before you act on it.

- URL: https://hail.so/blog/first-ai-phone-call
- Type: Tutorial
- Tags: voice-agent, getting-started
- Published: 2026-09-26
- Updated: 2026-11-03
- Reading time: 4 min

A voice API can accept your request before anyone answers the phone. That matters: if your application treats the first response as a finished conversation, it can send a confirmation for something the customer never agreed to.

For a first test, give the agent one small job and call your own phone. Here we will ask whether now is a good time for a callback, then inspect what happened.

## Before making the call

You need a Hail account, an API key, and an active voice-capable number in your workspace. Calls use your prepaid balance. Top it up on the **Usage & billing** page in the console. Keep the key on your server. Put it in the `HAIL_API_KEY` environment variable rather than a browser bundle or source file.

The phone numbers below are placeholders. Replace `from` with your Hail number and `to` with your own phone, both in international E.164 format. The example sets `recipient_consent` to `true` because you are calling yourself. For another recipient, that field must reflect permission you actually obtained.

## Give the agent a narrow task

“Call the customer” leaves too much undefined. Give the agent a question, limits, and a way to finish. This example asks about availability. It does not give the agent access to a calendar or permission to promise a booking.

```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: first-call-test-001' \
  --data '{
    "from": "+14155550100",
    "to": "+14155550101",
    "recipient_consent": true,
    "system_prompt": "You are an AI assistant making a test callback. Ask whether now is a good time to talk. If not, ask for a preferred callback time. Do not claim to book anything. Thank the person and end the call after their answer.",
    "first_message": "Hi, this is an AI assistant making the test call you requested. Is now a good time to talk?",
    "tools": []
  }'
```

`tools: []` keeps this first test conversational: the agent cannot invoke extra tools during the call. The idempotency key identifies this particular attempt. Keep it unchanged when retrying the same request after a connection problem; use a new key for a deliberately new call.

Hail's create-call endpoint returns HTTP `201` with a call object. Save its `id`. The call runs asynchronously, so its initial status is not evidence that someone answered. See the [Hail API contract](https://github.com/hail-hq/hail/blob/main/openapi/openapi.yaml) for the complete request and response fields.

## Read the call result

Set `HAIL_CALL_ID` to the returned `id`, then request the call record:

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

While the call is active, you may see `queued`, `dialing`, `ringing`, or `in_progress`. Terminal states include `completed`, `busy`, `no_answer`, `failed`, and `canceled`. Inspect `end_reason` when a call finishes unexpectedly.

For a manual test, check again after the conversation ends. In an application, use a bounded polling loop or subscribe to call events. Avoid polling indefinitely or starting another call just because the first one has not finished yet.

## Listen for the mistakes a status cannot explain

A completed call can still be an unsuccessful task. Listen to the test and review the transcript. Did the agent ask one question at a time? Did it stop when you declined? Did it invent a callback appointment?

Try answering “not now” and giving an ambiguous time such as “later.” Those responses expose gaps that an easy yes will miss. Keep the result as a request for your application to interpret; do not create a calendar event unless you have enough information and an actual booking step.

These snippets show the request structure, not a recorded customer conversation. Your call record and transcript are the evidence for your own test.

## Add the next step only after the first works

Once the call behaves as intended, you can send a short confirmation through the [SMS API](https://hail.so/sms) or a longer summary through the [email API](https://hail.so/email). Make that follow-up depend on the call result.

The [voice API overview](https://hail.so/voice) covers the available integration paths. Check the [current Hail rate card](https://hail.so/pricing) before running a larger batch.