RELAY Realtime SDK v3

$
npm install @signalwire/realtime-api@~3

The SignalWire Realtime SDK v3 is a Node.js server SDK that enables real-time communication through WebSocket connections. Built on an event-driven architecture, it provides dedicated namespaces for voice, video, messaging, chat, pub/sub, and task management.

Getting Started

$
npm install @signalwire/realtime-api@~3

1
import { Voice } from "@signalwire/realtime-api";
2
3
const client = new Voice.Client({
4
  project: "your-project-id",
5
  token: "your-api-token",
6
  topics: ["support"]  // Must match your RELAY Application reference
7
});

1
import { Voice } from "@signalwire/realtime-api";
2
3
const client = new Voice.Client({
4
  project: "your-project-id",
5
  token: "your-api-token",
6
  topics: ["support"]  // Must match your RELAY Application reference
7
});
8
9
// Answer incoming calls and play a greeting
10
client.on("call.received", async (call) => {
11
  console.log("Incoming call from:", call.from);
12
13
  await call.answer();
14
  await call.playTTS({ text: "Welcome to SignalWire!" });
15
});
16
17
console.log("Waiting for calls...");

Core Concepts

WebSocket Event Architecture

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

When you call a method like client.dial(), 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 a Call object containing all the details of your newly created call.

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

Authentication and Access Control

All SDK clients authenticate using project credentials. Voice, Messaging, and Task namespaces also require topic subscriptions that control event routing:

1
const client = new Voice.Client({
2
  project: "your-project-id",     // SignalWire project identifier
3
  token: "your-project-token",    // API token from project settings
4
  topics: ["support", "sales"]    // Required for Voice, Messaging, Task
5
});

Your project ID and token are available in the SignalWire Dashboard. These authenticate your WebSocket connection and establish your access permissions.

Topics (formerly contexts) work with RELAY Application resources to route events. When you assign a phone number or a SIP address to a RELAY Application with reference “support”, SignalWire routes all calls from that number or SIP address to SDK clients authenticated with the “support” topic. This creates strict access control - a client subscribed to “support” cannot receive events intended for “sales”.

The routing process is straightforward: incoming calls hit a phone number or a SIP address, SignalWire checks the RELAY Application’s reference, then delivers the event only to clients with matching topics. This happens automatically based on your authentication.

1
// Topic-based client (receives events only for subscribed topics)
2
const voice = new Voice.Client({
3
  project: "project-id",
4
  token: "token",
5
  topics: ["support", "sales"]  // Only receive calls for these topics
6
});
7
8
// Non-topic client (receives all events for the project)
9
const video = new Video.Client({
10
  project: "project-id",
11
  token: "token"  // No topics needed
12
});

Available Namespaces

Classes

Functions

createClient

• Const createClient(userOptions): Promise<RealtimeClient> - Deprecated — See RealtimeClient for more details.

Deprecated You no longer need to create the client manually. You can use the product constructors, like Video.Client, to access the same functionality.

Creates a real-time Client.

Parameters

Returns

Promise<RealtimeClient> - Deprecated — See RealtimeClient for more details.

an instance of a real-time Client.

Example

1
const client = await createClient({
2
  project: "<project-id>",
3
  token: "<project-token>",
4
});

getConfig

• Const getConfig(): GlobalConfig

Returns

GlobalConfig