Your first call in under five minutes.

Programmable Voice over REST + JSON: calls, Saudi numbers, call control, call flows and verification. One key, 80+ endpoints, 22 signed webhooks, and docs your AI tools can read.

Free sandbox. Real calls to your own verified number. Go live after a short review.

First call, four steps.

All of this runs in the sandbox. It is free, and the call rings your own verified number.

  1. 1

    Sign up with Nafath

    Verify your identity once. That is all the sandbox needs.

  2. 2

    Copy your sandbox key

    It is in your dashboard. Sandbox keys start with sk_sandbox_, live keys with sk_live_.

  3. 3

    Send POST /v1/callback

    Pass the E.164 number to ring. Pick your language on the right.

  4. 4

    Get a 202 back

    The response says "initiated" and your phone starts ringing.

POST /v1/callback
curl -X POST https://api.wave.sa/v1/callback \
  -H "Authorization: Bearer sk_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+966500000000" }'
Response202 Accepted
{ "call_id": "call_abc123", "status": "initiated", "sandbox": true }

Trimmed response. The full shape is in the API reference.

Docs your AI tools can read.

Point your coding assistant at the docs and it gets the whole API in formats it parses cleanly: plain-text indexes, Markdown per page and an OpenAPI spec.

Try this prompt

Read https://docs.wave.sa/llms.txt and add a Wave click-to-call button to my checkout page.

Your assistant reads the index, finds the right guide and drafts the integration for you to review.

Working with conversation data? The Wave Insights MCP server lets AI assistants query your Insights data directly.

llms.txt

A plain-text index of every docs page. The first file your assistant should read.

llms-full.txt

The complete docs in one file, for tools that prefer to load everything at once.

OpenAPI spec

Every endpoint, parameter and response in one machine-readable file. Generate types or a client from it.

docs.wave.sa/api-reference/openapi.json
Markdown

Every docs page is also served as clean Markdown, with no layout to parse.

Arabic indexes

105 doc pages in Arabic with their own indexes, so you and your assistant can work in Arabic end to end.

Break it in the sandbox. Not in production.

Same API, same events, free. Real calls to your own number, test numbers that fire webhooks, and failures on demand.

Pick a scenario

Real calls, free

Sandbox calls ring your own verified number, so you hear what your users will hear.

Test numbers

Dial a test number to fire simulated webhooks without calling anyone.

Errors on demand

Set X-Wave-Simulate to one of:

rate_limitinvalid_queuequeue_unavailableserver_errorinvalid_number
Call simulatoranswered
POST /v1/callback
Authorization: Bearer sk_sandbox_xxxxxxxxxxxx
  1. T+0sREQPOST /v1/callbackto: +966500000000
  2. T+0sRES202 Acceptedcall_id: call_abc123 · status: initiated
  3. T+0sEVTcall.initiatedSigned with X-Wave-Signature
  4. T+6sEVTcall.answeredYour verified number picks up
  5. T+48sEVTcall.endedThe call is over
  6. T+48sLOGCall logCDR written, number masked

Sample sequence. Timings are illustrative.

Ready for production? Swap sk_sandbox_ for sk_live_ after a short review.

See pricing

22 signed events. Retried, logged, replayable.

Calls, verifications, voicemail and messages push state to your server, signed with HMAC-SHA256 so you know it came from Wave.

call.initiatedcall.answeredcall.endedcall.missedcall.transferredcall.inputvoice_auth.completedverify.completedvoicemail.receivedconference.createdmessage.receivedmessage.deliveredand 10 more
Verify a signatureX-Wave-Signature: sha256=<hex>
import crypto from "node:crypto";

