Concept

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.

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.
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.

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:

TriggerWhat happened
toolThe model used the built-in end-call tool.
userYour code called ctx.endCall().
hostAn outside controller, such as a connected assistant, sent a hangup. It cannot be vetoed.
idleThe line was silent for too long.
max_durationThe call hit its time limit (the agent's own, never above the plan's).
participant-leftThe last person left the room.
flowA flow finished and asked to hang up.
engine-closedThe realtime engine closed under the call.
admissionThe platform refused the call at the door, after speaking its line.
agent-disconnectedThe 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

On this page