# Call lifecycle

> What happens to a phone call from the first ring to the call.ended webhook, and when you are billed.

Source: https://docs.vlayers.ai/get-started/concepts/call-lifecycle

Kind: Concept

A call has a clear beginning, a middle made of turns, and an end that always has a recorded reason.

![Six steps. Ring, admission, start with the prompt sealed, and greeting run left to right. Then turns repeat: the caller speaks, the agent answers, tools pass the Action Guard, handlers run and a transfer can happen. When something ends the call, the call.ended webhook is sent and the call is charged, once, for the time it ran.](https://docs.vlayers.ai/portal-media/concepts/call-lifecycle.svg)

*One call, from ring to call.ended.*

## 1. Ring and admission

When a call arrives, VoiceLayer decides whether to let it through before the agent speaks. It checks your plan's limit on calls at once, your budgets and your wallet, which places a hold for the call. It also checks who may call, if you limited the agent to certain callers, and the per-caller rate limit.

A refused call is not billed. The caller hears a short polite line and the call ends with a reason that says why (for example `caller_not_allowed` or `rate_limited:caller`).

## 2. Start: the prompt is sealed

When the call starts, VoiceLayer fixes the agent's version and its prompt for the whole call. Edits you make in the dashboard apply to the next call, never to one in progress. See [How agents run](https://docs.vlayers.ai/build/deploy).

## 3. Greeting

The agent speaks its opening line. If you set a fixed greeting it is spoken as written; otherwise the model writes one from the prompt.

## 4. Turns

The caller speaks, the agent answers, and this repeats. Along the way:

- **Tools** the model calls pass the Action Guard first: a tool the agent never declared is refused, not run. A tool has 10 seconds by default.
- **Handlers** you wrote run as things happen. See [Handlers](https://docs.vlayers.ai/get-started/concepts/handlers).
- **A transfer** brings a person onto the line and the agent leaves. See [Transfers](https://docs.vlayers.ai/build/transfers).

## 5. End

Every call ends for one reason. In code it is the `trigger` your end-of-call hook receives:

| Trigger | What happened |
|---|---|
| `tool` | The model used the built-in end-call tool. |
| `user` | Your code called `ctx.endCall()`. |
| `host` | An outside controller, such as a connected assistant, sent a hangup. It cannot be vetoed. |
| `idle` | The line was silent for too long. |
| `max_duration` | The call hit its time limit (the agent's own, never above the plan's). |
| `participant-left` | The last person left the room. |
| `flow` | A flow finished and asked to hang up. |
| `engine-closed` | The realtime engine closed under the call. |
| `admission` | The platform refused the call at the door, after speaking its line. |
| `agent-disconnected` | The agent left the room while the caller was still there, so the call is torn down. |

## 6. call.ended

After the end, VoiceLayer sends the `call.ended` webhook with the duration, the end reason, the outcome, the captured fields and the transcript. If the agent's worker has not yet confirmed its last words, a flag says so, and `GET /v1/calls/{id}/result` has the rest. See [Webhooks](https://docs.vlayers.ai/developers/receive/webhooks).

## What is billed when

When a call is let through, VoiceLayer places a hold on your wallet; a refused call places none. The hold is released when the call ends, and the call is charged then, once, for the exact time it ran (not rounded up to the minute). Very short calls of a few seconds are not charged. The phone leg's rate depends on its direction (inbound or outbound); the platform fee and the speech and model usage are charged beside it. See [Billing](https://docs.vlayers.ai/build/billing) for the rates and where each charge shows.

## Next

- [Handlers](https://docs.vlayers.ai/get-started/concepts/handlers): which of your code runs when.
- [Outbound calls](https://docs.vlayers.ai/build/outbound-calls): the same lifecycle, started by you.
