IVR Menus

An IVR menu greets a caller, reads out a few options, and routes them by the key they press — “press 1 for sales, press 2 for support.” You author the menu once with this API (or the dashboard), bind it to one of your Wave numbers, and Wave serves it live to every caller — no redeploy. Under the hood a menu compiles to a WaveML <Gather> that plays your greeting and collects one keypress, then runs the branch for that digit. This API is the authoring layer on top of WaveML — you describe the menu as JSON and Wave turns it into the call flow.

This page starts with the single-level menu — one greeting, one set of keypad options, each ending the call or handing it off. For sub-menus, “press 9 for the main menu” and repeat-on-silence, write a multi-level menu (a graph) — see Multi-level menus (graph) below. A visual flow builder is a separate, later feature.

Authentication & tiers

All /v1/callflows endpoints take an API key with the callflows:read or callflows:write scope, or a dashboard session. You can author and test menus with a sandbox key (sk_sandbox_); serving a menu to a real inbound call needs a production key (sk_live_), a production-tier org, and a bound number (see Bind a number below). A menu is a JSON definition: a greeting, the keypad branches, and an optional fallback for when the caller presses nothing.

{
  "prompt": { "say": { "text": "To authenticate press 1, to decline press 2", "language": "en" } },
  "gather": { "num_digits": 1, "timeout_seconds": 8 },
  "branches": [
    { "digit": "1", "action": { "say": { "text": "You are authenticated. Goodbye." } }, "input": { "authenticated": true } },
    { "digit": "2", "action": { "say": { "text": "You chose not to authenticate. Goodbye." } }, "input": { "authenticated": false } }
  ],
  "no_input": { "action": { "say": { "text": "We didn't get your input. Goodbye." } } }
}

Field	Type	Required	Notes
`prompt`	object	yes	The greeting. Exactly one of `say` or `play` (below).
`gather.num_digits`	integer	no	Digits to collect, `1`–`10`. Default `1`.
`gather.timeout_seconds`	integer	no	Seconds to wait for a keypress, `1`–`60`. Default `8`.
`branches`	array	yes	1–12 keypad options. Each `digit` must be unique.
`no_input`	object	no	Action taken if the caller presses nothing before `timeout_seconds`.

Prompt and actions

A prompt and every branch action is one of these. A branch action is a terminal leaf — it ends the call or hands it off.

Action	Shape	What it does
`say`	`{ "text": "…", "language"?: "en" }`	Speaks text (TTS). `text` ≤ 1000 chars.
`play`	`{ "audio_ref": "https://…" }`	Plays a pre-recorded audio prompt (below). Prompt or action.
`dial`	`{ "number": "0112345678" }`	Forwards the caller to a KSA number.
`enqueue`	`{ "queue": "support", "strategy"?: "ring-all" }`	Sends the caller into a queue.
`hangup`	`true`	Ends the call.

dial targets are restricted to Saudi (KSA) phone numbers — a toll-fraud guard, since a <Dial> bridges the caller out to a new leg.

Branch input (your webhook payload)

Give a branch an input object and Wave merges it into the call.input webhook when the caller picks that option — your integration’s hook for what the caller chose.

Up to 20 fields; values are string (≤512), number, or boolean.
The keys call_id, digits, node and limit_reached are reserved (Wave sets them) and rejected.

POST /v1/callflows — create a menu by name. Pass "activate": true to make it live immediately.

curl -X POST https://api.wave.sa/v1/callflows \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auth-ivr",
    "activate": true,
    "definition": {
      "prompt": { "say": { "text": "To authenticate press 1, to decline press 2" } },
      "branches": [
        { "digit": "1", "action": { "say": { "text": "You are authenticated. Goodbye." } }, "input": { "authenticated": true } },
        { "digit": "2", "action": { "say": { "text": "You chose not to authenticate. Goodbye." } }, "input": { "authenticated": false } }
      ]
    }
  }'

const res = await fetch("https://api.wave.sa/v1/callflows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "auth-ivr",
    activate: true,
    definition: {
      prompt: {
        say: {
          text: "To authenticate press 1, to decline press 2",
        },
      },
      branches: [
        {
          digit: "1",
          action: {
            say: {
              text: "You are authenticated. Goodbye.",
            },
          },
          input: {
            authenticated: true,
          },
        },
        {
          digit: "2",
          action: {
            say: {
              text: "You chose not to authenticate. Goodbye.",
            },
          },
          input: {
            authenticated: false,
          },
        },
      ],
    },
  }),
});
console.log(await res.json());