function verifyWaveSignature(rawBody, header, secret) {
  if (!header?.startsWith("sha256=")) return false;
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Constant-time comparison, against the raw body, before you parse it.

Delivery log
Sample stream
timeeventstatus

Your endpoint is down. Wave keeps trying.

5 attempts over about 2.5 hours. Every attempt lands in the delivery log.

Replay from the dashboard for 72 h

Guarantees you can put in a design doc.

Uptime, status, residency and telemetry: what you check before voice goes into a critical path.

Uptime SLA

99.9%

An uptime commitment on the Wave API, backed by a public status page and incident history.

All systems operational
status.wave.sa
Wave API90-day uptime
90 days agoToday

Voice

operational

Webhooks

operational

Dashboard

operational

Sample data. Live history at status.wave.sa.

Voice quality, every 5 seconds

The Web Calling SDK reports MOS, jitter, packet loss and RTT live, per call.

MOS

4.3

jitter

6 ms

loss

0.2 %

RTT

48 ms

Sample readout from a test call.

Data residency

Your call data stays in Saudi Arabia.

Recordings available for 90 days

Each recording is available for 90 days after the call, with signed, time-limited download links.

Idempotency keys

Send Idempotency-Key on key routes. Retry a timeout without placing the call twice.

Rate limits + burst guard

Limit headers on every response, and a call-velocity guard that stops runaway loops. Details

Request log, with a debugger. Every API request, filterable, keyed by the same request_id you get in errors.

-------------------------------------------------------------
| method | path | status | latency |
-------------------------------------------------------------
| POST | /v1/callback | 202 | 84ms |
| GET | /v1/calls | 200 | 41ms |
| POST | /v1/calls | 202 | 97ms |
| POST | /v1/callback | 429 | 6ms |
| GET | /v1/usage | 200 | 58ms |
| POST | /v1/virtual-numbers | 201 | 112ms |
| POST | /v1/calls | 429 | 5ms |
| GET | /v1/calls/{id}/recording | 200 | 73ms |

Errors you can branch on. Limits you can read.

A stable error contract in Arabic and English, and guardrails that keep a bug in a loop from becoming a phone bill.

Error envelopeArabic and English
{
  "error_code": "VALIDATION_ERROR",
  "message": "to must be a valid KSA phone number",
  "message_ar": "خطأ في التحقق من البيانات",
  "request_id": "req_abc123",
  "docs_url": "https://wave.sa/docs/errors"
}

A stable code to branch on, a message in English and Arabic for your UI, a request ID for support and a link to the fix.

Scoped API keys

Per-project keys with scopes enforced on every route. Rotate or revoke any time.

Rate-limit headers on every response

Read where you stand and back off on time.

x-ratelimit-limitx-ratelimit-remainingx-ratelimit-resetretry-after

Call-velocity guard

A sudden spike in outbound calls returns CALL_VELOCITY_EXCEEDED with Retry-After, before a runaway loop dials thousands of people.

Caller ID protection

Only numbers you own can be presented as CLI. Anything else returns CLI_NOT_OWNED.

Usage you can query

GET /v1/usage returns calls, answered, missed, minutes and estimated cost in SAR.

Building blocks, ready to paste.

All Wave APIs

Describe a call in a few lines.

WaveML gives you Play, Say, Gather, Dial, Enqueue, Record, AIAgent, Pause and Hangup, with Arabic and English TTS. This IVR asks callers to pick sales or support, then queues them round-robin.

Verbs: Play · Say · Gather · Dial · Enqueue · Record · AIAgent · Pause · Hangup

menu.xml
<Response>
  <Gather numDigits="1">
    <Say language="en">
      For sales press 1, for support press 2
    </Say>
  </Gather>
  <Enqueue strategy="round-robin">support</Enqueue>
</Response>

More ways to build

Mobile Voice SDKs

In-app calling for iOS and Android, on the same account, numbers and events as your web app.

Bring your own SIP trunk

Connect your existing carrier or PBX to Wave and keep your setup while you add programmable call control.

SMS and sender ID

A2P SMS from an alphanumeric sender ID, so messages arrive under your brand name.

Verify, any channel

One-time codes with attempt limits over WhatsApp, SMS or voice, closed out by verify.completed.

Works with the stack you already run.

Ready-made connections where they save you time, and an open spec for everything else.

Salla and Zid store app

Merchants on Salla and Zid add Wave calling to their store through the app.

See the store app
Wave Insights

HubSpot

Enrich customer records and push conversation context into HubSpot.

Wave Insights

MCP server

Let AI assistants query your Insights data directly, with per-tenant keys.

Wave Insights

Microsoft Entra ID and Active Directory

SSO with your company identity, including on closed networks.

Wave APIs

OpenAPI spec

Import it into your API client, generate types or wire Wave into your own tooling.

Your sandbox key is waiting.

Wave for developers — Programmable Voice API for Saudi Arabia