Overview

caution

The RELAY v4 is the most up-to-date version of the Realtime Relay SDK. Consider reading the Upgrading to Relay v4 page to understand the benefits of RELAY v4 and how to upgrade.

Realtime Server SDK

npm install @signalwire/realtime-api@~3

GitHub npm

SDK Reference

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.

How It Works

The SDK operates through a bidirectional WebSocket connection. When you call methods like dial() or send(), the SDK sends requests to SignalWire and returns promises with the results. Simultaneously, you can listen for real-time events like incoming calls or messages using the .on() method.

Getting Started

Install the SDK

npm install @signalwire/realtime-api@~3

Create a Relay Application

For Voice, Messaging, and Task namespaces, create a Relay Application resource in your dashboard:

1. Set a name for your application
2. Choose a reference (e.g., "support", "sales") that matches your client's topics
3. Assign phone numbers or SIP addresses to route calls to this application

Set up authentication

Get your project credentials from the SignalWire Dashboard:

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

const client = new Voice.Client({
  project: "your-project-id",
  token: "your-api-token",
  topics: ["support"]  // Must match your Relay Application reference
});

Test your setup

Create a simple inbound call handler to test your setup:

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

const client = new Voice.Client({
  project: "your-project-id",
  token: "your-api-token",
  topics: ["support"]  // Must match your Relay Application reference
});

// Answer incoming calls and play a greeting
client.on("call.received", async (call) => {
  console.log("Incoming call from:", call.from);
  
  await call.answer();
  await call.playTTS({ text: "Welcome to SignalWire!" });
});

console.log("Waiting for calls...");

Now call the SignalWire phone number or SIP address you assigned to your Relay Application in step 2. Your application will answer and play the greeting!

Usage Examples

Voice Calls

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

const voice = new Voice.Client({
  project: "your-project-id",
  token: "your-api-token",
  topics: ["office"]
});

// Listen for incoming calls
voice.on("call.received", async (call) => {
  console.log("Incoming call from:", call.from);
  await call.answer();
  
  // Play a greeting
  await call.playTTS({ text: "Welcome to our office" });
});

// Make an outbound call
const call = await voice.dialPhone({
  to: "+1234567890",
  from: "+0987654321"
});

SMS/MMS

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

const messaging = new Messaging.Client({
  project: "your-project-id",
  token: "your-api-token",
  topics: ["notifications"]
});

// Handle incoming messages
messaging.on("message.received", (message) => {
  console.log("Message from:", message.from);
  console.log("Content:", message.body);
});

// Send a message
await messaging.send({
  to: "+1234567890",
  from: "+0987654321",
  body: "Your appointment is confirmed for tomorrow at 3pm"
});

Video Rooms

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

const video = new Video.Client({
  project: "your-project-id",
  token: "your-api-token"
});

// Monitor room events
video.on("room.started", async (roomSession) => {
  console.log("Room started:", roomSession.name);
  
  roomSession.on("member.joined", (member) => {
    console.log("Member joined:", member.name);
  });
});

// Get active room sessions
const { roomSessions } = await video.getRoomSessions();

Chat Applications

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

const chat = new Chat.Client({
  project: "your-project-id",
  token: "your-api-token"
});

// Listen for messages in conversations
chat.on("message.received", (message) => {
  console.log(`${message.member.name}: ${message.content}`);
});

// Send a chat message
await chat.publish({
  channel: "general",
  content: "Hello team!"
});

PubSub Messaging

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

const pubsub = new PubSub.Client({
  project: "your-project-id",
  token: "your-api-token"
});

// Subscribe to channels
await pubsub.subscribe(["notifications", "updates"]);

// Listen for messages
pubsub.on("message", (message) => {
  console.log(`Channel: ${message.channel}`);
  console.log(`Content: ${message.content}`);
});

// Publish a message
await pubsub.publish({
  channel: "notifications",
  content: { alert: "System maintenance in 30 minutes" }
});

Task Management

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

const task = new Task.Client({
  project: "your-project-id",
  token: "your-api-token",
  topics: ["workers"]
});

// Listen for incoming tasks
task.on("task.received", (payload) => {
  console.log("Received task:", payload);
  
  // Process the task based on payload
  if (payload.action === "send_email") {
    console.log(`Sending email to ${payload.recipient}: ${payload.subject}`);
    // Add your custom email sending logic here
  }
});

// Send a task to workers
await Task.send({
  topic: "workers",
  message: {
    action: "send_email",
    recipient: "user@example.com",
    subject: "Welcome aboard!"
  }
});

Explore the SDK

Technical Reference

Complete API documentation for all namespaces, classes, and methods

Guides & Examples

Step-by-step tutorials and practical examples to get you building quickly