import os

import requests

res = requests.post(
    "https://api.wave.sa/v1/callflows",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
    json={
        "name": "auth-ivr",
        "activate": True,
        "definition": {
            "prompt": {
                "say": {
                    "text": "To authenticate press 1, to decline press 2",
                },
            },
            "branches": [
                {
                    "digit": "1",
                    "action": {
                        "say": {
                            "text": "You are authenticated. Goodbye.",
                        },
                    },
                    "input": {
                        "authenticated": True,
                    },
                },
                {
                    "digit": "2",
                    "action": {
                        "say": {
                            "text": "You chose not to authenticate. Goodbye.",
                        },
                    },
                    "input": {
                        "authenticated": False,
                    },
                },
            ],
        },
    },
)
print(res.json())

Field	Type	Required	Notes
`name`	string	yes	`A–Z a–z 0–9 _ -` and spaces, ≤100 chars. Unique per org — the routing key.
`definition`	object	yes	The menu definition (above).
`activate`	boolean	no	`true` makes this version live on create. Default `false`.

201 Created returns the menu, including its version history:

{
  "name": "auth-ivr",
  "kind": "menu",
  "version": 1,
  "is_active": true,
  "definition": { "prompt": { "…": "…" }, "gather": { "num_digits": 1, "timeout_seconds": 8 }, "branches": [ "…" ] },
  "created_at": "2026-08-28T10:00:00.000Z",
  "updated_at": "2026-08-28T10:00:00.000Z",
  "versions": [ { "version": 1, "is_active": true, "created_at": "2026-08-28T10:00:00.000Z" } ]
}

A duplicate name returns 409 — use PUT to add a version instead.

List and fetch menus

GET /v1/callflows lists one row per menu (its active or latest version):

{
  "data": [
    { "name": "auth-ivr", "kind": "menu", "version": 2, "is_active": true, "updated_at": "2026-08-28T11:00:00.000Z" }
  ]
}

GET /v1/callflows/{name} returns the full menu — the active (or latest) version’s definition plus the complete versions history. 404 if the menu doesn’t exist. Add ?version=N to read one version instead — for example a saved draft that is not live, or an older version: GET /v1/callflows/auth-ivr?version=3. The response has the same shape; is_active tells you whether that version is live. 404 if that version doesn’t exist; 400 if N is not a positive integer. Each flow has a kind: menu (single-level) or graph (multi-level). The definition comes back in the shape you wrote it: a menu as its prompt, gather, branches and no_input, and a graph with its ui fields. So you can send a definition that you read back to PUT with no change. A flow that Wave set up for you (not through this API) can read back in a simpler form: each option shows only its main action. If you PUT it back, the new version stores that simpler form.

Versioning and rollback

Menus are immutable and append-only. Editing never mutates a version in place — it appends a new one.

PUT /v1/callflows/{name} with a new definition (and optional activate) adds the next version. 404 if the menu doesn’t exist.
To avoid lost updates, also send base_version: the version you read and edited. If someone saved a later version first, the PUT returns 409 CALLFLOW_VERSION_CONFLICT and writes nothing; the message names the latest version. Read that version, apply your change again, and send it as the new base_version. Without base_version, PUT always appends (as before).
POST /v1/callflows/{name}/activate with { "version": N } makes version N live — rollback is just activating an older version. 404 if that version doesn’t exist.

# Roll back to version 1
curl -X POST https://api.wave.sa/v1/callflows/auth-ivr/activate \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version": 1 }'

// Roll back to version 1
const res = await fetch("https://api.wave.sa/v1/callflows/auth-ivr/activate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    version: 1,
  }),
});
console.log(await res.json());

import os

import requests

# Roll back to version 1
res = requests.post(
    "https://api.wave.sa/v1/callflows/auth-ivr/activate",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
    json={
        "version": 1,
    },
)
print(res.json())

Both return the menu object with the newly-active version.

Bind a number

POST /v1/callflows/{name}/bind-number points one of your Wave numbers at the menu’s active version — inbound calls to that number then run the menu.

curl -X POST https://api.wave.sa/v1/callflows/auth-ivr/bind-number \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "f933e0c3-45a9-4b25-b469-624745a3f8ef" }'

