Skip to main content

Technical Reference

The SignalWire Realtime SDK provides a comprehensive Node.js interface for real-time communication services on the SignalWire platform.

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.dialPhone(), 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 listen() methods handle a different communication pattern: real-time event notifications. These are asynchronous events triggered by external actions - like when someone calls your number (onCallReceived), sends you a message (onMessageReceived), or when something happens in a video room you're monitoring (onMemberJoined). 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:

import { SignalWire } from "@signalwire/realtime-api";

const client = await SignalWire({
  project: "your-project-id",     // SignalWire project identifier
  token: "your-project-token"     // API token from project settings
});

const voiceClient = client.voice;

// Voice, Messaging, and Task require topics for event routing
await voiceClient.listen({
  topics: ["support", "sales"],    // Required for Voice, Messaging, Task
  onCallReceived: (call) => { /* handle call */ }
});

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.

// Topic-based client (receives events only for subscribed topics)
await voiceClient.listen({
  topics: ["support", "sales"],  // Only receive calls for these topics
  onCallReceived: (call) => { /* handle call */ }
});

// Non-topic client (receives all events for the project)
await videoClient.listen({
  onRoomStarted: (roomSession) => { /* handle room */ }  // No topics needed
});

Available Namespaces​