***

title: RELAY
sidebar-title: Overview
subtitle: TypeScript API reference for RelayClient, Call, Message, and real-time events
slug: /reference/typescript/relay
description: Real-time WebSocket client for call and message control.
max-toc-depth: 3
position: 0
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[agents]: /docs/server-sdks/reference/typescript/agents

[client]: /docs/server-sdks/reference/typescript/relay/client

[call]: /docs/server-sdks/reference/typescript/relay/call

[message]: /docs/server-sdks/reference/typescript/relay/message

[actions]: /docs/server-sdks/reference/typescript/relay/actions

[events]: /docs/server-sdks/reference/typescript/relay/events

[constants]: /docs/server-sdks/reference/typescript/relay/constants

[relay-error]: /docs/server-sdks/reference/typescript/relay/relay-error

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][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.

```typescript {3}
import { RelayClient } from '@signalwire/sdk';

const client = new RelayClient({
  project: 'your-project-id',
  token: 'your-api-token',
  host: 'your-space.signalwire.com',
  contexts: ['support', 'sales'],
});

client.onCall(async (call) => {
  await call.answer();

  // Or subscribe/unsubscribe dynamically
  // await client.receive(['billing']);     // Add a context
  // await client.unreceive(['sales']);     // Remove a context
});

await 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:

```typescript {13}
import { RelayClient } from '@signalwire/sdk';

const client = new RelayClient({
  project: 'your-project-id',
  token: 'your-api-token',
  host: 'your-space.signalwire.com',
  contexts: ['default'],
});

client.onCall(async (call) => {
  await call.answer();

  // Play a menu and collect one digit
  const action = await call.playAndCollect(
    [{ type: 'tts', text: 'Press 1 for sales, 2 for support.' }],
    { digits: { max: 1, digit_timeout: 5.0 } },
  );
  const event = await action.wait();

  const digit = (event.params.result as Record<string, unknown>)?.digits ?? '';

  if (digit === '1') {
    await call.play([{ type: 'tts', text: 'Transferring to sales.' }]);
    await call.transfer('+15551234567');
  } else if (digit === '2') {
    await call.play([{ type: 'tts', text: 'Transferring to support.' }]);
    await call.transfer('+15559876543');
  } else {
    await call.play([{ type: 'tts', text: 'Goodbye.' }]);
    await call.hangup();
  }
});

await client.run();
```

## Classes

<CardGroup cols={2}>
  <Card title="RelayClient" href="/docs/server-sdks/reference/typescript/relay/client">
    WebSocket client for connecting, authenticating, dialing calls, and sending messages.
  </Card>

  <Card title="Call" href="/docs/server-sdks/reference/typescript/relay/call">
    Call object with methods for answer, hangup, play, record, collect, connect, and more.
  </Card>

  <Card title="Message" href="/docs/server-sdks/reference/typescript/relay/message">
    Message object for tracking SMS/MMS state and waiting for delivery confirmation.
  </Card>

  <Card title="Actions" href="/docs/server-sdks/reference/typescript/relay/actions">
    Async action handles returned from call control methods like play, record, and detect.
  </Card>

  <Card title="Events" href="/docs/server-sdks/reference/typescript/relay/events">
    Typed event classes for call state changes, playback, recording, and messaging.
  </Card>

  <Card title="Constants" href="/docs/server-sdks/reference/typescript/relay/constants">
    Call states, connect states, message states, and event type string constants.
  </Card>

  <Card title="RelayError" href="/docs/server-sdks/reference/typescript/relay/relay-error">
    Error thrown when the RELAY server returns an error response.
  </Card>
</CardGroup>