# AgentLine Calls

Place outbound calls, watch them live, hang up, and read transcripts. Calls cost
$0.10 a minute in both directions. Need an agent and number first? Use
https://agentline.md/agents.md and
https://agentline.md/numbers.md

## Before Calling

1. Confirm the call with the human. Never auto-dial.
2. Check the balance. Calls need at least $0.50:

   ```bash
   curl -s https://api.agentline.cloud/v1/billing/balance \
     -H "Authorization: Bearer $AGENTLINE_API_KEY"
   ```

3. The agent must have an active number. `400 "Agent has no active phone
   number"` means buy one first.

## Call

Write the payload to a file; inline JSON with apostrophes breaks.

```bash
cat > /tmp/al_call.json <<'EOF'
{
  "agent_id": "agt_xxx",
  "to_number": "+12125557890",
  "system_prompt": "You are Alex, confirming tomorrow's 3pm dentist appointment for Sam. Ask yes or no. Under 12 words per turn.",
  "initial_greeting": "Hi, this is Alex calling about Sam's appointment tomorrow."
}
EOF

curl -s -X POST https://api.agentline.cloud/v1/calls \
  -H "Authorization: Bearer $AGENTLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @/tmp/al_call.json
```

| Field | Required | Notes |
|---|---|---|
| `agent_id` | Yes | Agent placing the call. |
| `to_number` | Yes | E.164 destination. |
| `system_prompt` | No | Replaces the agent prompt for this call only. |
| `initial_greeting` | No | Replaces the agent greeting for this call only. |
| `voice_id` | No | Replaces the voice for this call only. |
| `from_number_id` | No | Number to call from. Defaults to the agent's number. |

The response has the `call_id`.

## Watch the Call

Poll every 10 seconds until `status` is `completed` or `failed`. Real calls
take 45 to 120 seconds. Do not wait silently and do not poll less often.

```bash
curl -s https://api.agentline.cloud/v1/calls/CALL_ID \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"

curl -s https://api.agentline.cloud/v1/calls/CALL_ID/transcript \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

Each poll, read the transcript: who answered, what was said, whether an IVR or
mailbox picked up. A call is not done until you have the final transcript.
Summarize it for the human.

Statuses: `initiated`, `in-progress`, `completed`, `failed`. Busy, no-answer,
and canceled outcomes arrive as `call.busy`, `call.no-answer`, and
`call.canceled` events.

## What Picks Up

Outbound calls listen first and handle the answer automatically:

| Heard | Agent does |
|---|---|
| Live human ("Hello?") | Speaks `initial_greeting`. |
| Voicemail greeting | Waits for the beep, leaves `voicemail_message`, hangs up. |
| Voicemail key menu ("press 2 to record") | Presses 2, leaves `voicemail_message`. |
| IVR ("press 1 for sales") | Sends a real DTMF tone for a key the menu offered. |
| Call screening ("state your name") | States name and purpose. |

Without `voicemail_message` on the agent, the call hangs up at a mailbox. Do
not add IVR or voicemail rules to the prompt; that fights the built-in handler.

On the first 10-second poll, hang up if the agent presses a key the menu did
not offer or repeats the same key.

## Hang Up

```bash
curl -s -X POST https://api.agentline.cloud/v1/calls/CALL_ID/hangup \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

The final transcript and billing are processed after hangup.

## Transcripts

`GET /v1/calls/{id}/transcript` returns `[{role, text, timestamp}]`. `role` is
`human` (the other party) or `agent`. The `conversation` field on
`call.utterance` events uses `user` and `assistant` instead.

## List

```bash
curl -s "https://api.agentline.cloud/v1/calls?status=completed&limit=10" \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

Filters: `agent_id`, `status`, `limit`, `offset`.

## Inbound Calls

Inbound calls are answered by the hosted voice with the agent's prompt and
greeting. They emit `call.received`, then `call.completed`. To answer
questions the voice cannot, connect the runtime with
https://agentline.md/relay.md

## Owner Task Calls

If `to_number` equals the agent's `owner_phone`, the call is a task call. The
completed call emits `call.owner_task`; execute the human turns. See
https://agentline.md/agents.md

AgentLine: https://agentline.cloud | API: https://api.agentline.cloud | All guides: https://agentline.md