Web Calling (WebRTC)

The Calling SDK lets your web app make and receive real voice calls in the browser over WebRTC — no plugins. You embed one script, give it an API key, and call connect() then initCall(). Wave handles the SIP registration, the media, and the short-lived session credentials for you.

Web Calling uses the webrtc:write scope. In sandbox, calls are origin-locked and destination-locked to your signup number; a production key (sk_live_) removes the destination lock.

Install

npm install @wave-sa/calling-sdk

<script src="https://unpkg.com/@wave-sa/calling-sdk"></script>
<!-- exposes the global `Wave.SDK` -->

Before you start

Allow your origin. In the Wave dashboard, add the origin your app runs on (e.g. https://app.example.com) to your project’s allowed origins. The SDK fetches its session from /v1/webrtc/config, which rejects any origin that isn’t on the list.
Use a webrtc:write key. The key is sent from the browser, so it’s origin-locked by design.

A key embedded in a browser is visible to anyone who loads your page. Wave origin-locks it (and destination-locks it in sandbox) to contain the blast radius — but for production, treat the embedded key as public and scope it to webrtc:write only.

Quickstart

import { WaveSDK } from "@wave-sa/calling-sdk";

const sdk = new WaveSDK(
  { apiKey: "sk_live_xxxxxxxxxxxx", apiUrl: "https://api.wave.sa/v1" },
  {
    onConnected: () => console.log("registered — ready to call"),
    onCallProgress: () => console.log("ringing…"),
    onCallConnected: () => console.log("in call"),
    onCallEnded: () => console.log("call ended"),
    onFailed: (err) => console.error(err.code, err.message),
  },
);

await sdk.connect();              // fetch session, open WebSocket, SIP REGISTER
await sdk.initCall("+966500000000"); // dial
// … later
await sdk.endCall();
sdk.disconnect();

Agent sessions and caller sessions

Each browser session is one of two kinds. The identity option selects the kind.

Kind	How to open it	What it can do
Agent session	Set `identity` (for example `"1001"`).	Makes calls and receives calls. The browser registers as that identity, so a queue agent login or a callflow `<Dial>` with the same name rings it.
Caller session	Leave `identity` out.	Makes calls only. Use it for a website visitor who calls your business. Wave gives the session a temporary SIP user and deletes it when the session ends.

Identity rules

1–64 characters from A–Z a–z 0–9 . _ -.
Use the same identity everywhere: in the SDK, in POST /v1/queues/agents/login, and in a callflow <Dial>.
The prefixes p_ (portal members) and c_ (caller sessions) are reserved. An identity with these prefixes gets 400 INVALID_IDENTITY.
If your tenant already has a SIP user with that name that Wave did not create (for example a desk phone), Wave does not change it and returns 409 IDENTITY_CONFLICT. Use a different identity.
Wave creates the SIP user on first use and sets a new password for each session. You never manage SIP users.
One session for each identity. If the same identity opens a second session (for example a second tab), the newest session wins. The older session gets onSessionEnded("revoked") at its next credential refresh and stops ringing.
Agent sessions need a production key (sk_live_). A sandbox key ignores identity and opens a caller session.

Receive calls

Set identity and add an onIncomingCall handler. The handler gets a call object:

Field	Meaning
`from`	The caller (a phone number such as `+9665…`, or another identity).
`callSid`	The Wave call id.
`accept()`	Gets the microphone, then answers. The usual call events follow (`onCallConnected`, `onCallEnded`, …).
`reject()`	Declines the call (SIP `486 Busy Here`).

const sdk = new WaveSDK(
  { apiKey: "sk_live_xxxxxxxxxxxx", identity: "1001" },
  {
    onIncomingCall: (call) => {
      showRinging(call.from);
      acceptButton.onclick = () => call.accept();
      rejectButton.onclick = () => call.reject();
    },
    onIncomingCallCancelled: () => hideRinging(), // the caller hung up first
    onCallConnected: () => console.log("in call"),
  },
);
await sdk.connect();

One call at a time. While a call is active or ringing, a new incoming call gets 486 Busy Here. It does not reach onIncomingCall.
If the caller hangs up before you accept or reject, onIncomingCallCancelled() fires. After that, accept() and reject() on that call object throw NO_ACTIVE_CALL.
If the microphone is denied, accept() throws MICROPHONE_UNAVAILABLE and the call continues to ring. You can then call reject().
If you set onIncomingCall without identity, the constructor throws INCOMING_REQUIRES_IDENTITY.

Call quality

While a call is connected and not on hold, the SDK sends onQualityReport(metrics) every 5 seconds. Each report covers the last 5 seconds:

Field	Meaning
`mos`	Estimated Mean Opinion Score, 1–4.5. Calculated in the browser with the ITU-T G.107 E-model from the values below. It is an estimate, not a measured score.
`jitter`	Jitter of the received audio, in ms.
`packetLoss`	Received audio packets lost in the interval, in %.
`roundTripTime`	Network round-trip time, in ms.
`timestamp`	Time of the report (ms since the epoch).

Reports stop when the call ends or is put on hold, and start again when you resume the call. As a guide: mos of 4.0 or more is good, 3.6–4.0 is fair, and less than 3.6 is poor. The quality values stay in the browser; Wave does not receive them.

Configuration

new WaveSDK(config, events)

Option	Type	Notes
`apiKey`	string	Required. Your `sk_sandbox_` / `sk_live_` key.
`destination`	string	Optional default number for `initCall()`.
`locale`	`"en"` \| `"ar"`	Prompt/UX locale. Default `"en"`.
`apiUrl`	string	API base. Default `https://api.wave.sa/v1`.
`identity`	string	Optional. Opens an agent session that can receive calls. See the identity rules above.

Methods

Method	What it does
`connect()`	Fetches the session, opens the signaling socket, registers. Fires `onConnected` when ready.
`initCall(destination?)`	Acquires the mic and dials. Returns `{ callSid, status: "initiated" }`.
`endCall()`	Hangs up the active call.
`muteCall()` / `unmuteCall()`	Mute or restore your microphone.
`holdCall()` / `resumeCall()`	Place the call on hold or resume it.
`sendDTMF(tones, transportType?)`	Send keypad tones (`0–9 * # A–D`). Defaults to RFC 2833; pass `"INFO"` for SIP INFO.
`disconnect()`	Tear everything down and release the mic.
`isMuted`	Current mute state (getter).

Events

Pass handlers in the second argument to the constructor.

Event	Fires when
`onConnecting()`	The signaling channel is opening.
`onConnected()`	Registered — ready to place a call.
`onCallProgress()`	The far end is ringing (early media).
`onCallConnected()`	The call was answered and media is flowing.
`onCallEnded()`	You ended the call with `endCall()`.
`onCallDisconnected(reason)`	The call dropped — `reason` is `NETWORK_ERROR`, `TIMEOUT`, `SERVER_ERROR`, or `REMOTE_HANGUP`.
`onMuteStateChange(isMuted)`	After `muteCall()` / `unmuteCall()`.
`onHold()` / `onResumed()`	The call was held / resumed.
`onFailed(error)`	Setup or registration failed — see error codes below.
`onTokenWillExpire()`	~60s before the session credential expires (informational).
`onSessionRefreshed()`	The session credential rotated successfully.
`onSessionEnded(reason)`	The session ended at Wave (`auth_failure` or `revoked`). `revoked` includes a newer session for the same identity.
`onIncomingCall(call)`	A call rings this agent session. Needs `identity`.
`onIncomingCallCancelled()`	The caller hung up before you accepted or rejected.
`onQualityReport(metrics)`	Every 5 s during a connected call: estimated MOS, jitter, packet loss, round-trip time.

You never handle the SIP password or session token yourself. The SDK fetches them, keeps the call alive, and auto-rotates the credential about a minute before it expires.

Error codes

onFailed(error) gives you an error.code:

Code	Meaning
`INVALID_API_KEY_FORMAT`	The `apiKey` isn’t a recognized Wave key.
`UNSUPPORTED_BROWSER`	No WebRTC support.
`MICROPHONE_UNAVAILABLE`	Mic permission denied or no input device.
`CONFIG_FAILED`	Couldn’t fetch the session — often the origin isn’t allowed.
`AUTH_FAILURE`	The key was rejected.
`REGISTRATION_FAILED`	SIP registration failed.
`TURN_UNAVAILABLE`	No media relay available on a restrictive network.
`CALL_ALREADY_ACTIVE` / `NO_ACTIVE_CALL`	Call-state misuse.
`NOT_CONNECTED`	`initCall()` before `connect()` finished.
`CALL_FAILED`	The call couldn’t be set up.
`INCOMING_REQUIRES_IDENTITY`	Thrown by the constructor: `onIncomingCall` is set, but `identity` is not.

The session request (POST /v1/webrtc/config) can also fail with these API errors. The SDK reports them as CONFIG_FAILED, with the HTTP status in the message:

API error	Status	Meaning
`INVALID_IDENTITY`	400	The identity breaks the rules above (characters, length, or a reserved prefix).
`IDENTITY_CONFLICT`	409	Your tenant has a SIP user with that name that Wave did not create. Wave did not change it.
`WEBRTC_PROVISIONING_FAILED`	502	Wave could not prepare the SIP user. Try again.

Webhooks

When a browser call ends, Wave sends the usual call.ended webhook for it (see Webhooks).

Get Started

Voice

Web Callback

WhatsApp

Reference

Web Calling (WebRTC)

Install

Before you start

Quickstart

Agent sessions and caller sessions

Receive calls

Call quality

Configuration

Methods

Events

Error codes

Webhooks

Next steps

How voice works

Calls & recordings

​Install

​Before you start

​Quickstart

​Agent sessions and caller sessions

​Receive calls

​Call quality

​Configuration

​Methods

​Events

​Error codes

​Webhooks

​Next steps

How voice works

Calls & recordings

Install

Before you start

Quickstart

Agent sessions and caller sessions

Receive calls

Call quality

Configuration

Methods

Events

Error codes

Webhooks

Next steps