For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inSign up
Support
GuidesReference
GuidesReference
    • Core
      • Overview
    • Agents
      • Overview
      • AgentBase
      • AgentServer
      • Configuration
      • ContextBuilder
      • DataMap
      • FunctionResult
      • Helper Functions & Utilities
      • LiveWire
      • PomBuilder
      • Prefabs
      • SkillBase
      • SkillManager
      • SkillRegistry
      • Skills
      • SwaigFunction
      • SwmlBuilder
      • SWMLService
    • RELAY
      • Overview
      • Actions
      • Call
      • Constants
      • Events
      • Message
      • RelayClient
      • RelayError
    • REST Client
      • Overview
      • Addresses
      • Calling
      • ChatResource
      • Compat
      • Datasphere
      • Fabric
      • ImportedNumbersResource
      • Logs
      • LookupResource
      • MFA
      • Number Groups
      • Phone Numbers
      • Project
      • PubSubResource
      • Queues
      • Recordings
      • Registry
      • RestClient
      • RestError
      • Short Codes
      • SIP Profile
      • Verified Callers
      • Video
LogoLogoSignalWire Docs
Log inSign up
Support
On this page
  • Context Routing
  • Example
  • Classes
RELAY

RELAY

TypeScript API reference for RelayClient, Call, Message, and real-time events

|View as Markdown|Open in Claude|
Was this page helpful?
Edit this page
Previous

Actions

Next
Built with

The RELAY namespace provides imperative, event-driven control over voice calls and SMS/MMS messages through a persistent WebSocket connection to SignalWire. While the Agents namespace handles AI-driven conversations declaratively via SWML, RELAY gives you fine-grained, async control over every step of a call — answering, playing prompts, collecting digits, recording, bridging, conferencing, and more.

RELAY uses the JSON-RPC 2.0 protocol over WebSocket (wss://). The client authenticates once, subscribes to contexts for inbound events, and processes call and message events in an async event loop. Automatic reconnection with exponential backoff ensures resilience against transient network failures.

Context Routing

Contexts are routing labels that control which inbound calls and messages are delivered to your application. When you assign a phone number to a context in the SignalWire dashboard, all calls to that number are routed to RELAY clients subscribed to that context.

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4 project: 'your-project-id',
5 token: 'your-api-token',
6 host: 'your-space.signalwire.com',
7 contexts: ['support', 'sales'],
8});
9
10client.onCall(async (call) => {
11 await call.answer();
12
13 // Or subscribe/unsubscribe dynamically
14 // await client.receive(['billing']); // Add a context
15 // await client.unreceive(['sales']); // Remove a context
16});
17
18await client.run();

A client only receives events for its subscribed contexts. This enables multiple applications or workers to handle different call flows on the same project by subscribing to different contexts.

Example

An IVR that answers calls, plays a menu, collects a digit, and routes accordingly:

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4 project: 'your-project-id',
5 token: 'your-api-token',
6 host: 'your-space.signalwire.com',
7 contexts: ['default'],
8});
9
10client.onCall(async (call) => {
11 await call.answer();
12
13 // Play a menu and collect one digit
14 const action = await call.playAndCollect(
15 [{ type: 'tts', text: 'Press 1 for sales, 2 for support.' }],
16 { digits: { max: 1, digit_timeout: 5.0 } },
17 );
18 const event = await action.wait();
19
20 const digit = (event.params.result as Record<string, unknown>)?.digits ?? '';
21
22 if (digit === '1') {
23 await call.play([{ type: 'tts', text: 'Transferring to sales.' }]);
24 await call.transfer('+15551234567');
25 } else if (digit === '2') {
26 await call.play([{ type: 'tts', text: 'Transferring to support.' }]);
27 await call.transfer('+15559876543');
28 } else {
29 await call.play([{ type: 'tts', text: 'Goodbye.' }]);
30 await call.hangup();
31 }
32});
33
34await client.run();

Classes

RelayClient

WebSocket client for connecting, authenticating, dialing calls, and sending messages.

Call

Call object with methods for answer, hangup, play, record, collect, connect, and more.

Message

Message object for tracking SMS/MMS state and waiting for delivery confirmation.

Actions

Async action handles returned from call control methods like play, record, and detect.

Events

Typed event classes for call state changes, playback, recording, and messaging.

Constants

Call states, connect states, message states, and event type string constants.

RelayError

Error thrown when the RELAY server returns an error response.