RELAY

RelayClient

View as MarkdownOpen in Claude

RelayClient manages a persistent WebSocket connection to SignalWire’s RELAY service. It handles authentication, automatic reconnection with exponential backoff, inbound event dispatch, outbound dialing, and SMS/MMS messaging. Use it when you need imperative, event-driven control over calls rather than the declarative AI agent approach.

The client supports two authentication modes: project ID + API token, or JWT token. Credentials can be passed directly or read from environment variables.

Properties

project
string

SignalWire project ID. Set via constructor or SIGNALWIRE_PROJECT_ID environment variable.

token
string

API token for authentication. Set via constructor or SIGNALWIRE_TOKEN environment variable.

jwtToken
string

JWT token for alternative authentication. Read from the SIGNALWIRE_JWT_TOKEN environment variable. When provided, project and token are not required.

host
string

SignalWire space hostname (e.g., your-space.signalwire.com). Set via constructor or SIGNALWIRE_SPACE environment variable. Defaults to relay.signalwire.com.

contexts
string[]

List of contexts to subscribe to for inbound call and message events.

relayProtocol
string

Server-assigned protocol string from the connect response. Read-only. Used internally for session resumption on reconnect.

Methods

onCall

Register an inbound call handler.

onMessage

Register an inbound message handler.

connect

Establish the WebSocket connection and authenticate.

disconnect

Close the WebSocket connection cleanly.

run

Start the client with automatic reconnection.

dial

Initiate an outbound call.

sendMessage

Send an outbound SMS or MMS message.

receive

Subscribe to additional contexts for inbound events.

unreceive

Unsubscribe from inbound event contexts.

execute

Send a raw JSON-RPC request to RELAY.

Example

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4  project: process.env.SIGNALWIRE_PROJECT_ID!,
5  token: process.env.SIGNALWIRE_TOKEN!,
6  contexts: ['default']
7});
8
9client.onCall(async (call) => {
10  await call.answer();
11  const action = await call.play([{ type: 'tts', text: 'Hello from RELAY!' }]);
12  await action.wait();
13  await call.hangup();
14});
15
16client.onMessage(async (message) => {
17  console.log(`SMS from ${message.fromNumber}: ${message.body}`);
18});
19
20await client.run();