Realtime Server SDK

npm install @signalwire/realtime-api

GitHub npm

SDK Reference

Overview

The SignalWire Realtime SDK v4 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 dialPhone() 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 listen() method.

Getting Started

Install the SDK

npm install @signalwire/realtime-api

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 { SignalWire } from "@signalwire/realtime-api";

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token"
});

// Access namespace clients
const voiceClient = client.voice;

Test your setup

Create a simple inbound call handler to test your setup:

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

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token"
});

const voiceClient = client.voice;

// Answer incoming calls and play a greeting
await voiceClient.listen({
  topics: ["support"],  // Must match your Relay Application reference
  onCallReceived: 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 { SignalWire } from "@signalwire/realtime-api";

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token"
});

const voiceClient = client.voice;

// Listen for incoming calls
await voiceClient.listen({
  topics: ["office"],
  onCallReceived: 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 voiceClient.dialPhone({
  to: "+1234567890",
  from: "+0987654321"
});

SMS/MMS

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

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token"
});

const messagingClient = client.messaging;

// Handle incoming messages
await messagingClient.listen({
  topics: ["notifications"],
  onMessageReceived: (message) => {
    console.log("Message from:", message.from);
    console.log("Content:", message.body);
  }
});

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

Video Rooms

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

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token"
});

const videoClient = client.video;

// Monitor room events
await videoClient.listen({
  onRoomStarted: async (roomSession) => {
    console.log("Room started:", roomSession.name);
    
    await roomSession.listen({
      onMemberJoined: (member) => {
        console.log("Member joined:", member.name);
      }
    });
  }
});

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

Chat Applications

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

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token"
});

const chatClient = client.chat;

// Listen for messages in conversations
await chatClient.listen({
  channels: ["general"],
  onMessageReceived: (message) => {
    console.log(`${message.member.name}: ${message.content}`);
  }
});

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

PubSub Messaging

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

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token"
});

const pubSubClient = client.pubSub;

// Listen for messages
await pubSubClient.listen({
  channels: ["notifications", "updates"],
  onMessageReceived: (message) => {
    console.log(`Channel: ${message.channel}`);
    console.log(`Content: ${message.content}`);
  }
});

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

Task Management

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

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token"
});

const taskClient = client.task;

// Listen for incoming tasks
await taskClient.listen({
  topics: ["workers"],
  onTaskReceived: (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 taskClient.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