Skip to main content
A voice interaction on Wave has three moving parts:

Numbers

A phone number (or SIP user) is the entry point — someone dials it, or you place a call from it.

Call flows

A call flow decides what the call does, expressed in WaveML — play a prompt, gather a digit, bridge, record, hand off to an AI agent.

Events

Every state change (ringing, answered, ended, a digit pressed) is delivered to your webhook endpoint.

​
The lifecycle of a call

1

A call starts

Either a caller dials your number (inbound), or you place one with the Callbacks API (outbound). Every call gets a stable wave_call_id (a UUID) that appears on all its events and in the call logs.
2

The engine runs your call flow

Wave’s voice engine fetches your call flow and executes it verb by verb. If the flow needs input (a keypad digit, an AI-agent outcome), the engine pauses, collects it, and continues — see the loop below.
3

Events reach your webhook

As the call progresses, Wave POSTs signed events to your endpoint: call.initiated, call.answered, call.ended, and — when a caller makes a menu choice — call.input.
4

The call appears in your logs

When it ends, the call (with duration, status, and any recording pointer) is in GET /v1/calls.

​
The call-flow loop

Call flows run as a chunked loop. When the engine needs instructions it sends your flow a JSON request; you reply with a WaveML document. The node_id on each verb is a cursor the engine echoes back, so your flow always knows where the call is.
You answer with WaveML. On a <Gather>, the caller’s digits come back on the next request as dtmf; on an <AIAgent>, the outcome comes back as aiagent_result. Branch on the node_id + the input to drive the call.
Where flows live today. The engine executes WaveML, but call flows are currently provisioned for your account (dashboard + your Wave contact) rather than authored through a public API. A call-flow authoring API is on the roadmap. You can build against everything else — placing calls, receiving events, reading logs, allocating numbers, managing queues — today.

​
Events you can subscribe to

Register an endpoint under Webhooks and subscribe to the voice events:

​
What you can build today

WaveML reference

Every verb a call flow can use.

Virtual numbers

Give each of your end-users their own Saudi number.

Queues

Route callers to agents and manage who’s logged in.

Webhooks

Receive call events at your endpoint.