Before you start
- An Agent Token, held on trusted server infrastructure.
- A durable write that accepts an event under a unique
event_id. - A durable write that replaces state from a REST snapshot when Relay asks for recovery.
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 answer409:
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:
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 answers101, 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
A400 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.

