{"id":12753,"library":"sip.js","title":"SIP.js WebRTC Library","description":"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.","status":"active","version":"0.21.2","language":"javascript","source_language":"en","source_url":"https://github.com/onsip/SIP.js","tags":["javascript","sip","webrtc","library","websocket","typescript"],"install":[{"cmd":"npm install sip.js","lang":"bash","label":"npm"},{"cmd":"yarn add sip.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add sip.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { SimpleUser } from 'sip.js'; // SimpleUser is nested under Web\nconst SimpleUser = require('sip.js').Web.SimpleUser; // CommonJS is deprecated since v0.21.0","symbol":"Web.SimpleUser","correct":"import { Web } from 'sip.js';\nconst simpleUser = new Web.SimpleUser(server, options);"},{"note":"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.","wrong":"const UserAgent = require('sip.js').UserAgent; // CommonJS is deprecated since v0.21.0","symbol":"UserAgent","correct":"import { UserAgent } from 'sip.js';\nconst userAgent = new UserAgent(options);"},{"note":"`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.","wrong":"import { SessionState } from 'sip.js/lib/api/session-state'; // Incorrect deep import path\nconst SessionState = require('sip.js').SessionState; // CommonJS is deprecated since v0.21.0","symbol":"SessionState","correct":"import { SessionState } from 'sip.js';\n// ... switch (newState) { case SessionState.Established: ... }"}],"quickstart":{"code":"import { Web } from \"sip.js\";\n\n// Helper function to get an HTML audio element\nfunction getAudioElement(id: string): HTMLAudioElement {\n  const el = document.getElementById(id);\n  if (!(el instanceof HTMLAudioElement)) {\n    throw new Error(`Element \"${id}\" not found or not an audio element.`);\n  }\n  return el;\n}\n\n// Options for SimpleUser\nconst options: Web.SimpleUserOptions = {\n  aor: \"sip:alice@example.com\", // caller\n  media: {\n    constraints: { audio: true, video: false }, // audio only call\n    remote: { audio: getAudioElement(\"remoteAudio\") }\n  }\n};\n\n// WebSocket server to connect with\nconst server = \"wss://sip.example.com\";\n\n// Construct a SimpleUser instance\nconst simpleUser = new Web.SimpleUser(server, options);\n\n// Connect to server and place call\nsimpleUser.connect()\n  .then(() => simpleUser.call(\"sip:bob@example.com\"))\n  .catch((error: Error) => {\n    console.error(\"Call failed:\", error);\n    // Handle call failure\n  });","lang":"typescript","description":"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."},"warnings":[{"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.","message":"SIP.js v0.21.0 and later are ECMAScript Module (ESM) only. This change impacts projects using custom build processes or CommonJS `require()` syntax.","severity":"breaking","affected_versions":">=0.21.0"},{"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 } });`.","message":"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.","severity":"breaking","affected_versions":">=0.21.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.19.0"},{"fix":"Replace `hackWssInTransport: true` in `UserAgentOptions` with `contactParams: { transport: \"wss\" }`.","message":"The `hackWssInTransport` UserAgent parameter was removed in v0.18.0.","severity":"breaking","affected_versions":">=0.18.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.17.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update all `require()` statements to ES module `import` syntax, e.g., `import { UserAgent } from 'sip.js';`","cause":"Attempting to use CommonJS `require()` syntax to import `sip.js` after the library transitioned to ESM-only in v0.21.0.","error":"TypeError: require is not a function"},{"fix":"Pass `RegistererRegisterOptions` via the `registererOptions` property in the `SimpleUser` constructor instead of directly to the `register()` method.","cause":"The `register` method of `SimpleUser` changed its signature in v0.21.0, and options are now passed differently.","error":"Argument of type 'RegistererOptions' is not assignable to parameter of type 'RegistererRegisterOptions | undefined'."},{"fix":"Remove `hackWssInTransport` from `UserAgentOptions` and use `contactParams: { transport: \"wss\" }` instead.","cause":"Using the `hackWssInTransport` option in `UserAgentOptions` after its removal in v0.18.0.","error":"Property 'hackWssInTransport' does not exist on type 'UserAgentOptions'."}],"ecosystem":"npm"}