Calls & recordings

Two ways to place a call

	`POST /v1/callback`	`POST /v1/calls`
Product	Web Callback	Programmable calling
Idea	”Call this customer back” — often widget- or queue-driven (`from_queue`)	“Place this call now”
Sandbox	Supports the `x-wave-simulate` header + test numbers	Real calls only

Both originate from your number and, in sandbox, are locked to your signup number. A production key removes that lock.

curl -X POST https://api.wave.sa/v1/calls \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+966500000000", "caller_id_name": "Acme" }'

{
  "call_id": "27d6dd39-…",
  "status": "initiated",
  "direction": "outbound",
  "to": "+966 50 XXX 0000",
  "from": "+966115209300",
  "sandbox": false,
  "created_at": "2026-08-19T10:00:00.000Z"
}

Read the call log

GET /v1/calls returns your calls newest-first with cursor pagination. Needs the calls:read scope.

curl "https://api.wave.sa/v1/calls?limit=20" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

{
  "data": [
    {
      "id": "27d6dd39-…",
      "type": "outbound",
      "status": "ended",
      "from": "+966115209300",
      "to_masked": "+966 50 XXX 0000",
      "duration_seconds": 42,
      "created_at": "2026-08-19T10:00:00.000Z",
      "answered_at": "2026-08-19T10:00:05.000Z",
      "ended_at": "2026-08-19T10:00:47.000Z"
    }
  ],
  "next_cursor": "eyJ…",
  "limit": 20
}

Pass next_cursor back as ?cursor= to page. Destination numbers are masked.

Fetch a recording

GET /v1/calls/{call_id}/recording returns a time-limited download URL (valid ~60 minutes). Needs the recordings:read scope and a production key.

curl https://api.wave.sa/v1/calls/27d6dd39-…/recording \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

{
  "call_id": "27d6dd39-…",
  "url": "https://oss.example.com/…?signature=…",
  "expires_at": "2026-08-19T11:00:00.000Z"
}

A recording exists only if the call was recorded (via a <Dial record> or a background <Record>) and storage is provisioned for your account. Until then this returns 404 RECORDING_NOT_FOUND or 503 RECORDING_SERVICE_UNAVAILABLE. Sandbox keys get 400 SANDBOX_KEY_NOT_ALLOWED.

Control a live call

Change a call while it is live: POST /v1/calls/{call_id}/{action}, where action is hangup, hold, unhold, mute, unmute, dtmf ({"digits"}), play ({"url"}, a public https URL), recording/start or recording/stop. Needs the calls:write scope. A 200 means the voice engine accepted the command.

Works on calls Wave placed (callbacks and outbound calls) and on inbound calls to your numbers. Web-calling calls return 409 CALL_NOT_CONTROLLABLE (the SDK controls the browser’s own leg).
hangup works from initiated; every other action needs an answered call.
The optional body field leg picks the leg: "customer" (default) or "agent", the agent connected now by a <Dial> or a queue. With no connected agent you get 409 AGENT_LEG_NOT_CONNECTED. The response tells you the leg.

curl -X POST https://api.wave.sa/v1/calls/27d6dd39-…/mute \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"leg": "agent"}'

{
  "call_id": "27d6dd39-…",
  "action": "mute",
  "leg": "agent",
  "status": "answered",
  "request_id": "req-…"
}

In-call control is turned on per environment, and the agent leg and the recording routes each have their own switch. While a switch is off, the route returns 503 CALL_CONTROL_DISABLED.

Transfer a live call

Send the caller somewhere else: POST /v1/calls/{call_id}/transfer with a target. This is a blind transfer: the caller’s leg goes straight to the target, with no announcement to the target first. Do not depend on the current agent leg staying connected after the transfer. Needs the calls:write scope.

`target.type`	`target.value`
`number`	A KSA phone number. The caller-ID is your Wave number on this call (the number the caller dialled, or the number Wave called from).
`user`	A web-calling identity of your organization.
`queue`	A queue of your organization (letters, digits, `-` and `_`).

A target that has a bad format or is not your organization’s returns 422 TRANSFER_TARGET_INVALID. The call must be answered, and only one transfer can be in progress on a call (409 TRANSFER_IN_PROGRESS).

curl -X POST https://api.wave.sa/v1/calls/27d6dd39-…/transfer \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"target": {"type": "queue", "value": "sales"}}'

{
  "call_id": "27d6dd39-…",
  "transfer_id": "8f1c…",
  "action": "transfer",
  "status": "requested",
  "request_id": "req-…"
}

Wave answers 202 at once. When the transfer has a result, Wave sends one call.transferred webhook with an outcome: answered, no_answer, busy, failed, cancelled, enqueued (queue target) or expired (the voice engine did not act on it). If the target does not answer, the call ends. Read a call’s transfers and their outcomes with GET /v1/calls/{call_id}/transfers (calls:read scope). On a simulated sandbox call, the transfer completes at once with outcome answered, and the webhook is marked simulated.

Call transfer has its own switch per environment, and it is not available in production yet. While it is off, the route returns 503 CALL_CONTROL_DISABLED.

Get Started

Voice

Web Callback

WhatsApp

Reference

Calls & recordings

Two ways to place a call

Read the call log

Fetch a recording

Control a live call

Transfer a live call

Next steps

Web Calling

Webhooks

​Two ways to place a call

​Read the call log

​Fetch a recording

​Control a live call

​Transfer a live call

​Next steps

Web Calling

Webhooks

Two ways to place a call

Read the call log

Fetch a recording

Control a live call

Transfer a live call

Next steps