Co-browse API

Co-browse is the real-time twin of session replay. When a customer is stuck on your site, they start a co-browse session from the native chat widget; a support agent then joins from the inbox to watch the customer’s live page and, when the customer grants control, highlight elements, scroll, and assist with form fields. The page DOM is mirrored over a data channel — it is not a screen share, so off-screen content the agent was never shown is never transmitted, and the visitor can revoke at any time. This page documents the operator half: reading the session state, joining the live session, ending it, configuring the capture-time privacy policy, and sending guided-control packets. The visitor starts and ends co-browse from the widget runtime — those calls are authenticated with the visitor’s widget token and are not part of this API key surface. Base path: /api/v1/cobrowse Authentication: API key (X-API-Key) or session JWT. Scopes & roles:

Reads (GET) require the conversations:read scope.
Writes — joining a session, ending it, updating the privacy policy, and sending a control packet — require the conversations:write scope and an owner, admin, or developer role.

Method	Path	Purpose
`GET`	`/api/v1/cobrowse/{conversationId}`	Read the current co-browse session state
`POST`	`/api/v1/cobrowse/{conversationId}/join`	Join the live session and mint an agent token
`POST`	`/api/v1/cobrowse/{conversationId}/end`	End the session from the agent side
`GET`	`/api/v1/cobrowse/privacy`	Read the tenant’s capture-time privacy/masking policy
`PUT`	`/api/v1/cobrowse/privacy`	Update the tenant’s capture-time privacy/masking policy
`POST`	`/api/v1/cobrowse/{conversationId}/control`	Send a guided-control packet (highlight / scroll / form-fill)

A session is keyed by its conversationId — the conversation it belongs to. Sessions are tenant-scoped: you only ever see sessions on your own account’s conversations.

Using the SDKs

Prefer the typed client, but this page’s endpoint has no helper yet — the generic request() keeps auth/retries and the { data, meta } envelope identical:

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const { data } = await orbit.request<unknown>(
  "GET",
  "/cobrowse/sessions"
);

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/cobrowse/sessions")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

The session object

Every endpoint returns the current session under cobrowse, or null when the conversation has never started one.

Field	Type	Meaning
`session_id`	string	Identifier for this co-browse session.
`status`	string	`requested` (the visitor started it, no agent yet), `active` (an agent has joined), or `ended`.
`room_name`	string	The data-channel room both parties join. Bound to the account, conversation, and session, so a token can never be replayed against another conversation.
`visitor_id`	string \| null	The widget visitor that initiated the session.
`control`	boolean	The visitor’s standing consent for agent-side guidance. When `false`, an agent can only observe.
`requested_at`	string	ISO 8601 timestamp the visitor initiated the session.
`started_at`	string \| null	ISO 8601 timestamp the agent first joined, or `null` before then.
`ended_at`	string \| null	ISO 8601 timestamp the session ended, or `null` while live.
`ended_by`	string \| null	`visitor`, `agent`, or `system` — who ended it.
`agent_user_id`	string \| null	The operator currently on the session, if any.

Read the session state

Returns the current co-browse session stamped on the conversation, or null when no session has been started. The inbox detail panel polls this to decide whether to show the “Co-browse available” or “Co-browse live” affordance.

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

{
  "data": {
    "cobrowse": {
      "session_id": "cobrowse_9f2a",
      "status": "requested",
      "room_name": "cobrowse:org_123:conv_abc123:cobrowse_9f2a",
      "visitor_id": "vis_77c1",
      "control": false,
      "requested_at": "2026-06-18T14:02:11.000Z",
      "started_at": null,
      "ended_at": null,
      "ended_by": null,
      "agent_user_id": null
    }
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-06-18T14:02:30.000Z"
  }
}

cobrowse is null when the conversation exists but carries no session. Requesting a conversation that isn’t in your account returns 404 NOT_FOUND. A malformed conversationId returns 422 VALIDATION_ERROR.

Join the session

