Skip to main content

Realtime Server SDK

npm install @signalwire/realtime-api

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​

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"
});

Explore the SDK​