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.
All of this runs in the sandbox. It is free, and the call rings your own verified number.
Verify your identity once. That is all the sandbox needs.
It is in your dashboard. Sandbox keys start with sk_sandbox_, live keys with sk_live_.
POST /v1/callbackPass the E.164 number to ring. Pick your language on the right.
The response says "initiated" and your phone starts ringing.
curl -X POST https://api.wave.sa/v1/callback \
-H "Authorization: Bearer sk_sandbox_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "to": "+966500000000" }'{ "call_id": "call_abc123", "status": "initiated", "sandbox": true }Trimmed response. The full shape is in the API reference.
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.
A plain-text index of every docs page. The first file your assistant should read.
The complete docs in one file, for tools that prefer to load everything at once.
Every endpoint, parameter and response in one machine-readable file. Generate types or a client from it.
docs.wave.sa/api-reference/openapi.jsonEvery docs page is also served as clean Markdown, with no layout to parse.
105 doc pages in Arabic with their own indexes, so you and your assistant can work in Arabic end to end.
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:
Sample sequence. Timings are illustrative.
Ready for production? Swap sk_sandbox_ for sk_live_ after a short review.
Calls, verifications, voicemail and messages push state to your server, signed with HMAC-SHA256 so you know it came from Wave.
X-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.
5 attempts over about 2.5 hours. Every attempt lands in the delivery log.
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.
Voice
operational
Webhooks
operational
Dashboard
operational
Sample data. Live history at status.wave.sa.
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.
Your call data stays in Saudi Arabia.
Each recording is available for 90 days after the call, with signed, time-limited download links.
Send Idempotency-Key on key routes. Retry a timeout without placing the call twice.
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.
A stable error contract in Arabic and English, and guardrails that keep a bug in a loop from becoming a phone bill.
{
"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.
Per-project keys with scopes enforced on every route. Rotate or revoke any time.
Read where you stand and back off on time.
A sudden spike in outbound calls returns CALL_VELOCITY_EXCEEDED with Retry-After, before a runaway loop dials thousands of people.
Only numbers you own can be presented as CLI. Anything else returns CLI_NOT_OWNED.
GET /v1/usage returns calls, answered, missed, minutes and estimated cost in SAR.
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
<Response>
<Gather numDigits="1">
<Say language="en">
For sales press 1, for support press 2
</Say>
</Gather>
<Enqueue strategy="round-robin">support</Enqueue>
</Response>In-app calling for iOS and Android, on the same account, numbers and events as your web app.
Connect your existing carrier or PBX to Wave and keep your setup while you add programmable call control.
A2P SMS from an alphanumeric sender ID, so messages arrive under your brand name.
One-time codes with attempt limits over WhatsApp, SMS or voice, closed out by verify.completed.
Ready-made connections where they save you time, and an open spec for everything else.
Merchants on Salla and Zid add Wave calling to their store through the app.
See the store appEnrich customer records and push conversation context into HubSpot.
Let AI assistants query your Insights data directly, with per-tenant keys.
SSO with your company identity, including on closed networks.
Import it into your API client, generate types or wire Wave into your own tooling.
Every endpoint, in Arabic and English.
docs.wave.saWhat changed, and when.
docs.wave.sa/changelogEvery verb and attribute for building call flows.
docs.wave.saAll 22 events, signing, retries and replay.
docs.wave.saStuck? Talk to our Saudi team.
Real people in the Kingdom, Sunday to Thursday, by email and WhatsApp, in Arabic or English.