Mints a data-channel join token for the agent so they can view — and, when the visitor granted control, guide — the customer’s live browser session. The call flips the session to active and stamps the agent and start time. Pass control: true to request guided control. The effective grant is the AND of your request and the visitor’s stored consent: if the visitor joined observe-only, the session can never be escalated to guided control, regardless of this flag. The grant is enforced when the token is minted, not just in the UI.

curl -X POST https://api.orbit.devotel.io/api/v1/cobrowse/conv_abc123/join \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "control": true }'

The body is optional; control defaults to false (observe-only).

{
  "data": {
    "token": "ey...",
    "ws_url": "wss://media.orbit.devotel.io",
    "room_name": "cobrowse:org_123:conv_abc123:cobrowse_9f2a",
    "session_id": "cobrowse_9f2a",
    "control": true,
    "role": "agent",
    "expires_in": 1800,
    "cobrowse": {
      "session_id": "cobrowse_9f2a",
      "status": "active",
      "room_name": "cobrowse:org_123:conv_abc123:cobrowse_9f2a",
      "visitor_id": "vis_77c1",
      "control": true,
      "requested_at": "2026-06-18T14:02:11.000Z",
      "started_at": "2026-06-18T14:03:05.000Z",
      "ended_at": null,
      "ended_by": null,
      "agent_user_id": "user_88ad"
    }
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:03:05.000Z" }
}

Use token and ws_url to connect to the room with the orbit-media client SDK. The token expires after expires_in seconds (30 minutes); the SDK re-mints on reconnect by calling this endpoint again, which is idempotent on an already-active session — it re-stamps the agent without resetting started_at. control in the response is the effective grant after the visitor’s consent ceiling is applied.

Status	Code	When
`404`	`NOT_FOUND`	The conversation isn’t in your account.
`404`	`COBROWSE_NOT_ACTIVE`	No joinable session — the visitor hasn’t started co-browsing, or the previous session ended. Ask the visitor to start it from the chat widget.
`422`	`VALIDATION_ERROR`	Malformed `conversationId` or join body.
`503`	`COBROWSE_UNAVAILABLE`	The co-browse media service is not configured on this deployment.

End the session

Ends the co-browse session from the agent side: status becomes ended, with ended_at and ended_by: "agent" stamped. The call is idempotent — ending an already-ended session is a no-op and returns the same record. The visitor can independently end from the widget; either side ending stops the data room. To start co-browsing again, the visitor must re-initiate from the widget so consent is re-confirmed.

curl -X POST https://api.orbit.devotel.io/api/v1/cobrowse/conv_abc123/end \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "cobrowse": {
      "session_id": "cobrowse_9f2a",
      "status": "ended",
      "room_name": "cobrowse:org_123:conv_abc123:cobrowse_9f2a",
      "visitor_id": "vis_77c1",
      "control": true,
      "requested_at": "2026-06-18T14:02:11.000Z",
      "started_at": "2026-06-18T14:03:05.000Z",
      "ended_at": "2026-06-18T14:11:40.000Z",
      "ended_by": "agent",
      "agent_user_id": "user_88ad"
    }
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:11:40.000Z" }
}

Returns 404 NOT_FOUND when the conversation — or its session — isn’t in your account.

Get/update the capture-time privacy policy

Co-browse mirrors the visitor’s live DOM to the agent’s browser over a data channel. The privacy policy decides what the capture client masks in the visitor’s page before it publishes a DOM packet, and doubles as the server-side guard on the control endpoint below — a selector or input type the policy blocks can never be captured or remotely controlled. The policy is default-deny: with nothing configured, every input is masked and tel, email, and cc input types are blocked. input[type="password"] and a small set of built-in payment/card selectors are always blocked and cannot be relaxed by this endpoint, regardless of what you send.

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

