Technical Reference

$
npm install @signalwire/js

The SignalWire Browser SDK is a JavaScript library that enables WebRTC-based voice, video, and chat applications directly in web browsers. Built on WebSocket architecture, it provides real-time communication capabilities without plugins or downloads.

$
npm install @signalwire/js

1
<script src="https://cdn.signalwire.com/@signalwire/js"></script>

1
// Server-side: Get a Video Room token
2
// Replace <YOUR_SPACE>, <username>, and <password> with your actual values
3
const response = await fetch('https://<YOUR_SPACE>.signalwire.com/api/video/room_tokens', {
4
  method: 'POST',
5
  headers: {
6
    'Content-Type': 'application/json',
7
    'Accept': 'application/json',
8
    'Authorization': 'Basic ' + btoa('<PROJECT_ID>:<API_TOKEN>')  // Your SignalWire credentials
9
  },
10
  body: JSON.stringify({
11
    room_name: "my_room",
12
    user_name: "John Smith",
13
    permissions: [
14
      "room.self.audio_mute",
15
      "room.self.audio_unmute",
16
      "room.self.video_mute",
17
      "room.self.video_unmute",
18
      "room.self.deaf",
19
      "room.self.undeaf",
20
      "room.self.set_input_volume",
21
      "room.self.set_output_volume",
22
      "room.self.set_input_sensitivity"
23
    ],
24
    room_display_name: "My Room",
25
    join_as: "member"
26
  })
27
});
28
29
const { token } = await response.json();

1
import { Video } from "@signalwire/js";
2
3
// Join a video room
4
const roomSession = new Video.RoomSession({
5
  token: "your-room-token",  // From your server
6
  rootElement: document.getElementById("video-container")
7
});
8
9
// Listen for events
10
roomSession.on("member.joined", (e) => {
11
  console.log(`${e.member.name} joined the room`);
12
});
13
14
roomSession.on("room.joined", () => {
15
  console.log("Successfully joined the room!");
16
});
17
18
// Join the room
19
await roomSession.join();

1
<div id="video-container"></div>

Core Concepts

The SDK operates through WebSocket connections that handle both method calls and real-time events. When you call methods like join() or publish(), the SDK sends requests and returns promises. Simultaneously, you can listen for real-time events like new members joining or messages arriving using the .on() method.

Namespaces

WebSocket Event Architecture

The SDK operates on a bidirectional WebSocket connection between your browser application and SignalWire’s servers. This enables real-time communication through a structured event system:

When you call a method like roomSession.join(), the SDK sends your request over the WebSocket connection and SignalWire processes it and responds immediately. These method calls follow a request-response pattern - the returned promise resolves with the result data, such as joining a video room or publishing a message.

The .on() methods handle a different communication pattern: real-time event notifications. These are asynchronous events triggered by external actions - like when someone joins your video room (member.joined), sends you a message (message.received), or when device states change (call.state). Unlike method responses, these events arrive whenever the triggering action occurs, not as a direct response to your code.

Authentication and Access Control

Browser SDK clients use token-based authentication for security. Since web browsers are untrusted environments where secrets can be exposed, API tokens must be kept on your server and used to generate limited-scope tokens for client use.

Server-to-Browser Authentication Flow

Token Types by Namespace

Different namespaces require specific token types:

1
// Video Room Session - requires Room Token
2
const roomSession = new SignalWire.Video.RoomSession({
3
  token: "room-token-from-rest-api",        // Get from /api/video/room_tokens
4
  rootElement: document.getElementById("video-container")
5
});
6
7
// Chat Client - requires Chat Token  
8
const chatClient = new SignalWire.Chat.Client({
9
  token: "chat-token-from-rest-api"         // Get from /api/chat/tokens
10
});
11
12
// PubSub Client - requires PubSub Token
13
const pubSubClient = new SignalWire.PubSub.Client({
14
  token: "pubsub-token-from-rest-api"       // Get from /api/fabric/subscriber_tokens
15
});

Server-Side Token Generation

Your server uses Project ID and API Token to generate limited-scope tokens:

1
// Example: Generate a Video Room Token
2
const response = await fetch('https://<YOUR_SPACE>.signalwire.com/api/video/room_tokens', {
3
  method: 'POST',
4
  headers: {
5
    'Authorization': 'Basic ' + btoa('<PROJECT_ID>:<API_TOKEN>'),
6
    'Content-Type': 'application/json'
7
  },
8
  body: JSON.stringify({
9
    room_name: "my_room",
10
    user_name: "John Smith",
11
    permissions: ["room.self.audio_mute", "room.self.video_mute"]
12
  })
13
});
14
15
const { token } = await response.json();
16
// Send this token to your browser client

This approach ensures your project credentials never expose to client-side code while providing scoped access to specific rooms, channels, or resources.