sip.js

library0.21.2jsnpmunverified

SIP.js is a comprehensive JavaScript library designed for building real-time communication applications using SIP (Session Initiation Protocol) over WebSockets, with deep integration for WebRTC. It enables peer-to-peer audio and video sessions, instant messaging, presence, and DTMF signaling. The current stable version is 0.21.2. The project maintains an active release cadence with regular minor and patch updates, often introducing new features and addressing bugs. Key differentiators include its TypeScript-first development, compatibility with standard SIP servers like Asterisk and FreeSWITCH, and support for all major web browsers and Node.js environments. It offers both a simplified `SimpleUser` API for common use cases and a full API framework for more granular control over SIP sessions.

http-networking communication

npm install sip.js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIP.JS

sip.js

http-networkingjavascriptv0.21.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Web.SimpleUser

✓ import { Web } from 'sip.js'; const simpleUser = new Web.SimpleUser(server, options);

✗ import { SimpleUser } from 'sip.js'; // SimpleUser is nested under Web const SimpleUser = require('sip.js').Web.SimpleUser; // CommonJS is deprecated since v0.21.0

The `SimpleUser` class is primarily intended for browser environments and is exported within the `Web` namespace. CommonJS `require()` syntax is not officially supported since v0.21.0 due to ESM migration.

UserAgent

✓ import { UserAgent } from 'sip.js'; const userAgent = new UserAgent(options);

✗ const UserAgent = require('sip.js').UserAgent; // CommonJS is deprecated since v0.21.0

The core `UserAgent` class is a top-level named export. Since v0.21.0, `sip.js` is an ECMAScript module (ESM) only, requiring `import` syntax.

SessionState

✓ import { SessionState } from 'sip.js'; // ... switch (newState) { case SessionState.Established: ... }

✗ import { SessionState } from 'sip.js/lib/api/session-state'; // Incorrect deep import path const SessionState = require('sip.js').SessionState; // CommonJS is deprecated since v0.21.0

`SessionState` is an enum and a named export from the main package. Deep imports may break with future internal refactorings. ESM-only since v0.21.0.

This quickstart demonstrates how to establish a basic audio-only SIP call using the `SimpleUser` API, connecting to a WebSocket server, and handling call initiation with basic error logging.

import { Web } from "sip.js"; // Helper function to get an HTML audio element function getAudioElement(id: string): HTMLAudioElement { const el = document.getElementById(id); if (!(el instanceof HTMLAudioElement)) { throw new Error(`Element "${id}" not found or not an audio element.`); } return el; } // Options for SimpleUser const options: Web.SimpleUserOptions = { aor: "sip:alice@example.com", // caller media: { constraints: { audio: true, video: false }, // audio only call remote: { audio: getAudioElement("remoteAudio") } } }; // WebSocket server to connect with const server = "wss://sip.example.com"; // Construct a SimpleUser instance const simpleUser = new Web.SimpleUser(server, options); // Connect to server and place call simpleUser.connect() .then(() => simpleUser.call("sip:bob@example.com")) .catch((error: Error) => { console.error("Call failed:", error); // Handle call failure });

Debug

Known issues

breakingSIP.js v0.21.0 and later are ECMAScript Module (ESM) only. This change impacts projects using custom build processes or CommonJS `require()` syntax.

fix

Migrate all imports to ES module syntax (e.g., `import { Name } from 'sip.js';`). Update TypeScript compiler options `module` and `moduleResolution` to `NodeNext` and ensure all imports are fully specified with `.js` extensions.

affects: >=0.21.0

breakingThe `SimpleUser.register` method signature changed in v0.21.0. It is now `register(registererRegisterOptions?: RegistererRegisterOptions): Promise<void>;`. Any `RegistererOptions` previously passed as the first parameter to `register` must now be provided to the `SimpleUser` constructor.

fix

Update calls to `simpleUser.register()` to match the new signature. If options are needed, pass them via the `registererOptions` property in the `SimpleUser` constructor: `const simpleUser = new Web.SimpleUser(server, { registererOptions: { expires: 1800 } });`.

affects: >=0.21.0

breakingIn v0.19.0, the Web Session Description Handler (SDH) and `SimpleUser` hold implementation were updated to be RFC 8829 compliant. Users who extended the previous `Web SessionDescriptionHandler` may experience issues.

fix

Review and adapt custom Session Description Handlers to conform to the new RFC 8829 compliant implementation. Existing workarounds for previous non-compliant behavior may need to be removed or adjusted.

affects: >=0.19.0

breakingThe `hackWssInTransport` UserAgent parameter was removed in v0.18.0.

fix

Replace `hackWssInTransport: true` in `UserAgentOptions` with `contactParams: { transport: "wss" }`.

affects: >=0.18.0

gotchaIn v0.17.0, the Session Description Handler (SDH) was reworked. While not a breaking change for most, users who extended the old default SDH directly will find it in a new location and should copy its functionality into their own source if they wish to continue using it.

fix

If your application extended the default Session Description Handler, manually copy the old default SDH source code into your project to ensure continued functionality.

affects: >=0.17.0

Errors

Common errors & fixes

TypeError: require is not a function

Attempting to use CommonJS `require()` syntax to import `sip.js` after the library transitioned to ESM-only in v0.21.0.

fix

Update all `require()` statements to ES module `import` syntax, e.g., `import { UserAgent } from 'sip.js';`

Argument of type 'RegistererOptions' is not assignable to parameter of type 'RegistererRegisterOptions | undefined'.

The `register` method of `SimpleUser` changed its signature in v0.21.0, and options are now passed differently.

fix

Pass `RegistererRegisterOptions` via the `registererOptions` property in the `SimpleUser` constructor instead of directly to the `register()` method.

Property 'hackWssInTransport' does not exist on type 'UserAgentOptions'.

Using the `hackWssInTransport` option in `UserAgentOptions` after its removal in v0.18.0.

fix

Remove `hackWssInTransport` from `UserAgentOptions` and use `contactParams: { transport: "wss" }` instead.

Upgrade

Version history

0.21.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/onsip/SIP.js ↗

packagehttps://www.npmjs.com/package/sip.js ↗

homepagehttps://sipjs.com ↗