const res = await fetch("https://api.wave.sa/v1/callflows/auth-ivr/bind-number", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number_id: "f933e0c3-45a9-4b25-b469-624745a3f8ef",
  }),
});
console.log(await res.json());

import os

import requests

res = requests.post(
    "https://api.wave.sa/v1/callflows/auth-ivr/bind-number",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
    json={
        "phone_number_id": "f933e0c3-45a9-4b25-b469-624745a3f8ef",
    },
)
print(res.json())

Field	Type	Required	Notes
`phone_number_id`	uuid	yes	A number your org owns. `404` if it isn’t yours; `409` if the menu has no active version.

Returns { "bound": true }. Numbers are Wave-provided — see Virtual Numbers. DELETE /v1/callflows/{name} soft-retires a menu: it stops serving callers and any bound number is unlinked, but the version history is kept (you can recreate it later). Returns { "retired": true }; 404 if the menu doesn’t exist.

The `call.input` webhook

When a caller presses a digit, Wave sends a call.input webhook. Its data carries the pressed digits plus that branch’s input object — so your backend learns exactly what the caller chose:

{
  "event": "call.input",
  "data": { "call_id": "…", "digits": "1", "authenticated": true }
}

Multi-level menus (graph)

A graph is a menu with more than one level. You write it as a set of named nodes. Each node does one thing and points to the next node. The call starts at the start node. Send a graph to the same routes as a menu: POST /v1/callflows and PUT /v1/callflows/{name}, with "kind": "graph" in the definition. Activate, rollback, retire and bind work the same as for a menu.

{
  "kind": "graph",
  "start": "welcome",
  "on_limit": "bye",
  "nodes": {
    "welcome": { "type": "say", "text": "Welcome to Acme.", "next": "main" },
    "main": {
      "type": "menu",
      "prompt": { "say": { "text": "Press 1 for sales. Press 2 for support." } },
      "options": [
        { "digit": "1", "next": "sales", "input": { "team": "sales" } },
        { "digit": "2", "next": "support", "input": { "team": "support" } }
      ],
      "no_input": { "next": "main" },
      "invalid": { "next": "sorry" }
    },
    "sorry": { "type": "say", "text": "That is not an option.", "next": "main" },
    "sales": {
      "type": "menu",
      "prompt": { "say": { "text": "Press 1 for new orders. Press 9 for the main menu." } },
      "options": [
        { "digit": "1", "next": "neworders" },
        { "digit": "9", "next": "tomain" }
      ]
    },
    "tomain": { "type": "goto", "next": "main" },
    "neworders": { "type": "dial", "target": "0112345678" },
    "support": { "type": "enqueue", "queue": "support" },
    "bye": { "type": "say", "text": "Goodbye.", "next": "end" },
    "end": { "type": "hangup" }
  }
}

Nodes

Node ids use lower-case letters and digits, 1–12 characters (main, sales2). Every node can also have ui: { "x": number, "y": number, "label"?: string } — layout data for a visual builder. label is the node’s display name in any language (for example "القائمة الرئيسية"), 1–40 characters after spaces are trimmed, with no control characters or bidi overrides. Wave trims label and otherwise stores ui and gives it back unchanged. It does not change the call: the node id stays the routing key, and label never goes to the caller or to your webhook.

`type`	Fields	What it does
`menu`	`prompt`, `options`, `no_input`?, `invalid`?, `timeout_seconds`?	Plays the prompt and waits for one key. `prompt` is one of `say` or `play`, as in a single-level menu. `options` is 1–12 items of `{ "digit", "next", "input"? }`. Each `digit` is one key (`0`–`9`, `*`, `#`) and is unique in the menu. `timeout_seconds` is `1`–`60`, default `8`.
`say`	`text`, `language`?, `next`	Speaks text (TTS), then goes to `next`.
`play`	`audio_ref`, `next`	Plays an audio prompt that you uploaded, then goes to `next`.
`goto`	`next`	Goes to `next`. Use it for “press 9 for the main menu” or “press * to repeat”.
`dial`	`target`	Connects the caller to a KSA number. The call ends after the dial.
`enqueue`	`queue`, `strategy`?, `moh`?	Sends the caller into a queue. `moh` is hold music: an `audio_ref` that you uploaded. The call ends after the queue.
`hangup`	—	Ends the call.

