​

Session Replay

​

Retention and limits

• Inline head — the first 5,000 events (up to 4 MB) are kept on the conversation row for instant preview. Long sessions don’t truncate: once the head fills, every further batch spills to durable object storage as an ordered chunk, and playback reassembles head plus chunks into the full stream.
• Abuse backstop — a recording is hard-capped at roughly 1 GiB of serialized events (5 million events). Only a pathological or hostile recorder can reach it; when it trips, the recording’s status becomes capped and its truncated flag is set to true. Normal multi-hour support sessions stay well below the ceiling.

​

Watching a recording in the inbox

​

Failure modes to expect

• Nothing recorded. The widget captures only after a visitor starts a conversation on a page with the widget installed. If no session-replay row ever appears, capture isn’t running — verify with the steps below before assuming data was lost.
• Playback shows only the start of a long session. The recording offloaded its tail to durable storage and reassembly failed (a transient storage read error). The API serves the inline head rather than failing the request; retry, and the full stream usually returns. Persistent head-only responses on offloaded recordings (offloaded: true in the summary) are worth a support ticket.
• A capped / truncated recording. The abuse backstop fired. Treat it as a signal that the recorder or page is emitting far more events than a real session produces — for example a page script in a rapid DOM-mutation loop.
• Purging during erasure. DELETE /session-replay/{conversationId} removes the recording’s durable chunks first, then drops the row pointer, and writes an audit entry (session_replay.deleted). The conversation and messages are untouched. If the conversation itself is later deleted, any still-attached recording goes with it — purge recordings first when the erasure request covers the recording but not the thread.

​

Privacy posture and compliance

curl -X PUT https://api.orbit.devotel.io/api/v1/session-replay/privacy \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mask_all_inputs": true,
    "mask_text_selectors": [".account-number"],
    "block_selectors": ["#payment-iframe"],
    "mask_pii_default": true
  }'

• GDPR / DSAR — session recordings of EU visitors are personal data. Your DPO should review the masking policy (what leaves the browser), the purge endpoint (your right-to-erasure mechanism), and the audit entries both produce. See GDPR posture guide and DSAR handling for how erasure requests map to Orbit’s purge surfaces.
• Sector controls (PCI, health data) — if your pages render card data or regulated identifiers, rely on block_selectors for the hard “never serialized” cut rather than text masking, and document the selectors you set as part of your own control evidence.

​

Verifying capture

1. Install the widget on a test page, open that page, and start a conversation as a visitor.
2. Browse a little — click, scroll, navigate across one or two pages.
3. Call GET /api/v1/session-replay (or open the conversation in the Inbox). A row for your test conversation with a growing total_event_count means capture is live.
4. Fetch GET /api/v1/session-replay/{conversationId} and check that session_replay.status is recording (or ended once the visitor leaves) rather than capped.

​

Endpoints

​

See also

• Session Replay API reference — full payload shapes and error codes
• Co-browse — the live, real-time counterpart to session replay
• Inbox API — where agents play recordings back
• GDPR posture guide — how replay masking and purge fit your erasure duties