> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Call Lifecycle & States

> How a call flows end to end, every state it moves through, voicemail detection, and the end reasons your agent observes.

Every call - whether you start it or a caller rings in - ends up the same way:
a Unpod media worker and the caller are the two participants in a LiveKit room,
and the worker bridges the audio while streaming transcripts to your
`AgentRunner` over a separate text-only bridge. Your dialog brain never joins the
room or touches audio. This page traces both directions, the states a call moves
through, and how it can end.

Call lifecycle

<ol>
  <li>Caller→Number**Call start.** The call reaches Unpod - a caller rings in, or you dial out.</li>
  <li>Speech pipeline**Audio to text.** Unpod transcribes the caller. Audio stays on Unpod's side.</li>
  <li>Orchestrator→AgentRunner**Dispatch.** The call goes to your runner, which opens a `Session`.</li>
  <li>Session→DialogMachine**Turn.** Your dialog logic reads the caller's text and decides the reply.</li>
  <li>AgentRunner→Speech pipeline**Reply text.** Unpod synthesizes it to speech for the caller. Steps 2-5 repeat every turn.</li>
  <li>Storage + hooks**Call end.** Transcript, metrics and webhooks are recorded and sent.</li>
</ol>

Unpod runs itYou run itCaller

## The state machine

Call states

pendingOutbound only, after calls.create()dialingringingInbound calls start hereansweredactiveYour agent is talkinghangupcompletedHangup or end() after being active

failed
From `ringing`: no answer, busy, blocked, cancelled, or voicemail before connect. From `active`: an error.

| Visible `status` | Internal state | What is happening |
| - | - | - |
| `pending` | queued | Enqueued; waiting for a concurrency slot (outbound only). |
| `ringing` | `dialing` / `ringing` | The SIP leg is originating, or the far end is ringing. |
| `active` | `active` | Both legs connected; your agent is talking to the caller. |
| `completed` | `ended` | The conversation finished after being active. |
| `failed` | `not_connected` / `cancelled` | Never reached a live conversation, or cancelled pre-connect. |

> [!NOTE]
>
> Inbound calls skip `pending` and dialing - the caller is already on the line,
> so the call starts at `ringing`/`active`. Only outbound calls pass through the
> full sequence. You never drive these states yourself; you observe them via the
> call `status`, the `call_end` hook, and the final `end_reason`.

## Outbound: what happens after `calls.create()`

`calls.create()` is **asynchronous**. It does not wait for the phone to ring -
it puts your call on a queue and returns immediately with `status: "pending"`.
The actual dialing happens in the background, gated by your plan's per-account
concurrency limit.

**1. You enqueue the call**

`calls.create(pipe_id, to_number, ...)` records the call and returns `201`
with `status: "pending"`. Your request is never blocked on the network.

**2. Unpod gates on concurrency**

A background worker picks up the call. If your account is at its
concurrent-call cap, the call is automatically rescheduled and retried
shortly - no error, no dropped call.

**3. Unpod dials the number**

Unpod creates a room and originates the SIP call to `to_number`. The call
row moves to `ringing`, and you get a `session_id`.

**4. Your agent joins and talks**

A Unpod media worker joins the room and bridges the caller's audio;
transcripts stream to your `AgentRunner` over its text bridge and reply text
comes back for TTS. The call row moves to `active`, then `completed` on
hangup.

Outbound call, step by step

<ol>
  <li>Your backend→Unpod API`calls.create(pipe_id, to_number)`</li>
  <li>Unpod API→Your backend`201` with `status: pending`, right away.</li>
  <li>Unpod API→QueueEnqueues the call. The queue checks your per-account concurrency.</li>
  <li>Queue→LiveKit + SIPCreates a room and dials `to_number`.</li>
  <li>LiveKit + SIP→AgentRunnerA media worker bridges the call; your runner connects over text.</li>
  <li>LiveKit + SIP→AgentRunnerCaller transcript arrives as text.</li>
  <li>AgentRunner→LiveKit + SIPReply text goes back; Unpod synthesizes it to speech.</li>
</ol>

`status`: pending → ringing → active → completed

> [!TIP]
>
> Because `create()` returns `pending`, poll `client.calls.get(call_id)` to watch
> the status advance. Don't assume the call is connected the moment `create()`
> returns.

## Inbound: what happens when someone calls your number

