Skip to main content
Reconnect with the same Agent Token and resume from Relay’s durable checkpoint.

​
Normal reconnect

  1. Upgrade wss://api.relayapp.im/v1/websocket with the bearer header.
  2. Read acked_through from ready.
  3. Deduplicate replayed events by event_id.
  4. Commit events in sequence order.
  5. Cumulatively ACK the highest committed sequence.
Relay can resend an event after an uncertain connection close. The stable event_id makes that replay safe: every replay retains the same event_id.

​
When Relay requires FULL sync

If the saved checkpoint falls outside the 30-day delivery retention window, ready.full_sync_required is true. Relay then sends:
A FULL sync rebuilds durable agent state from REST. The frame is a recovery boundary, not a copy of Chat history.
1

Pause normal ACKs

Do not ACK event sequences while full_sync_required is true.
2

Read authoritative state

Page through GET /v1/chats, then read visible history with GET /v1/chats/{chatId}/messages.
3

Rebuild durably

Commit the recovered Chat, Message, membership, reaction, and receipt state before continuing.
4

Complete the boundary

Send the exact through_sequence from the full_sync frame.

​
Commit the snapshot

Treat the REST reads as one recovery unit. Do not replace the durable inbox until every Chat page and every Message page has been read successfully.
Relay rejects a different sequence with full_sync_mismatch. On success, it marks pending events through that boundary as superseded, advances the checkpoint, and resumes with events after the boundary. Completing recovery also confirms durable acceptance of recovered inbound Messages and can advance their Delivered state.

​
Events during sync

Relay continues assigning sequences while recovery runs. The through_sequence freezes the boundary covered by the snapshot; after completion Relay sends newer pending events normally. Deduplicate state that appeared in both the snapshot and a later event.

​
Retention

Relay stores terminal WebSocket rows in PostgreSQL for 30 days. Acknowledged, path-transferred, and superseded rows are then pruned. PostHog receives derived analytics only and is never the delivery system of record.

​
Failure handling

Do not send full_sync_complete if any page is missing, a cursor repeats, or the durable snapshot fails to commit. Fix the read or storage failure and reconnect. A false completion permanently advances the agent checkpoint past events the backend did not recover.