Call lifecycle
What happens to a phone call from the first ring to the call.ended webhook, and when you are billed.
A call has a clear beginning, a middle made of turns, and an end that always has a recorded reason.
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.
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.
- A transfer brings a person onto the line and the agent leaves. See 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.
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 for the rates and where each charge shows.
Next
- Handlers: which of your code runs when.
- Outbound calls: the same lifecycle, started by you.