No input, wrong key, and the loop limit

No key before timeout_seconds: the call goes to the menu’s no_input node.
A key that is not an option: the call goes to the menu’s invalid node.
If you do not set no_input or invalid, Wave plays the same menu again.
A call can take 20 menu turns at most. At the next menu, the call goes to your on_limit node. If there is no on_limit, the call ends.

Rules that Wave checks when you save

Wave rejects a graph with a 400 and names the field that is wrong (for example definition.nodes.sales.options.0.next) when:

start or on_limit is not a node, or a next points to a node that does not exist.
A node cannot be reached from start. (Nodes that only on_limit reaches are permitted.)
The graph has more than 50 nodes, or a menu has more than 12 options or the same digit two times.
A loop does not go through a menu node. (The call would never stop.)
The on_limit path can reach a menu node.
A dial target is not a KSA number, or an audio_ref (in a play node, a menu prompt or moh) is not a file that your org uploaded.

`call.input` for a graph

Wave sends one call.input webhook each time the caller answers a menu node — also for no input and for a wrong key. data has the digits, the option’s input, and node (the id of the menu node). When the call gets to the 20-turn limit, data also has "limit_reached": true.

{
  "event": "call.input",
  "data": { "call_id": "…", "digits": "1", "team": "sales", "node": "main" }
}

After a dial or enqueue node, the call ends. Wave does not send another call.input for it.

Audio prompts

A play prompt or action plays a pre-recorded file instead of TTS — good for a produced greeting, and it sidesteps synthesis latency. Upload the file first, then reference the returned audio_ref. POST /v1/callflows/audio takes a base64-encoded WAV file (8 kHz mono 16-bit PCM recommended — telephony quality) and returns a Wave-hosted audio_ref:

curl -X POST https://api.wave.sa/v1/callflows/audio \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "base64": "<base64-wav>", "content_type": "audio/wav", "file_name": "welcome.wav" }'

const res = await fetch("https://api.wave.sa/v1/callflows/audio", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    base64: "<base64-wav>",
    content_type: "audio/wav",
    file_name: "welcome.wav",
  }),
});
console.log(await res.json());

import os

import requests

res = requests.post(
    "https://api.wave.sa/v1/callflows/audio",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
    json={
        "base64": "<base64-wav>",
        "content_type": "audio/wav",
        "file_name": "welcome.wav",
    },
)
print(res.json())

{ "audio_ref": "https://<bucket>.<region>.aliyuncs.com/prompts/<org>/<id>.wav" }

Use the audio_ref in a play:

{ "prompt": { "play": { "audio_ref": "https://…/prompts/<org>/<id>.wav" } } }

Audio upload is rolling out. Until it’s enabled for your account, the upload returns 503 and menus use say (TTS) prompts. An audio_ref must be a file you uploaded — arbitrary URLs are rejected.

Next steps

WaveML — the verbs a menu compiles to, and full custom flows.
Webhooks — receive and verify call.input.
Queues — where an enqueue branch sends the caller.

Get Started

Voice

Web Callback

WhatsApp

Reference

Authentication & tiers

The menu definition

Prompt and actions

Branch input (your webhook payload)

Create a menu

List and fetch menus

Versioning and rollback

Bind a number

Retire a menu

The `call.input` webhook

Multi-level menus (graph)

Example: two levels, “press 9 for the main menu”

Nodes

No input, wrong key, and the loop limit

Rules that Wave checks when you save

`call.input` for a graph

Audio prompts

Next steps

​Authentication & tiers

​The menu definition

​Prompt and actions

​Branch input (your webhook payload)

​Create a menu

​List and fetch menus

​Versioning and rollback

​Bind a number

​Retire a menu

​The call.input webhook

​Multi-level menus (graph)

​Example: two levels, “press 9 for the main menu”

​Nodes

​No input, wrong key, and the loop limit

​Rules that Wave checks when you save

​call.input for a graph

​Audio prompts

​Next steps

Authentication & tiers

The menu definition

Prompt and actions

Branch input (your webhook payload)

Create a menu

List and fetch menus

Versioning and rollback

Bind a number

Retire a menu

The `call.input` webhook

Multi-level menus (graph)

Example: two levels, “press 9 for the main menu”

Nodes

No input, wrong key, and the loop limit

Rules that Wave checks when you save

`call.input` for a graph

Audio prompts

Next steps