Realtime Client

View as Markdown

The Realtime Client is the main entry point for the Realtime SDK. It provides methods to connect to the SignalWire Realtime service, authenticate, and access namespace clients for voice, video, chat, task, and pubsub functionality.

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({
4 project: "your-project-id",
5 token: "your-api-token"
6});

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 on each namespace client.

Use connect to re-establish a connection after disconnecting, or disconnect to close the connection.

Constructor

SignalWire(options): Promise<SWClient>

Creates a new Realtime Client instance.

Parameters

options
objectRequired

Configuration options for the client.

project
stringRequired

SignalWire project id, e.g. a10d8a9f-2166-4e82-56ff-118bc3a4840f

token
stringRequired

SignalWire project token, e.g. PT9e5660c101cd140a1c93a0197640a369cf5f16975a0079c9

host
string

SignalWire host URL. Default is the standard SignalWire host.

logLevel
string

Log level: 'trace', 'debug', 'info', 'warn', 'error', or 'silent'.

debug
object

Debug configuration object.

logWsTraffic
booleanDefaults to false

If true, logs all WebSocket traffic.

Namespace Clients

The Realtime Client provides access to namespace clients for different communication features. Access them via properties on the client instance.

1const voiceClient = client.voice;
2const videoClient = client.video;
3const chatClient = client.chat;
4const taskClient = client.task;
5const pubSubClient = client.pubSub;

Available Namespace Clients

Examples

Voice Calls

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({
4 project: "your-project-id",
5 token: "your-api-token"
6});
7
8const voiceClient = client.voice;
9
10// Listen for incoming calls
11await voiceClient.listen({
12 topics: ["office"],
13 onCallReceived: async (call) => {
14 console.log("Incoming call from:", call.from);
15 await call.answer();
16
17 // Play a greeting
18 await call.playTTS({ text: "Welcome to our office" });
19 }
20});
21
22// Make an outbound call
23const call = await voiceClient.dialPhone({
24 to: "+1234567890",
25 from: "+0987654321"
26});

Video Rooms

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({
4 project: "your-project-id",
5 token: "your-api-token"
6});
7
8const videoClient = client.video;
9
10// Monitor room events
11await videoClient.listen({
12 onRoomStarted: async (roomSession) => {
13 console.log("Room started:", roomSession.name);
14
15 await roomSession.listen({
16 onMemberJoined: (member) => {
17 console.log("Member joined:", member.name);
18 }
19 });
20 }
21});
22
23// Get active room sessions
24const { roomSessions } = await videoClient.getRoomSessions();

Chat Applications

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({
4 project: "your-project-id",
5 token: "your-api-token"
6});
7
8const chatClient = client.chat;
9
10// Listen for messages in conversations
11await chatClient.listen({
12 channels: ["general"],
13 onMessageReceived: (message) => {
14 console.log(`${message.member.name}: ${message.content}`);
15 }
16});
17
18// Send a chat message
19await chatClient.publish({
20 channel: "general",
21 content: "Hello team!"
22});

PubSub Messaging

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({
4 project: "your-project-id",
5 token: "your-api-token"
6});
7
8const pubSubClient = client.pubSub;
9
10// Listen for messages
11await pubSubClient.listen({
12 channels: ["notifications", "updates"],
13 onMessageReceived: (message) => {
14 console.log(`Channel: ${message.channel}`);
15 console.log(`Content: ${message.content}`);
16 }
17});
18
19// Publish a message
20await pubSubClient.publish({
21 channel: "notifications",
22 content: { alert: "System maintenance in 30 minutes" }
23});

Task Management

1import { SignalWire } from "@signalwire/realtime-api";
2
3const client = await SignalWire({
4 project: "your-project-id",
5 token: "your-api-token"
6});
7
8const taskClient = client.task;
9
10// Listen for incoming tasks
11await taskClient.listen({
12 topics: ["workers"],
13 onTaskReceived: (payload) => {
14 console.log("Received task:", payload);
15
16 // Process the task based on payload
17 if (payload.action === "send_email") {
18 console.log(`Sending email to ${payload.recipient}: ${payload.subject}`);
19 // Add your custom email sending logic here
20 }
21 }
22});
23
24// Send a task to workers
25await taskClient.send({
26 topic: "workers",
27 message: {
28 action: "send_email",
29 recipient: "user@example.com",
30 subject: "Welcome aboard!"
31 }
32});