Skip to main content
Connect your backend to Relay over WebSocket in two steps: confirm the agent has no webhook subscription, then open the connection.

Before you start

List webhook subscriptions

WebSocket delivery requires zero saved webhook subscriptions, because an agent uses one delivery path at a time. Read the list first; any saved subscription, active or not, makes the upgrade answer 409:
An empty list means the agent is ready. To move an agent from webhooks to WebSocket, read choose the delivery path:
captured-output

Connect

The SDK manages heartbeats, reconnects with backoff, and acknowledges only after your callbacks resolve. durableInbox is your database and readRelaySnapshot is your complete REST reader. With a raw client, connect to wss://api.relayapp.im/v1/websocket with the token in the Authorization header:
Redact the Authorization header from logs. Keep model work, tools, and replies in a separate worker that reads from the inbox; the onEvent callback only stores.

What you get back

The upgrade answers 101, and the first frame is ready with the agent’s checkpoint. Relay then sends event frames oldest first, up to max_in_flight unacknowledged at a time:
captured-output

When it fails

A 400 means the query string is wrong: send none, or exactly observe=true. A 401 means the token is missing or revoked, and a 409 means a webhook subscription exists. If the connection closes after the upgrade, read the disconnect reasons and the recovery procedure.

Next steps