WaveML reference

WaveML is the small XML language that describes what happens on a call: play a prompt, collect a digit, bridge to an agent, record, hand off to an AI voice agent. If you know TwiML, WaveML will feel familiar.

How call flows are authored today. WaveML is what Wave’s voice engine executes. Right now, call flows are provisioned for your account (dashboard + your Wave contact) rather than authored through a public API — a call-flow authoring API is on the roadmap. This page is the reference for the language itself, so you know exactly what a flow can do and can spec yours precisely.

The response envelope

When a call needs instructions, the engine sends your flow a request and expects a WaveML document in reply. Verbs run top to bottom; the call ends on <Hangup> or an empty <Response>.

<?xml version="1.0" encoding="UTF-8"?>
<Response wave_tenant="acme" wave_tenant_cc="20">
  <Say node_id="n1">Welcome to Acme.</Say>
  <Hangup node_id="n2"/>
</Response>

On the first reply of a call, set wave_tenant and its concurrency limit wave_tenant_cc on the root <Response>. Every verb carries a node_id — a cursor the engine echoes back on its next request so your flow knows where the call is. See How voice works for the full request/response loop.

Play

Play an audio file (WAV/MP3 over HTTPS).

<Play node_id="n1">https://cdn.example.com/welcome.wav</Play>

Attribute	Description	Default
`node_id`	Unique id for this step.	—
`loop`	Times to repeat.	`1`
`digit`	A DTMF digit that interrupts playback.	—

Say

Speak text with the engine’s text-to-speech. Arabic and English are supported.

<Say node_id="n1" language="ar">أهلاً بك في أكمي</Say>

Attribute	Description	Default
`node_id`	Unique id for this step.	—
`voice`	Voice hint for the TTS.	—
`language`	BCP-47 language tag, e.g. `ar`, `en`.	—

Pre-recorded <Play> audio starts instantly; <Say> goes through text-to-speech. For fixed prompts, prefer <Play>.

Gather

Collect DTMF (keypad) input. Nest a <Say> or <Play> inside as the prompt; the digits the caller presses arrive on the next request as dtmf.

<Gather node_id="menu" numDigits="1" timeout="8">
  <Say>For sales press 1, for support press 2.</Say>
</Gather>

Attribute	Description	Default
`node_id`	Unique id for this step.	—
`numDigits`	How many digits to collect.	—
`timeout`	Seconds to wait for input.	—
`finishOnKey`	Key that ends collection early (e.g. `#`).	—
`tries`	Re-prompt attempts.	—

Dial

Bridge the call to another number or SIP user. The dialed party sees callerId.

<Dial node_id="n1" callerId="0115209300" record="true">920012345</Dial>

Attribute	Description	Default
`node_id`	Unique id for this step.	—
`callerId`	Number presented to the dialed party.	—
`timeout`	Seconds to wait for an answer.	—
`timeLimit`	Max call duration, seconds.	—
`dialMusic`	Ringback / music URL.	—
`record`	`true` records the bridged leg.	`false`

Enqueue

Place the caller in a call-center queue. Agents ring when they’re logged in — manage them with the Queues API. The queue name is the element’s text; queues are created on demand.

<Enqueue node_id="n1" strategy="ring-all" moh="https://cdn.example.com/hold.wav">support</Enqueue>

Attribute	Description	Default
`node_id`	Unique id for this step.	—
`strategy`	`ring-all` or `round-robin`.	`ring-all`
`moh`	Music-on-hold URL.	—

Record

Record the call. Because <Enqueue>/<Say> have no inline record attribute, a standalone <Record background="true"/> arms recording for a call that then flows into other verbs.

<Response wave_tenant="acme">
  <Record node_id="rec" background="true"/>
  <Enqueue node_id="n1">support</Enqueue>
</Response>

Attribute	Description	Default
`node_id`	Unique id for this step.	—
`background`	`true` records in the background and continues the flow immediately.	`false`

AIAgent

Hand the call to a real-time AI voice agent. Speech-to-text, a language model, and text-to-speech run live, with barge-in. The element’s text is the agent’s persona prompt.

<AIAgent node_id="n2">
  You are Noura, a friendly outreach voice for Alfa Electric.
  If the customer asks for a human, end with the outcome word "transfer".
  If they ask never to be contacted, end with the outcome word "dnc".
</AIAgent>

<AIAgent> is not terminal. When the conversation ends, the engine comes back to your flow with this verb’s node_id and an aiagent_result outcome word — completed, transfer, dnc, or any word your prompt defines — and your flow decides what happens next:

<!-- aiagent_result=transfer -> connect a human -->
<Response>
  <Dial node_id="n3" callerId="0115209300">920012345</Dial>
  <Hangup node_id="n4"/>
</Response>

Attribute	Description	Default
`node_id`	Unique id for this step.	—
`voice`	Voice hint for the agent’s text-to-speech.	—

Always handle an unrecognized aiagent_result with a safe fallback — treating it like completed and hanging up is a good default.

Pause

Wait silently.

<Pause node_id="n1" length="2"/>

Attribute	Description	Default
`node_id`	Unique id for this step.	—
`length`	Seconds to wait.	`1`

Hangup

End the call.

<Hangup node_id="n1"/>

Next steps

How voice works

The request/response loop the engine drives.

Queues

Sign agents in and out of <Enqueue> queues.

Get Started

Voice

Web Callback

Reference

The response envelope

Play

Say

Gather

Dial

Enqueue

Record

AIAgent

Pause

Hangup

Next steps

How voice works

Queues

​The response envelope

​Play

​Say

​Gather

​Dial

​Enqueue

​Record

​AIAgent

​Pause

​Hangup

​Next steps

How voice works

Queues

The response envelope

Play

Say

Gather

Dial

Enqueue

Record

AIAgent

Pause

Hangup

Next steps