JsSIP

Common errors

• WebSocket connection to 'wss://...' failed: WebSocket is closed before the connection is established.

  cause This error frequently indicates issues with the SIP WebSocket server's SSL/TLS certificate (if using WSS), the server being unreachable, or a misconfigured WebSocket endpoint.
  fix Inspect your browser's developer console for more specific WebSocket errors. Verify your SIP server's SSL/TLS certificate is valid and trusted. Confirm the WebSocket server is running and accessible on the specified URL and port, and that firewalls are not blocking the connection.

• NotAllowedError: Permission denied by system

  cause The user's browser or operating system has blocked access to the microphone or camera, which is required for the call's `mediaConstraints`.
  fix Guide the user to grant media permissions. Advise them to check their browser's site settings (e.g., camera and microphone permissions) and operating system privacy settings. Consider providing a UI element to trigger the permission prompt again.

• TypeError: Cannot read properties of undefined (reading 'call')

  cause `ua` (User Agent) instance might not be properly initialized or `ua.start()` has not completed successfully before attempting to make a call.
  fix Ensure the `UA` instance is correctly configured and `ua.start()` is called and has had time to establish its connection before `ua.call()` is invoked. Check for errors during `ua.start()` and related event handlers (`registered`, `unregistered`, `registrationFailed`).

• Error: Invalid URI 'sip:user@domain.com'

  cause The provided SIP URI format for calling or configuring the User Agent is incorrect or malformed according to SIP URI specifications.
  fix Review the SIP URI string (`sip:bob@example.com` in the quickstart) to ensure it adheres to the correct SIP URI syntax (e.g., `sip:user@host` or `sips:user@host`). Avoid common typos or missing components.

Warnings

• breaking In JsSIP 0.3.x, HTML5 video elements are no longer directly handled by JsSIP. Developers must now use media stream handling tools to decide when and where to attach local and remote media streams, offering more control but requiring manual DOM manipulation for media elements.
  Fix: Migrate your media handling logic to explicitly manage `MediaStream` objects obtained from `RTCSession` events and attach them to `<video>` or `<audio>` elements in the DOM. Consult `JsSIP.RTCSession` documentation for details.
• gotcha When using secure WebSocket (WSS) connections for SIP signaling, the server must present a valid, publicly trusted SSL/TLS certificate. Browsers will reject connections to servers with self-signed, expired, or untrusted certificates, leading to `WebSocket connection failed` errors in the console.
  Fix: Ensure your SIP over WebSocket server is configured with a publicly trusted SSL/TLS certificate from a recognized Certificate Authority (CA) for production. For development, you may need to explicitly trust self-signed certificates in your browser or OS, or temporarily use non-secure `ws://` if appropriate.
• gotcha Browsers require explicit user consent to access the microphone and camera. If a user denies these permissions, JsSIP calls configured with `mediaConstraints` will fail with a `NotAllowedError` or `Permission denied` DOMException, preventing media capture.
  Fix: Implement robust UI/UX to proactively prompt users for media permissions. Gracefully handle permission denials by informing the user and guiding them on how to grant permissions via browser or operating system settings. Always check `navigator.mediaDevices.getUserMedia` promises for rejection.
• gotcha JsSIP relies on a SIP server correctly configured to support SIP over WebSocket (RFC 7118). Common misconfigurations include incorrect WebSocket path, missing TLS setup for WSS, or firewall blocks, which will prevent the JsSIP `UA` from establishing a connection.
  Fix: Verify that your SIP server (e.g., Kamailio, Asterisk, Mobicents) has a WebSocket listener enabled and properly configured for the correct path and port, with TLS/SSL correctly set up if using WSS. Check server logs and network activity in browser developer tools for connection errors.
• breaking JsSIP versions prior to 3.2.17 might use deprecated `MediaStream` API methods for WebRTC. Modern browser versions have transitioned to `MediaStreamTrack` APIs. While `webrtc-adapter` can help, directly supporting `MediaStreamTrack` is essential for compatibility.
  Fix: Upgrade to JsSIP 3.2.17 or later, which includes changes to switch to `MediaStreamTrack` from the deprecated `MediaStream` API. If using older versions, ensure `webrtc-adapter` is properly included and up-to-date in your application.

Install

• npm install jssip npm
• yarn add jssip yarn
• pnpm add jssip pnpm

Imports

• JsSIP
  wrong:

  const JsSIP = require('jssip');

  correct:

  import * as JsSIP from 'jssip';

  While CommonJS `require` works for the UMD bundle, modern applications and TypeScript projects should prefer the ESM named or namespace imports. JsSIP ships both CJS and ESM bundles.
• UA
  wrong:

  import UA from 'jssip';

  correct:

  import { UA } from 'jssip';

  UA is a named export, not the default export. Accessing it via the global `JsSIP.UA` is also common when JsSIP is loaded as a script without a module bundler.
• WebSocketInterface
  wrong:

  import { WSI } from 'jssip';

  correct:

  import { WebSocketInterface } from 'jssip';

  The class is specifically named `WebSocketInterface`. Ensure correct capitalization and the full name.

Quickstart

This quickstart demonstrates how to instantiate a JsSIP User Agent, configure a WebSocket transport, register event handlers for the call lifecycle, and initiate an audio/video SIP call. It showcases the fundamental setup required for WebRTC-based communication using JsSIP in a modern JavaScript/TypeScript environment, including proper import syntax and basic error handling.

import { UA, WebSocketInterface } from 'jssip';

const socket = new WebSocketInterface('wss://sip.myhost.com');
const configuration = {
  sockets  : [ socket ],
  uri      : 'sip:alice@example.com',
  password : process.env.SIP_PASSWORD ?? 'superpassword' // Use environment variables for sensitive data.
};

const ua = new UA(configuration);

ua.start();

// Register callbacks to desired call events
const eventHandlers = {
  'progress': (e: any) => { // Type 'any' for brevity; consider defining specific event types
    console.log('Call is in progress');
  },
  'failed': (e: any) => {
    console.error('Call failed with cause: ' + e.data.cause);
  },
  'ended': (e: any) => {
    console.log('Call ended with cause: ' + e.data.cause);
  },
  'confirmed': (e: any) => {
    console.log('Call confirmed');
  }
};

const options = {
  eventHandlers,
  mediaConstraints: { 'audio': true, 'video': true }
};

const session = ua.call('sip:bob@example.com', options);

// Example: Stop UA after some time (for demonstration)
setTimeout(() => {
  console.log('Stopping User Agent...');
  ua.stop();
}, 30000);