Realtime sockets

A realtime socket streams the same receipts as an event pull subscription, so you don’t need to poll. You attach existing pull subscriptions to the socket.

You need website_read and event_read, and every request must send an exact HTTPS Origin header.

1. Create a session.

   curl -s -X POST "$GATEWAY/api/v1/realtime/sessions" \
     -H "Authorization: Bearer $INSIDE_GATEWAY_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Origin: https://app.example.com" \
     -d '{"website_ids":["web_4927_123"]}'

   The 201 response contains session_id and a single-use ticket that expires within 30 seconds.

2. Open the socket. Connect to GET /api/v1/realtime/sessions/{session_id}/socket as a WebSocket with the same Origin. Within 5 seconds, send the ticket as the first text frame:

   { "type": "auth", "ticket": "..." }

   An auth.ok frame confirms authentication.

3. Attach a subscription.

   { "type": "subscription.open", "subscription_id": "sub_...", "cursor": "..." }

4. Acknowledge each page. For every subscription.page, send subscription.ack with its exact next_cursor within 30 seconds.

5. Reconnect or close. Call POST /api/v1/realtime/sessions/{session_id}/tickets for a reconnect ticket, and DELETE /api/v1/realtime/sessions/{session_id} to close the session.

Limits

• Up to 20 sessions per installation, and up to 20 attached subscriptions per socket.
• Each page has at most 25 receipts, and frames are at most 64 KiB.
• Reconnecting replays from the last acknowledged cursor.
• Send subscription.close to detach a subscription.