> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Vobiz WebRTC SDK (vobiz-webrtc-sdk)

> Add browser calling to your web app with the Vobiz WebRTC SDK: log in with a SIP endpoint or an access token, make and receive calls, and use mute, DTMF, and hold/resume.

The Vobiz WebRTC SDK turns a browser tab into a phone. It registers with Vobiz over a secure WebSocket, places and receives calls, and gives you in-call controls: mute, DTMF, and hold/resume.

**Source code:** [vobiz-ai/vobiz-browser-sdk](https://github.com/vobiz-ai/vobiz-browser-sdk)

## Resources

* **npm package:** [vobiz-webrtc-sdk](https://www.npmjs.com/package/vobiz-webrtc-sdk)
* **Starter kit:** [vobiz-ai/Vobiz-RTC-demo](https://github.com/vobiz-ai/Vobiz-RTC-demo) - a Node.js answer-URL backend and a browser softphone built on the SDK
* **Try it without code:** [WebRTC Playground](https://www.vobiz.ai/docs/integrations/webrtc-application-setup.md)
* **SIP library:** [vobiz-ai/vobiz-jssip](https://github.com/vobiz-ai/vobiz-jssip) ([npm](https://www.npmjs.com/package/vobiz-jssip)), bundled into the SDK
* **Release notes:** [CHANGELOG.md](https://github.com/vobiz-ai/vobiz-browser-sdk/blob/main/CHANGELOG.md)

> [!NOTE]
>
> Use **1.0.6 or later**. In 1.0.5, `hold()` could drop an incoming call, and on outbound calls audio kept flowing while the call showed as held. See [Upgrade notes](#upgrade-notes).

## Installation

```bash theme={null}
npm install vobiz-webrtc-sdk
```

Import it with `import Vobiz from 'vobiz-webrtc-sdk'` and create a client with `new Vobiz(options).client`. Add an `<audio id="remoteAudio" autoplay>` element to your page; the SDK plays the other party's audio through it. TypeScript declarations are included.

## Log in

Use one login method per user:

| Method | Call | Credentials |
| - | - | - |
| SIP endpoint | `client.login(username, password)` | The `username` and `password` of a [SIP endpoint](https://www.vobiz.ai/docs/platform/voice/endpoints.md) with an application attached. Not your account Auth ID and Auth Token. |
| Access token | `client.loginWithAccessToken(token)` | A short-lived token your backend mints for the user. The token's application handles the user's outbound calls. |

`onLogin` fires once the browser is registered, and `client.isRegistered()` then returns `true`. A wrong password fires `onLoginFailed`. Never put your account Auth Token in the browser.

## Make and receive calls

**Outbound.** `client.call(number, extraHeaders)` dials a number in E.164 format. Vobiz then requests the answer URL of the user's application, which decides where the call goes, usually with [`<Dial>`](https://www.vobiz.ai/docs/xml/dial):

* To reach a phone, set `callerId` on `<Dial>` to a number your account owns. Without a valid caller ID the call fails and the browser receives `onCallFailed`.
* To reach another browser user, dial a Vobiz number whose application rings that user with `<Dial><User>sip:USERNAME@registrar.vobiz.ai</User></Dial>`. Dialing another user's SIP address directly from the SDK is rejected.

**Incoming.** A call rings the browser when an application `<Dial>`s the user, or when you place a call to `sip:USERNAME@registrar.vobiz.ai` with the [Voice API](https://www.vobiz.ai/docs/call/overview.md). The SDK fires `onIncomingCall`. Answer with `client.answer(callUUID)`, decline with `client.reject(callUUID)`, or stop ringing locally with `client.ignore(callUUID)`. `client.getIncomingCalls()` lists ringing calls; when two ring at once, `client.answer(callUUID, 'reject')` answers one and rejects the other.

## In-call controls

| Method | What it does |
| - | - |
| `client.mute()` / `client.unmute()` | Stop or resume sending your microphone. |
| `client.sendDtmf(digit)` | Send a DTMF digit: `0`-`9`, `*`, or `#`. |
| `client.hold()` / `client.unhold()` | Put the call on hold or resume it. See [Hold and resume](#hold-and-resume). |
| `client.isOnHold()` | `true` while this client has the call on hold. |
| `client.hangup()` | End the active call. Both sides receive `onCallTerminated`. |
| `client.getCallUUID()` | The active call's UUID, or `null`. |
| `client.logout()` | Unregister the browser. `onLogout` fires when it completes. |

## Hold and resume

Available from **1.0.6**, on incoming and outbound calls, with either login method.

* `hold()` and `unhold()` return `true` when the request is sent. They return `false` when there is no answered call, or while another hold or resume is still in progress. `hold()` on a call that is already held returns `true` and sends nothing.
* `onCallHold` and `onCallResume` fire once Vobiz confirms the change. Update your UI on these events, not on the return value.
* While the call is on hold, the SDK stops sending your microphone and you stop receiving the other party's audio.
* On resume, the microphone comes back on unless you muted the call with `mute()`. Calling `unmute()` while on hold takes effect when the call resumes.

## Events

| Event | Fires when |
| - | - |
| `onLogin` / `onLoginFailed` | Registration succeeds or fails. |
| `onLogout` | `logout()` completes. |
| `onCalling` | An outbound call starts. |
| `onCallRemoteRinging` | The destination is ringing. |
| `onIncomingCall` | A call rings this browser. Arguments: caller ID, SIP headers, call info (with `callUUID`), caller name. |
| `onIncomingCallCanceled` | The caller hangs up before you answer. |
| `onIncomingCallIgnored` | You called `ignore()`. |
| `onCallAnswered` | The call is answered. |
| `onMediaConnected` | Audio is flowing. |
| `onCallHold` / `onCallResume` | Hold or resume is confirmed. |
| `onCallFailed` | The call cannot connect: rejected, invalid number, no caller ID, and so on. |
| `onCallTerminated` | The call ends, from either side. |

## Upgrade notes

Run `npm install vobiz-webrtc-sdk@latest`. No code changes are needed.

**1.0.6** fixes hold and resume. In 1.0.5, `hold()` on an incoming call dropped the call without `onCallTerminated`, after which `unhold()` and `hangup()` did nothing; on outbound calls the hold events fired but audio kept flowing. 1.0.6 also mutes the microphone while the call is on hold.

## Next steps

* [Try the WebRTC Playground](https://www.vobiz.ai/docs/integrations/webrtc-application-setup.md)
* [Create SIP endpoints](https://www.vobiz.ai/docs/platform/voice/endpoints.md)
* [Route calls with `<Dial>`](https://www.vobiz.ai/docs/xml/dial)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.