RelayClient

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_API_TOKEN environment variable.

jwtToken

string

JWT token for alternative authentication. Set via constructor or SIGNALWIRE_JWT_TOKEN environment variable. When provided, project and token are not required.

host

stringDefaults to relay.signalwire.com

Relay WebSocket endpoint. The default is the endpoint for SignalWire projects; you do not set your space here. The constructor option wins, then SIGNALWIRE_RELAY_HOST, then SIGNALWIRE_SPACE, then the default. RestClient reads SIGNALWIRE_SPACE as the REST host, so when it is set for REST, set SIGNALWIRE_RELAY_HOST or pass host to keep the default.

contexts

string[]Defaults to []

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

maxActiveCalls

number | undefinedDefaults to 1000

Maximum number of concurrent inbound calls the client will track. Calls arriving beyond this limit are dropped with a log warning. Set via constructor or RELAY_MAX_ACTIVE_CALLS environment variable. Constructor-only — not accessible as a public attribute after initialization.

scheme

'ws' | 'wss'Defaults to 'wss'

WebSocket scheme. Read-only. 'wss' (production, the default) or 'ws' (loopback / local only). Set via the scheme constructor option or the SIGNALWIRE_RELAY_SCHEME environment variable. Production should never use 'ws'.

relayProtocol

string

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

Methods

onCall

onMessage

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.

onEvent

Observe every inbound Relay event (low-level).

notify

Send a fire-and-forget JSON-RPC notification.

Async Disposable

RelayClient implements Symbol.asyncDispose, so it can be used with the await using statement for scoped connections. The client disconnects automatically when the scope exits.

import { RelayClient } from '@signalwire/sdk';
async function main() {
  await using client = new RelayClient({
    project: process.env.SIGNALWIRE_PROJECT_ID!,
    token: process.env.SIGNALWIRE_API_TOKEN!,
    contexts: ['default'],
  });
  await client.connect();
  const call = await client.dial([
    [{ type: 'phone', params: { to_number: '+15559876543', from_number: '+15551234567' } }],
  ]);
  // Automatically disconnects on exit
}
await main();

For environments without await using support, use try/finally with disconnect().

Example

import { RelayClient } from '@signalwire/sdk';
const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_API_TOKEN!,
  contexts: ['default']
});
client.onCall(async (call) => {
  await call.answer();
  const action = await call.play([{ type: 'tts', text: 'Hello from Relay!' }]);
  await action.wait();
  await call.hangup();
});
client.onMessage(async (message) => {
  console.log(`SMS from ${message.fromNumber}: ${message.body}`);
});
await client.run();