SIP.js WebRTC Library

Common errors

• TypeError: require is not a function

  cause 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'.

  cause 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'.

  cause Using the `hackWssInTransport` option in `UserAgentOptions` after its removal in v0.18.0.
  fix Remove `hackWssInTransport` from `UserAgentOptions` and use `contactParams: { transport: "wss" }` instead.

Warnings

• breaking SIP.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.
• breaking The `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 } });`.
• breaking In 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.
• breaking The `hackWssInTransport` UserAgent parameter was removed in v0.18.0.
  Fix: Replace `hackWssInTransport: true` in `UserAgentOptions` with `contactParams: { transport: "wss" }`.
• gotcha In 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.

Install

• npm install sip.js npm
• yarn add sip.js yarn
• pnpm add sip.js pnpm

Imports

• Web.SimpleUser
  wrong:

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

  correct:

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

  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
  wrong:

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

  correct:

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

  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
  wrong:

  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

  correct:

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

  `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.

Quickstart

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
  });