Inbound is simpler - there is no queue, because there is nothing to rate-limit.
The moment a caller dials a number attached to your agent, the call is
already live and Unpod connects your agent to it.

**1. Caller dials your number**

The carrier delivers the call over SIP. LiveKit answers, creates a room,
and adds the caller as a participant.

**2. Unpod resolves your pipe**

Unpod matches the dialed number to your agent and its voice profile.

**3. Your agent is bridged to the live call**

A Unpod media worker joins the room the caller is already in and bridges the
audio; transcripts start streaming to your `AgentRunner` over its text
bridge immediately.

## The audio + transcript path

Once both legs are in the room, every call works the same way. Unpod's speech
stack transcribes the caller and streams plain **text** to your `AgentRunner`;
your dialog logic replies with text; Unpod synthesizes it back to speech.

The animated lifecycle above is the same loop in motion: call audio stays on
Unpod's side, text crosses into your runner, and reply text comes back for TTS.

> [!NOTE]
>
> Your `agent_id` selects **which dialog brain** runs for the call - it is not
> how Unpod routes the phone number. Number routing is handled by the
> [agent](https://docs.unpod.ai/get-started/core-concepts.md#agent) the number is attached to.

## Voicemail detection

Unpod automatically detects when an outbound call has reached a voicemail
system so your agent does not waste a turn talking to a machine. There are two
detection points:

**1. Pre-connect (during ringing)**

Many carriers route "forwarded to voicemail" to a SIP *user-unavailable*
signal after a brief ring. When Unpod sees this pattern, it classifies the
call as voicemail **before** it ever connects, ends the call, and reports
`end_reason: "VOICEMAIL_DETECTED_PRECONNECT"`.

**2. Post-connect (just after answer)**

Some voicemail systems answer, play a greeting, then go silent. If a call
connects, the caller never speaks, and the leg ends within a short window,
Unpod classifies it as voicemail and reports
`end_reason: "AGENT_HUNG_UP_VOICEMAIL_DETECTED"`.

## End reasons

When a call finishes, Unpod records why. These are the reasons you are most
likely to act on:

| `end_reason` | Meaning |
| - | - |
| `USER_HUNG_UP_IN_CALL` | The caller hung up during the conversation. |
| `USER_DID_NOT_PICK_UP` | Outbound call rang out with no answer. |
| `USER_HUNG_UP_RINGING` | The caller rejected the call while ringing. |
| `AGENT_HUNG_UP_SILENCE_DETECTED` | The agent ended the call after prolonged user silence. |
| `AGENT_HUNG_UP_VOICEMAIL_DETECTED` | Voicemail detected after connect; agent hung up. |
| `VOICEMAIL_DETECTED_PRECONNECT` | Voicemail detected during ringing; call never connected. |
| `MAX_DURATION_REACHED` | The hard per-call duration cap was hit. |
| `IDLE_TIMEOUT` | The call was idle too long and was reaped. |
| `SIP_FAILED_WRONG_NUMBER` | The number was invalid or unreachable. |
| `SIP_FAILED_NUMBER_BLOCKED` | The carrier blocked the call. |

> [!NOTE]
>
> This is not the full set - additional reasons exist for SIP/trunk
> configuration errors and handover edge cases. Treat unknown reasons as a
> generic failure and log them.

## Reacting to outcomes in your agent

Observe telephony outcomes through hooks rather than polling:

```python theme={null}
@ctx.session.on("call_end")
async def on_end(final_state: str) -> None:
    reason = ctx.session.data.get("end_reason")
    if reason == "VOICEMAIL_DETECTED_PRECONNECT":
        await schedule_retry(ctx.user_number, after_minutes=120)
    elif reason in ("SIP_FAILED_WRONG_NUMBER", "SIP_FAILED_NUMBER_BLOCKED"):
        await mark_unreachable(ctx.user_number)
```

## Related

* [Outbound Calls](https://docs.unpod.ai/agent-sdk/outbound-calls.md) - the `calls.create()` API in detail
* [Agents](https://docs.unpod.ai/speech-stack/agents.md) - one `agent_id`, one brain, N voices; what a number attaches to
* [Hooks & Events](https://docs.unpod.ai/speech-stack/hooks-events.md) - every lifecycle event you can hook
* [AgentRunner & Sessions](https://docs.unpod.ai/agent-sdk/agent-runner.md) - ending and transferring live calls


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.