> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# RelayClient

> WebSocket client for real-time call and message control.

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

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

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

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

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

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

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

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

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

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

`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`** `string` — default: 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[]` — default: \[]

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

---

**`maxActiveCalls`** `number | undefined` — default: 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'` — default: '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](/docs/server-sdks/reference/typescript/relay/client/on-call)

Register an inbound call handler.

#### [onMessage](/docs/server-sdks/reference/typescript/relay/client/on-message)

Register an inbound message handler.

#### [connect](/docs/server-sdks/reference/typescript/relay/client/connect)

Establish the WebSocket connection and authenticate.

#### [disconnect](/docs/server-sdks/reference/typescript/relay/client/disconnect)

Close the WebSocket connection cleanly.

#### [run](/docs/server-sdks/reference/typescript/relay/client/run)

Start the client with automatic reconnection.

#### [dial](/docs/server-sdks/reference/typescript/relay/client/dial)

Initiate an outbound call.

#### [sendMessage](/docs/server-sdks/reference/typescript/relay/client/send-message)

Send an outbound SMS or MMS message.

#### [receive](/docs/server-sdks/reference/typescript/relay/client/receive)

Subscribe to additional contexts for inbound events.

#### [unreceive](/docs/server-sdks/reference/typescript/relay/client/unreceive)

Unsubscribe from inbound event contexts.

#### [execute](/docs/server-sdks/reference/typescript/relay/client/execute)

Send a raw JSON-RPC request to Relay.

#### [onEvent](/docs/server-sdks/reference/typescript/relay/client/on-event)

Observe every inbound Relay event (low-level).

#### [notify](/docs/server-sdks/reference/typescript/relay/client/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.

```typescript {4-5}
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**

```typescript {3}
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();
```

> WebSocket client for real-time call and message control.

## Docs

- [connect](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/connect.md): Establish the WebSocket connection and authenticate.
- [dial](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/dial.md): Initiate an outbound call.
- [disconnect](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/disconnect.md): Close the WebSocket connection cleanly.
- [execute](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/execute.md): Send a raw JSON-RPC request to Relay.
- [notify](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/notify.md): Send a fire-and-forget JSON-RPC notification to Relay.
- [onCall](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/on-call.md): Register the inbound call handler.
- [onEvent](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/on-event.md): Register a low-level observer for every inbound Relay event.
- [onMessage](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/on-message.md): Register the inbound message handler.
- [receive](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/receive.md): Subscribe to additional contexts for inbound events.
- [run](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/run.md): Start the client with automatic reconnection.
- [sendMessage](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/send-message.md): Send an outbound SMS or MMS message.
- [unreceive](https://signalwire.com/docs/server-sdks/reference/typescript/relay/client/unreceive.md): Unsubscribe from inbound event contexts.