Session Replay API

Session replay is the asynchronous twin of live co-browse. The native chat widget records the visitor’s web session (a serialized DOM snapshot plus incremental rrweb mutation events) and stores it against the conversation. A support agent plays it back later — in the inbox, with an rrweb player — to see exactly what the customer hit, after the fact rather than in real time. This page documents the operator half: listing recordings, fetching one for playback, purging one for a privacy request, and setting the capture-time masking policy. The visitor capture endpoints (how the widget uploads events) are internal to the widget runtime and not part of this surface. Base path: /api/v1/session-replay Authentication: API key (X-API-Key) or session JWT. Scopes & roles:

Reads (GET) require the conversations:read scope.
Writes — DELETE a recording and PUT the privacy policy — require the conversations:write scope and an owner, admin, or developer role.

Method	Path	Purpose
`GET`	`/api/v1/session-replay`	List recent recordings (summaries, no event payloads)
`GET`	`/api/v1/session-replay/{conversationId}`	Fetch the full recording for playback
`DELETE`	`/api/v1/session-replay/{conversationId}`	Purge a recording (privacy / right-to-erasure)
`GET`	`/api/v1/session-replay/privacy`	Get the capture-time privacy masking policy
`PUT`	`/api/v1/session-replay/privacy`	Update the capture-time privacy masking policy

A recording is keyed by its conversationId — the conversation the session was captured against. Recordings are tenant-scoped: you only ever see the recordings captured for your own account.

List recordings

Returns the most recent recordings across your conversations as lightweight summaries — the event payloads are omitted so the list stays cheap. The inbox “Session replays” panel uses this to let an agent pick one to play back. The newest 50 recordings are returned, newest first.

curl https://api.orbit.devotel.io/api/v1/session-replay \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "recordings": [
      {
        "conversation_id": "conv_abc123",
        "recording_id": "rec_9f2a",
        "status": "ended",
        "visitor_id": "vis_77c1",
        "start_url": "https://shop.example.com/checkout",
        "started_at": "2026-06-18T14:02:11.000Z",
        "ended_at": "2026-06-18T14:07:53.000Z",
        "event_count": 1840,
        "size_bytes": 612344,
        "truncated": false,
        "offloaded": false,
        "total_event_count": 1840,
        "total_size_bytes": 612344
      }
    ]
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-06-18T14:09:00.000Z"
  }
}

status is one of recording (still capturing), ended (the visitor finished or navigated away), or capped (an abuse backstop stopped capture). offloaded is true when a long session spilled past the inline head into durable storage; total_event_count and total_size_bytes describe the full recording across that storage, while event_count and size_bytes describe only the inline head. truncated is true only when the abuse backstop was hit.

Fetch a recording for playback

Returns the full rrweb event stream for one conversation. For a long recording that was offloaded, the events held in durable storage are reassembled with the inline head so the stream plays end to end. Feed session_replay.events to an rrweb player to replay the session.

curl https://api.orbit.devotel.io/api/v1/session-replay/conv_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "session_replay": {
      "recording_id": "rec_9f2a",
      "status": "ended",
      "visitor_id": "vis_77c1",
      "start_url": "https://shop.example.com/checkout",
      "started_at": "2026-06-18T14:02:11.000Z",
      "ended_at": "2026-06-18T14:07:53.000Z",
      "event_count": 1840,
      "size_bytes": 612344,
      "truncated": false,
      "offloaded": false,
      "total_event_count": 1840,
      "total_size_bytes": 612344,
      "events": [
        { "type": 4, "data": { "href": "https://shop.example.com/checkout" }, "timestamp": 1781792531000 }
      ]
    }
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:09:30.000Z" }
}

session_replay is null when the conversation exists but carries no recording. Requesting a conversation that doesn’t exist in your account returns 404 NOT_FOUND. A malformed conversationId returns 422 VALIDATION_ERROR. Each event in events is a raw rrweb event — type (the rrweb event type), data (the opaque rrweb payload, passed straight through to the player), and timestamp (epoch milliseconds). Orbit never interprets the payload; it only stores and replays it.

Delete a recording

Removes the recording from the conversation. The conversation and its messages are untouched — only the replay is erased, including any events held in durable storage. The call is idempotent, so a privacy or right-to-erasure workflow can retry it safely. Returns 404 NOT_FOUND if the conversation isn’t in your account.

curl -X DELETE https://api.orbit.devotel.io/api/v1/session-replay/conv_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": { "deleted": true },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:10:00.000Z" }
}

Privacy masking policy

Session replay records the visitor’s DOM, which can include data the visitor typed. The masking policy decides what the capture client redacts in the visitor’s browser, before any events are uploaded — so masked content never leaves the page. The policy is account-wide and reaches new capture sessions on the next widget session bootstrap; it does not touch existing recordings or the delete path. The default posture is fail-closed: with no policy configured, every input value is masked and built-in PII heuristics are on. You must explicitly relax masking.

Field	Type	Default	Meaning
`mask_all_inputs`	boolean	`true`	Mask every `<input>`, `<textarea>`, and `<select>` value before upload.
`mask_text_selectors`	string[]	`[]`	CSS selectors whose visible text is replaced with asterisks — for rendered free-text PII that isn’t an input.
`block_selectors`	string[]	`[]`	CSS selectors whose subtree is never serialized at all — a hard cut for highly sensitive regions like payment iframes or ID images.
`mask_pii_default`	boolean	`true`	Apply the recorder’s built-in heuristic masking for elements marked sensitive (the `.rr-mask` class or `data-rr-mask` attribute).

Each selector entry is a single CSS selector, trimmed and non-empty (max 200 characters); up to 200 entries are allowed in each selector list.

Get the policy

curl https://api.orbit.devotel.io/api/v1/session-replay/privacy \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "privacy": {
      "mask_all_inputs": true,
      "mask_text_selectors": [],
      "block_selectors": [],
      "mask_pii_default": true
    }
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:11:00.000Z" }
}

Update the policy

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
  }'

The response echoes the stored policy. Every field is optional and defaults to the fail-closed value, so a partial body only relaxes what you name. An invalid body returns 422 VALIDATION_ERROR.

API Reference

All Endpoints

Session Replay API

Session Replay API

List recordings

Fetch a recording for playback

Delete a recording

Privacy masking policy

Get the policy

Update the policy

See also

​Session Replay API

​List recordings

​Fetch a recording for playback

​Delete a recording

​Privacy masking policy

​Get the policy

​Update the policy

​See also

Session Replay API

List recordings

Fetch a recording for playback

Delete a recording

Privacy masking policy

Get the policy

Update the policy

See also