Make your first AI phone call with a voice API

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 with credits, an API key, and an active voice-capable number in your workspace. 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.

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 for the complete request and response fields.

Read the call result

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

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 or a longer summary through the email API. Make that follow-up depend on the call result.

The voice API overview covers the available integration paths. Before running a larger batch, estimate usage with the voice agent cost calculator and check the current Hail rate card.