Calls & recordings - Wave API

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.

Next steps

Web Calling

Place calls from the browser with the SDK.

Webhooks

Get call events pushed to you instead of polling.