{
  "data": {
    "privacy": {
      "mask_all_inputs": true,
      "allowlist_selectors": [],
      "block_selectors": [],
      "blocked_input_types": ["tel", "email", "cc"],
      "unmask_on_visitor_click": false
    }
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:02:30.000Z" }
}

Field	Type	Meaning
`mask_all_inputs`	boolean	Mask every `<input>` / `<textarea>` / `<select>` value before publishing a DOM packet. Defaults to `true`.
`allowlist_selectors`	string[]	When `mask_all_inputs` is `false`, only these CSS selectors publish unmasked; everything else stays masked. Ignored while `mask_all_inputs` is `true`.
`block_selectors`	string[]	Tenant-added CSS selectors whose subtree is never published and can never be targeted by a control packet. Merged with (never replaces) the built-in always-blocked selectors.
`blocked_input_types`	string[]	Input types to block by type, from `tel`, `email`, `cc`. `password` is always blocked and is not a member of this list.
`unmask_on_visitor_click`	boolean	Lets the visitor click a masked field on their own screen to reveal it locally. Never changes what is published to the agent.

To update the policy:

curl -X PUT https://api.orbit.devotel.io/api/v1/cobrowse/privacy \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mask_all_inputs": true,
    "block_selectors": [".payment-panel"],
    "blocked_input_types": ["tel", "email", "cc"],
    "unmask_on_visitor_click": false
  }'

The response echoes the merged policy under data.privacy. Selectors round-trip verbatim; omitted fields fall back to their default-deny values, not to whatever was previously stored. The change takes effect on the next co-browse session bootstrap for both the visitor and the joining agent — it does not retroactively change a session already in progress. PUT requires the conversations:write scope and an owner, admin, or developer role, same as joining or ending a session. A malformed body returns 422 VALIDATION_ERROR.

Send a guided-control packet

Broadcasts an agent-initiated highlight, scroll, or form_fill action into the co-browse data room so the visitor’s browser can render it. The target selector (and, for form_fill, the input_type) is checked against the tenant’s privacy policy above before anything is sent — a packet aimed at a blocked selector, an always-blocked region, or a password field is rejected and never reaches the visitor. Sending control requires the visitor to have granted control on this session; requesting it does not escalate an observe-only session.

curl -X POST https://api.orbit.devotel.io/api/v1/cobrowse/conv_abc123/control \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "form_fill",
    "selector": "#shipping-city",
    "input_type": "text",
    "value": "Austin"
  }'

Field	Type	Required	Meaning
`action`	string	yes	One of `highlight`, `scroll`, `form_fill`.
`selector`	string	yes	CSS selector of the DOM node being targeted.
`input_type`	string	for `form_fill`	The target input’s type, so the server can enforce the input-type hard floor (e.g. `password`) even when the selector alone doesn’t reveal it.
`value`	string	for `form_fill`	The text to write into the visitor’s field. Ignored for `highlight` / `scroll`.

A successful call returns 204 No Content — the packet was broadcast to the room.

Status	Code	When
`404`	`COBROWSE_NOT_ACTIVE`	No live co-browse session for this conversation.
`403`	`COBROWSE_CONTROL_NOT_GRANTED`	The visitor has not granted guided control for this session — observe-only.
`403`	`COBROWSE_CONTROL_BLOCKED`	The packet’s selector or input type falls inside a privacy-protected region (a tenant `block_selectors` entry, a blocked input type, or the always-blocked hard floor). This attempt is audit-logged.
`422`	`VALIDATION_ERROR`	Malformed `conversationId` or control body.
`502`	`COBROWSE_CONTROL_FAILED`	The packet could not be delivered to the data room.
`503`	`COBROWSE_UNAVAILABLE`	The co-browse media service is not configured on this deployment.

Every accepted form_fill is audit-logged; highlight and scroll are not, to keep the audit trail focused on packets that write a value into the visitor’s page.

API Reference

All Endpoints

Co-browse API: join and end live browser sessions

Co-browse API

Using the SDKs

The session object

Read the session state

Join the session

End the session

Get/update the capture-time privacy policy

Send a guided-control packet

See also

​Co-browse API

​Using the SDKs

​The session object

​Read the session state

​Join the session

​End the session

​Get/update the capture-time privacy policy

​Send a guided-control packet

​See also

Co-browse API

Using the SDKs

The session object

Read the session state

Join the session

End the session

Get/update the capture-time privacy policy

Send a guided-control packet

See also