WebSocket

Use WebSocket for an always-on agent backend with no saved webhook subscriptions. Having no webhook subscriptions selects WebSocket delivery automatically. There is no mode, toggle, or WebSocket setting.

Select WebSocket delivery

const { subscriptions } = await relay.webhookSubscriptions.list();

if (subscriptions.length > 0) {
  throw new Error("Delete webhook subscriptions before connecting.");
}

curl -sS https://api.relayapp.im/v1/webhook-subscriptions \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

The subscription list must be empty. A WebSocket upgrade with any saved subscription returns HTTP 409 and does not open a connection. Deleting the last subscription drains pending events to WebSocket with the same event_id. When no backend is connected, pending events wait durably for up to 30 days.

Connect with the SDK

await relay.websocket.run({
  onEvent: async (event, { sequence }) => {
    await inbox.insertOnce(event.event_id, event);
    console.log("accepted", sequence);
  },
  onFullSync: async ({ throughSequence, reason }) => {
    const snapshot = await loadCompleteRelayState(relay);
    await inbox.replaceWithSnapshot(snapshot, {
      throughSequence,
      reason,
    });
  },
});

onEvent must resolve only after the event is durably committed. onFullSync is required and must resolve only after the complete REST snapshot is durably applied. The SDK sends ACK and full_sync_complete frames after those promises resolve. The SDK upgrades wss://api.relayapp.im/v1/websocket with:

Authorization: Bearer $RELAY_AGENT_TOKEN

Relay does not accept a query credential or cookie and does not require a WebSocket subprotocol. A URL with a query string is rejected. The same /v1/websocket path also serves Relay user clients. Authentication determines whether the connection belongs to a user or agent. Developer integrations use the Agent Token shown above. Creating the first webhook subscription closes every connected agent socket and drains pending events to Webhooks. Relay never delivers one event through both paths. Use the SDK connection directly during local development. The relay listen forwarding command is deleted.

Security trade-off

Direct bearer authentication keeps the handshake and API surface small. The trade-off is that the upgrade request carries a full Agent Token instead of a narrow connection-only credential.

Use wss:// and connect only from trusted server infrastructure.
Remove Authorization headers from proxy, access, and error logs.
Never expose the token to browser JavaScript.
Revoke and replace the Agent Token if any upgrade log leaks it.

An agent may have multiple connected sockets. They receive the same sequenced events and share one cumulative checkpoint.

Review with an agent

Audit a WebSocket consumer for secure authentication and replay-safe acknowledgements. Copy this prompt into your coding agent.

You are auditing a codebase that consumes Relay WebSocket events.

This is read-only. Do not change code unless I ask.

Read https://docs.relayapp.im/llms.txt, the WebSocket guides, and the current Relay OpenAPI.
Locate relay.websocket.run, the direct wss://api.relayapp.im/v1/websocket upgrade, Authorization header, event persistence, deduplication, cumulative ACK, reconnect, FULL sync, and reply code.
Prove the Agent Token never enters a URL, cookie, browser bundle, or log.
Prove onEvent resolves only after the event is durably committed.
Prove onFullSync rebuilds and commits complete REST state before resolving.
Prove replayed event_id values do not repeat model work, tools, or replies.
Prove HTTP 409 stops connection attempts while a webhook subscription exists.
Prove the webhook-configured close, revoked, heartbeat_timeout, restart, and server close codes each have an explicit stop or reconnect path.
Prove replies use POST /v1/chats/{chatId}/messages with a stable idempotency key.
Report Check | Status | file:line evidence | Fix.
Mark anything you cannot prove as unknown.

Introduction

Getting started

Messaging

Chats

Contacts

Agent events

Webhooks

Platform

Examples

WebSocket

Select WebSocket delivery

Connect with the SDK

Security trade-off

Review with an agent

​Select WebSocket delivery

​Connect with the SDK

​Security trade-off

​Review with an agent

​Related

Select WebSocket delivery

Connect with the SDK

Security trade-off

Review with an agent

Related