# Co-Browsing API Documentation
> Co-Browsing API allows developers to build co-browsing and instant screen sharing into any product.
Source: https://cobrowsingapi.com/docs
## Table of contents
- [Getting Started](https://cobrowsingapi.com/docs/getting-started.md)
- [How It Works](https://cobrowsingapi.com/docs/getting-started/how-it-works.md)
- [What Data Does Upscope Store?](https://cobrowsingapi.com/docs/getting-started/what-data-does-upscope-store.md)
- [SDK](https://cobrowsingapi.com/docs/sdk.md)
- [Web SDK](https://cobrowsingapi.com/docs/sdk/web.md)
- [Installation](https://cobrowsingapi.com/docs/sdk/web/installation.md)
- [Configuration Options](https://cobrowsingapi.com/docs/sdk/web/configuration-options.md)
- [SDK Functions](https://cobrowsingapi.com/docs/sdk/web/sdk-functions.md)
- [Listening for Events](https://cobrowsingapi.com/docs/sdk/web/listening-for-events.md)
- [Multi-Language Support](https://cobrowsingapi.com/docs/sdk/web/translations.md)
- [iOS SDK](https://cobrowsingapi.com/docs/sdk/ios.md)
- [Installation](https://cobrowsingapi.com/docs/sdk/ios/installation.md)
- [Configuration Options](https://cobrowsingapi.com/docs/sdk/ios/configuration-options.md)
- [SDK Functions](https://cobrowsingapi.com/docs/sdk/ios/sdk-functions.md)
- [Listening for Events](https://cobrowsingapi.com/docs/sdk/ios/listening-for-events.md)
- [Full Device Screen Sharing](https://cobrowsingapi.com/docs/sdk/ios/full-device-screen-sharing.md)
- [Android SDK](https://cobrowsingapi.com/docs/sdk/android.md)
- [Installation](https://cobrowsingapi.com/docs/sdk/android/installation.md)
- [Configuration Options](https://cobrowsingapi.com/docs/sdk/android/configuration-options.md)
- [SDK Functions](https://cobrowsingapi.com/docs/sdk/android/sdk-functions.md)
- [Listening for Events](https://cobrowsingapi.com/docs/sdk/android/listening-for-events.md)
- [Full Device Screen Sharing](https://cobrowsingapi.com/docs/sdk/android/full-device-screen-sharing.md)
- [Flutter SDK](https://cobrowsingapi.com/docs/sdk/flutter.md)
- [Installation](https://cobrowsingapi.com/docs/sdk/flutter/installation.md)
- [Configuration Options](https://cobrowsingapi.com/docs/sdk/flutter/configuration-options.md)
- [SDK Functions](https://cobrowsingapi.com/docs/sdk/flutter/sdk-functions.md)
- [Listening for Events](https://cobrowsingapi.com/docs/sdk/flutter/listening-for-events.md)
- [Full Device Screen Sharing](https://cobrowsingapi.com/docs/sdk/flutter/full-device-screen-sharing.md)
- [React Native SDK](https://cobrowsingapi.com/docs/sdk/react-native.md)
- [Installation](https://cobrowsingapi.com/docs/sdk/react-native/installation.md)
- [Configuration Options](https://cobrowsingapi.com/docs/sdk/react-native/configuration-options.md)
- [SDK Functions](https://cobrowsingapi.com/docs/sdk/react-native/sdk-functions.md)
- [Listening for Events](https://cobrowsingapi.com/docs/sdk/react-native/listening-for-events.md)
- [Full Device Screen Sharing](https://cobrowsingapi.com/docs/sdk/react-native/full-device-screen-sharing.md)
- [Element Masking](https://cobrowsingapi.com/docs/sdk/element-masking.md)
- [Identifying the Visitor](https://cobrowsingapi.com/docs/sdk/identifying-the-visitor.md)
- [The Lookup Code](https://cobrowsingapi.com/docs/sdk/the-lookup-code.md)
- [REST API](https://cobrowsingapi.com/docs/rest-api.md)
- [Authentication](https://cobrowsingapi.com/docs/rest-api/authentication.md)
- [API Endpoints](https://cobrowsingapi.com/docs/rest-api/api-endpoints.md)
- [Object Types](https://cobrowsingapi.com/docs/rest-api/object-types.md)
- [Better Searching](https://cobrowsingapi.com/docs/rest-api/better-searching.md)
- [Embedded Session Control](https://cobrowsingapi.com/docs/rest-api/embedded-session-control.md)
- [Embedding with the Viewer SDK](https://cobrowsingapi.com/docs/rest-api/viewer-sdk.md)
- [On Premise](https://cobrowsingapi.com/docs/on-premise.md)
- [Quick Start](https://cobrowsingapi.com/docs/on-premise/quick-start.md)
- [REST API (on premise)](https://cobrowsingapi.com/docs/on-premise/rest-api-on-premise.md)
- [Presentation Sharing](https://cobrowsingapi.com/docs/presentation-sharing.md)
- [SDK Integration](https://cobrowsingapi.com/docs/presentation-sharing/sdk-integration.md)
- [Getting Public Links](https://cobrowsingapi.com/docs/presentation-sharing/getting-public-link.md)
- [Salesforce Visualforce Example](https://cobrowsingapi.com/docs/presentation-sharing/salesforce-example.md)
---
## Getting Started
Source: https://cobrowsingapi.com/docs/getting-started
### How It Works
Source: https://cobrowsingapi.com/docs/getting-started/how-it-works
Co-Browsing API allows one person (the **Agent**) to view the screen of another person (the **Visitor**) in real-time.
#### Key Concepts
##### Visitor
The person whose screen is being shared. The Visitor has the SDK installed on their web page or app, and their screen is captured and streamed to the Agent.
##### Agent
The person viewing the Visitor's screen. Agents typically access the session through your dashboard or a custom integration using the REST API.
##### Session
A screen sharing session between one Visitor and one or more Agents. Sessions are temporary and end when either party disconnects.
#### Integration Steps
##### 1. Install the SDK
Add the SDK to the pages or app screens you want to be shareable. See the [SDK documentation](https://cobrowsingapi.com/docs/sdk.md) for platform-specific installation guides.
##### 2. Identify the Visitor
To connect an Agent to a specific Visitor, you need a way to identify them. You have several options:
| Method | Description |
|--------|-------------|
| **Short ID** | Get the Upscope-generated ID via `Upscope('getShortId')` and pass it to your Agent-side code |
| **Unique ID** | Use your own identifier (e.g., user ID from your database) by passing it as `uniqueId` |
| **Integration ID** | Use an ID from another platform (e.g., Intercom, Zendesk) via `integrationIds` |
| **Lookup Code** | Have the Visitor read a [4-digit code](https://cobrowsingapi.com/docs/sdk/the-lookup-code.md) to the Agent over the phone |
If you are using anything other than the Short ID to identify the Visitor, first use the [search endpoint](https://cobrowsingapi.com/docs/rest-api/api-endpoints.md#searching-for-visitors) to get their Short ID.
##### 3. Start a Session
Once you have a Visitor identifier, create a session using the REST API:
1. Call the [start session endpoint](https://cobrowsingapi.com/docs/rest-api/api-endpoints.md#generating-a-link-to-start-screen-sharing-with-a-visitor) with the Visitor's Short ID
2. Receive a `watch_url` in the response
3. Redirect the Agent's browser to this URL
```
POST /v1.3/visitors/visitor_abc/watch_url
{
"agent": {
"id": "viewer_123"
}
}
```
#### What's Next?
- [Install the SDK](https://cobrowsingapi.com/docs/sdk.md) on your web pages or mobile app
- Set up [Visitor identification](https://cobrowsingapi.com/docs/sdk/identifying-the-visitor.md) to find users
- Explore the [REST API](https://cobrowsingapi.com/docs/rest-api.md) for custom integrations
### What Data Does Upscope Store?
Source: https://cobrowsingapi.com/docs/getting-started/what-data-does-upscope-store
Here's a breakdown of the data that Co-Browsing API stores for co-browsing and how long it is retained.
**Data Retention Notice:**
This is not a warranty that data will be kept. Unless specified in your Agreement, data might be deleted earlier at any time without notice.
#### Definitions
| Term | Definition |
|------|------------|
| **Visitor** | Person who shares their screen (has the SDK installed) |
| **Agent** | Person who views a Visitor's screen |
| **Session** | A screen sharing connection between Visitor and Agent(s) |
| **Session Content** | The actual content being shared during a Session |
| **Short ID** | Unique identifier assigned by Upscope to a Visitor |
| **Unique ID** | Identifier you provide for a Visitor |
**Cloud:**
When using Upscope Cloud, data is processed and stored across our infrastructure:
- **Edge** — Datacenter closest to the Visitor (or your chosen region)
- **USA** — Main datacenter in the United States
##### Data Never Sent to Upscope
This data stays in the Visitor's browser and is never transmitted.
| Data | Notes |
|------|-------|
| Page content before Session starts | Only sent once Session is initiated and authorized |
| Masked content | Elements with `no-upscope` class or specified in settings |
| Cookies and browser storage | Never accessed |
| Console content (if disabled) | Only sent if console access is enabled AND Session is active |
##### Data Processed But Not Stored
| Data | Location | Notes |
|------|----------|-------|
| Session HTML content | Edge | During active Session only |
| Audio streams | Edge | If audio is enabled |
| Full screen sharing | Edge | If full screen sharing is enabled |
| Console content | Edge | If console access is enabled, during Session only |
| Agent instructions (highlights, clicks, scroll) | Edge | During active Session only |
| CRM conversation content | USA | If using CRM integrations |
##### Data Cached (24 Hours)
| Data | Location |
|------|----------|
| Public assets (stylesheets, images, fonts) | Edge |
##### Data Stored (1 Week)
| Data | Location | Notes |
|------|----------|-------|
| Server request logs | USA | Redacted, DevOps access only |
| Application telemetry | USA | How users interact with Upscope |
| Sample connection logs | USA | Random sample for debugging |
##### Visitor Data Stored (30 Days)
Stored until 30 days after Visitor's last activity, manual deletion, or account deletion.
| Data | Location | Notes |
|------|----------|-------|
| Last IP address | Edge | |
| Last page view (timestamp, URL) | Edge | |
| Country and city | Edge | Derived from IP, not GPS |
| Device info (browser, device type) | Edge | |
| Online status | Edge | |
| Unique ID | Edge | If provided |
| Identities (name, email) | Edge | If provided |
| REST API data | USA | Synced from Edge for API access |
**High-volume accounts** may have Visitor data auto-deleted after 24 hours.
##### Data Stored Until Account Deletion
| Data | Location | Notes |
|------|----------|-------|
| Visitor data from Sessions | USA | IP, Unique ID, identities |
| REST API call logs | USA | Redacted |
| Session recordings (MP4) | Edge | If recording enabled |
| Webhook logs | USA | Without request body |
| Usage statistics | USA | Session counts, lengths (no content) |
| Credit card details | USA | |
| OAuth keys | USA | For integrations |
##### Data Stored 1 Year After Account Deletion
| Data | Location |
|------|----------|
| Session history | USA |
| Agent account details | USA |
| Account settings changes | USA |
##### Data Stored Indefinitely
| Data | Location |
|------|----------|
| Contracts | USA |
| Billing history and details | USA |
| Communications with Upscope | USA |
**On-Premise:**
When using an on-premise installation, the co-browsing bridge server runs within your infrastructure. This significantly reduces data sent to Upscope.
- **Your Infrastructure** — Where your on-premise server is hosted
- **USA** — Upscope's main datacenter (limited data only)
##### Data Never Sent to Upscope
This data stays in the Visitor's browser and is never transmitted.
| Data | Notes |
|------|-------|
| Page content before Session starts | Only sent once Session is initiated and authorized |
| Masked content | Elements with `no-upscope` class or specified in settings |
| Cookies and browser storage | Never accessed |
| Console content (if disabled) | Only sent if console access is enabled AND Session is active |
##### Data Processed But Not Stored
| Data | Location | Notes |
|------|----------|-------|
| Session HTML content | Your Infrastructure | During active Session only |
| Audio streams | Your Infrastructure | If audio is enabled |
| Full screen sharing | Your Infrastructure | If full screen sharing is enabled |
| Console content | Your Infrastructure | If console access is enabled, during Session only |
| Agent instructions (highlights, clicks, scroll) | Your Infrastructure | During active Session only |
##### Data Cached (24 Hours)
| Data | Location |
|------|----------|
| Public assets (stylesheets, images, fonts) | Your Infrastructure |
##### Visitor Data Stored (30 Days)
Stored on your infrastructure until 30 days after Visitor's last activity or manual deletion.
| Data | Location | Notes |
|------|----------|-------|
| Last IP address | Your Infrastructure | |
| Last page view (timestamp, URL) | Your Infrastructure | |
| Country and city | Your Infrastructure | Derived from IP, not GPS |
| Device info (browser, device type) | Your Infrastructure | |
| Online status | Your Infrastructure | |
| Unique ID | Your Infrastructure | If provided |
| Identities (name, email) | Your Infrastructure | If provided |
**On-Premise REST API:**
Use the on-premise REST API to keep Visitor data within your infrastructure. Using the Cloud REST API would sync data to Upscope's USA datacenter.
##### Data Stored Until Account Deletion
| Data | Location | Notes |
|------|----------|-------|
| Session recordings (MP4) | Your Infrastructure | If recording enabled |
**The following is still stored by Upscope Cloud:**
| Data | Location | Notes |
|------|----------|-------|
| Webhook logs | USA | Without request body |
| Usage statistics | USA | Session counts, lengths (no content) |
| Credit card details | USA | |
| OAuth keys | USA | For integrations |
##### Data Stored 1 Year After Account Deletion
| Data | Location |
|------|----------|
| Agent account details | USA |
| Account settings changes | USA |
##### Data Stored Indefinitely
| Data | Location |
|------|----------|
| Contracts | USA |
| Billing history and details | USA |
| Communications with Upscope | USA |
## SDK
Source: https://cobrowsingapi.com/docs/sdk
Co-Browsing API needs to be installed on any web page or app you want to be shared.
Choose your platform to get started with the SDK:
- **[Web](https://cobrowsingapi.com/docs/sdk/web/)** - JavaScript SDK for web applications
- **[iOS](https://cobrowsingapi.com/docs/sdk/ios/)** - Native iOS SDK for Swift/SwiftUI apps
- **[Android](https://cobrowsingapi.com/docs/sdk/android/)** - Native Android SDK for Kotlin apps
- **[Flutter](https://cobrowsingapi.com/docs/sdk/flutter/)** - Flutter SDK for cross-platform apps
- **[React Native](https://cobrowsingapi.com/docs/sdk/react-native/)** - React Native SDK for cross-platform apps
Once installed, check out these guides:
- **[Identifying the Visitor](https://cobrowsingapi.com/docs/sdk/identifying-the-visitor.md)** - Set user identities for agent search
- **[Element Masking](https://cobrowsingapi.com/docs/sdk/element-masking.md)** - Hide sensitive content during sessions
- **[The Lookup Code](https://cobrowsingapi.com/docs/sdk/the-lookup-code.md)** - Quick connection codes for agents
### Web SDK
Source: https://cobrowsingapi.com/docs/sdk/web
#### Installation
Source: https://cobrowsingapi.com/docs/sdk/web/installation
##### Overview
Co-Browsing API can be installed using one of the following methods:
1. **Installing via Script Tag** - Directly add the code snippet to your web page.
2. **Installing via NPM** - Ideal for projects using a Node.js environment.
3. **Installing via React** - For React-based applications.
Choose the method that best fits your project's requirements.
**Installing via Script Tag:**
You'll find your installation code within your Co-Browsing API dashboard. Simply add the code anywhere on your webpage, or, if you prefer, add it to a JavaScript file by removing the `` tags from the code.
**Recommendation:** Make sure that the code loads as fast as possible by adding it as one of the first things that execute on the page.
**Warning:**
While you can install Co-Browsing API through Google Tag Manager or Segment, the preferred method is to paste the installation code directly on your website, as this will result in faster load times.
Installation remains the same whatever front end framework you use. Co-Browsing API works fine with React, Angular, and most other modern JavaScript frameworks. All you need to do is add the code to the page.
**Installing via NPM:**
1. Install the SDK
```shell
npm install --save @upscopeio/sdk
```
2. Import the Upscope Object
```javascript
import Upscope from '@upscopeio/sdk';
```
3. Initialize
```javascript
Upscope("init", {
apiKey: ""
});
```
**Note:** You can use the Upscope object wherever required, and call the same functions that are available with the regular installation. Initialization (`init`) needs to be called first and must include your public API key.
###### Public API Key
You can find yours in the installation page of your Co-Browsing API dashboard.
###### Pinning a Specific Version
By default, the package downloads the latest version of the Co-Browsing API code, so you are always up to date without reinstalling. If you prefer to run the exact version you installed from npm, import from `@upscopeio/sdk/static` instead:
```javascript
import Upscope from '@upscopeio/sdk/static';
```
The static import works exactly like the default one, but no remote code is downloaded: only your account configuration is fetched, and the Co-Browsing API code that runs is the one bundled with the installed package version. This also makes it suitable for environments that disallow remote code, such as Manifest V3 browser extensions.
**Get notified about new versions:**
When pinning a version, updates only reach your users when you update the package and redeploy. Add your email address on the installation page of your Co-Browsing API dashboard to be notified when a new version is released.
**Installing via React:**
###### Installation
To incorporate Co-Browsing API into your React project, first install the React-specific package using npm:
```shell
npm install --save @upscopeio/react
```
Import the `UpscopeProvider` component and wrap your main application component with it.
```javascript
import { UpscopeProvider } from '@upscopeio/react';
{/* rest of your app */}
```
**Entire page shared:**
Co-Browsing API will share the entire page, regardless of where the `UpscopeProvider` is added in your component hierarchy. To only share a specific part of your content, see [Sharing Only Part of the Page](#sharing-only-part-of-the-page).
###### Pinning a Specific Version
By default, the package downloads the latest version of the Co-Browsing API code, so you are always up to date without reinstalling. If you prefer to run the exact version you installed from npm, import from `@upscopeio/react/static` instead:
```javascript
import { UpscopeProvider } from '@upscopeio/react/static';
```
All the other exports (`useUpscope`, `Masked`, `NoRemoteControl`) are available from the same path. The static import works exactly like the default one, but no remote code is downloaded: only your account configuration is fetched, and the Co-Browsing API code that runs is the one bundled with the installed package version. This also makes it suitable for environments that disallow remote code, such as Manifest V3 browser extensions.
**Get notified about new versions:**
When pinning a version, updates only reach your users when you update the package and redeploy. Add your email address on the installation page of your Co-Browsing API dashboard to be notified when a new version is released.
###### Configuration
###### Public API Key
You can find yours in the installation page of your Co-Browsing API dashboard.
The `UpscopeProvider` accepts props that you can use for additional configuration settings. These settings are similar to the ones you would specify using the `init` function in the standard SDK. For example, to specify a unique identifier for a user, you can do:
```javascript
{/* Your application code here */}
```
###### Using Functionality in Components
To use Co-Browsing API features in your individual components, you can use the `useUpscope` hook:
```javascript
import { useUpscope } from '@upscopeio/react';
function YourComponent() {
const {
Upscope, // SDK object
shortId, // Connected shortId or undefined
getLookupCode, // Asynchronous function to get lookup code
listen, // Event listener function
reset, // Reset function
isSharing // Boolean indicating active session
} = useUpscope();
// Your component logic here
}
```
###### Additional Utilities: Masking and Disabling Remote Control
Co-Browsing API offers utility components to mask sensitive data and disable remote control on specific UI elements.
To mask sensitive information:
```javascript
import { Masked, NoRemoteControl } from '@upscopeio/react';
function YourComponent() {
return (
<>
{/* Sensitive Info */}
{/* Control Elements */}
);
}
```
To disable remote control on a particular element:
```javascript
import { NoRemoteControl } from '@upscopeio/react';
function YourComponent() {
return (
<>
);
}
```
By following these steps and guidelines, you can fully integrate Co-Browsing API into your React application and leverage its features effectively.
##### Testing on a Local or Staging Environment
When you test on your own computer or in a staging environment that is not publicly accessible, you might notice some odd rendering issues.
This is because our proxy server is unable to reach your CSS and media files and therefore can't properly edit them to render on the Agent side.
We try to automatically detect if you are on a URL that looks like localhost (e.g. `http://127.0.0.1/*`, `http://localhost/*`, etc.), and send the content of CSS files directly from the Visitor's browser to the Agent's browser.
You can add more URLs for browser proxying in your dashboard settings.
##### Iframe Support
Co-Browsing API will work with iframes without you needing to do anything when these are hosted on the same domain. This means that the part of the URL between `://` and the first `/` is exactly the same (i.e. `app.acme.com` and `dashboard.acme.com` are considered different domains).
In this case, you only need to add the script to the outermost frame (i.e. the parent page).
You don't need to do anything to make Co-Browsing API work cross-domain if iframes aren't involved.
###### Different Domains
To make Co-Browsing API work when you have iframes on different domains/subdomains, you'll need to add the code to all the iframes. This is the code you get from your dashboard's installation page.
The iframes will connect automatically.
**Using the SDK:**
The code will behave differently in the iframe, and you can't use SDK within it.
That means that if you want to identify the user you'll need to do so in the outermost frame.
###### Sharing Only Part of the Page
By default, Co-Browsing API shares the entire page. If you only want to share a specific part of your content (for example, a document viewer or a preview area), place that content in a **same-origin iframe** and pass the iframe's `contentWindow` as the `sharingRoot` configuration option. Only the iframe's document will be shared — everything outside it stays private.
```html
```
```javascript
const iframe = document.querySelector('#shared-content');
iframe.addEventListener('load', () => {
Upscope('init', {
sharingRoot: iframe.contentWindow
});
});
```
Make sure the iframe has finished loading before initializing, as shown above, so that `contentWindow` points to the final document.
If you're using React, pass `sharingRoot` as a prop to the `UpscopeProvider`, enabling it once the iframe is available:
```javascript
function SharedContent() {
const [contentWindow, setContentWindow] = useState(null);
return (
```
You can start listening for events by doing:
```javascript
const upscopeWindow = document.getElementById('upscope-iframe').contentWindow;
window.addEventListener('message', event => {
if (!event.source || event.source !== upscopeWindow)
return;
const {data} = event;
// ... deal with the Co-Browsing API event
console.log('Co-Browsing API event type', data.type);
});
```
**Sending instructions:**
If you have embedded Co-Browsing API within your application like this:
```html
```
You can send instructions by doing:
```javascript
const upscopeWindow = document.getElementById('upscope-iframe').contentWindow;
upscopeWindow.postMessage({
action: "name",
// ... other parameters
}, '*');
```
#### Events
Events will be received in this format:
```javascript
{
"type": "eventType",
// ...parameters
}
```
The following events are sent by the iframe to the parent frame:
| Type | Parameters | Description |
|-----------------------------|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| `upscope.sessionState.update` | `state: EmbeddedSessionState` | Fired whenever the session state changes. Contains a full snapshot — see [Session State](#session-state) below. This is the primary event to listen for. |
| `sessionEnded` | `reason: "ended" \| "error"` | Fired when the session is terminated. `ended` — session ended normally; `error` — session ended due to an error (see the `error` event for details). |
| `customMessage` | `message: Record<string, unknown>` | Fired when the visitor's SDK sends a custom message via `Upscope('sendCustomMessage', ...)`. |
| `error` | `error: string` | Fired when a connection or remote control error occurs. Possible values: `connection:authentication`, `connection:data`, `connection:user_not_found`, `connection:user_not_online`, `connection:expired`, `connection:version_not_supported`, `remote_control:inactive`, `remote_control:element_not_allowed`, `remote_control:click_not_allowed`, `remote_control:type_not_allowed`, `remote_control:scroll_not_allowed`. |
#### Session State
Every `upscope.sessionState.update` event carries an `EmbeddedSessionState` object — a full snapshot of everything happening in the session at that moment.
| Property | Type | Description |
|---|---|---|
| `activeConnectionId` | `string \| undefined` | The ID of the visitor connection currently being viewed. A visitor can have multiple connections (e.g. multiple open tabs). Use `setActiveConnection` to switch between them. |
| `agentIdleness` | `"active" \| "willDisconnect" \| "disconnected"` | The activity state of the agent. `willDisconnect` — the agent will disconnect shortly due to inactivity. |
| `audioState` | `"off" \| "ringing" \| "accepted" \| "authorizing" \| "active"` | The current audio call state. |
| `availableModes` | `("visitor_browser" \| "visitor_screen" \| "agent_screen")[]` | The sharing modes available in the current session. |
| `color` | `string` | The current active color for the agent drawing and pointer tools. |
| `connected` | `boolean` | Whether the session is currently connected. |
| `connections` | [`Connection[]`](https://cobrowsingapi.com/docs/rest-api/object-types.md#connection) | All active visitor connections (browser tabs or app instances). Use alongside `activeConnectionId` to let the agent switch between them. |
| `controlStatus` | `"off" \| "requested" \| "granted" \| undefined` | The remote control status. `off` — the agent does not have control; `requested` — the agent has requested control and is waiting for the visitor to accept; `granted` — the agent has control. `undefined` if the session has not started. |
| `controlTool` | `"cursor" \| "drawing" \| "pointer" \| null` | The currently active agent control tool, or `null` if none is selected. |
| `currentUrl` | `string \| null` | The current URL of the active visitor connection. |
| `dataBounceSpeed` | `number` | Round-trip data latency in milliseconds. Values above 500ms indicate a slow connection. |
| `isVideoOn` | `boolean` | Whether video streaming is currently active. |
| `mode` | `"visitor_browser" \| "visitor_screen" \| "agent_screen" \| "other_agent_screen" \| undefined` | The current sharing mode. `visitor_browser` — viewing the visitor's browser tab; `visitor_screen` — viewing the visitor's full screen; `agent_screen` — this agent is sharing their screen; `other_agent_screen` — another agent is sharing their screen; `undefined` — session has not started. |
| `muted` | `boolean` | Whether the agent's audio is muted. |
| `observersCount` | `number` | The number of agents currently observing the session. |
| `sessionStatus` | `"waiting" \| "pendingRequest" \| "active" \| "snapshotReceived" \| "viewerReady" \| "terminated"` | The current session status. `waiting` — waiting for the browser to respond; `pendingRequest` — waiting for the visitor to accept; `active` — session has started; `snapshotReceived` — first frame received; `viewerReady` — **the page is visible**; `terminated` — the session has ended. |
| `size` | `{ width: number; height: number } \| undefined` | The current dimensions of the viewer in pixels. |
| `videoAgentState` | `"off" \| "authorizing:<observerId>" \| "active:<observerId>"` | Video state from the agent side. The suffix after `:` is the observer ID. |
| `videoVisitorState` | `"off" \| "ringing" \| "authorizing:<connectionId>" \| "active:<connectionId>"` | Video state from the visitor side. `ringing` — incoming video call; the suffix after `:` is the visitor's connection ID. |
| `viewerAudioAvailable` | `boolean` | Whether audio is available on the agent side. |
| `visitor` | [`Visitor?`](https://cobrowsingapi.com/docs/rest-api/object-types.md#visitor) | The visitor in the session. Property names use camelCase rather than snake_case. `undefined` if the session has not started. |
| `visitorAudioAvailable` | `boolean` | Whether audio is available on the visitor's side. |
#### Instructions
Instructions need to be sent in this format:
```javascript
{
"action": "actionName",
// ... parameters
}
```
The following instructions are available:
| Action | Parameters | Description |
|----------------------|------------------------------------------|-----------------------------------------------------------------------------|
| `endSession` | — | Terminates the session. |
| `setMode` | `mode: "draw" \| "pointer" \| "cursor" \| null` | Sets which mode the Agent is currently using. Allowed values are: `draw` — Drawing mode; `pointer` — Pointer (spotlight) mode; `cursor` — Cursor mode; `null` — No tool selected. |
| `switchColor` | `color: string?` | Changes the current Agent color. If `color` is not set, it will toggle between built-in colors. |
| `clearDrawings` | — | Clears all drawings from the Visitor's screen. Requires the `allow_draw` permission. |
| `toggleAudio` | `on: boolean` | Toggles the audio state. |
| `toggleVideo` | — | Toggles the video state. |
| `setMuted` | `muted: boolean` | Sets the muted state for audio. |
| `beginVideo` | — | Begins video streaming. |
| `endVideo` | — | Ends video streaming. |
| `forceRefresh` | — | Forces a refresh of the session. |
| `historyBack` | — | Navigates back in the session history. |
| `historyForward` | — | Navigates forward in the session history. |
| `reloadPage` | — | Reloads the current page in the session. |
| `requestControl` | — | Requests control of the session. |
| `requestFullTab` | — | Requests full tab control. |
| `runConsoleCommand` | `command: string` | Runs a console command in the session. |
| `sendCustomMessage` | `message: Record<string, unknown>` | Sends a custom message to the session. |
| `setActiveConnection` | `connectionId: string` | Switches the active visitor connection (e.g. to a different browser tab). Use `activeConnectionId` and `connections` from `EmbeddedSessionState` to get available connection IDs. |
| `setCurrentUrl` | `url: string` | Sets the current URL in the session. |
| `stopFullTab` | — | Stops full tab control. |
| `emojiConfetti` | `emoji: string` | Triggers an emoji confetti effect using the specified emoji. |
### Embedding with the Viewer SDK
Source: https://cobrowsingapi.com/docs/rest-api/viewer-sdk
Instead of opening a hosted watch link (or embedding it in an iframe), you can render the co-browsing screen natively inside your own React application with the [`@upscopeio/viewer-sdk`](https://www.npmjs.com/package/@upscopeio/viewer-sdk) package. This gives you full control over the UI around the Visitor's screen: you build the toolbar, the buttons, and the layout, and the SDK provides the screen itself plus hooks to control the Session.
Use this when you want co-browsing to feel like a native part of your product. If you just need to open a session quickly, the [secure watch link](https://cobrowsingapi.com/docs/rest-api/api-endpoints.md#generating-a-link-to-start-screen-sharing-with-a-visitor) or [embedded session control](https://cobrowsingapi.com/docs/rest-api/embedded-session-control.md) are simpler options.
#### Installation
```sh
npm install @upscopeio/viewer-sdk
```
React 18 (`react` and `react-dom`) are peer dependencies.
#### Getting a Viewer Token
The SDK authenticates with a viewer token generated by the [viewer token endpoint](https://cobrowsingapi.com/docs/rest-api/api-endpoints.md#generating-a-viewer-token-to-embed-co-browsing). The token must be requested by **your server** (the REST API key must never reach the browser) and handed to the browser right before connecting: tokens are short lived, and requesting one creates the Session.
```javascript
// On your server
const response = await fetch(`https://api.upscope.io/v1.4/visitors/${visitorId}/viewer_token`, {
body: JSON.stringify({
viewer: { id: "123", name: "Joe Smith" },
}),
headers: {
"Authorization": `Bearer ${UPSCOPE_API_KEY}`,
"Content-Type": "application/json",
},
method: "POST",
});
// Pass token, endpoint, region and short_id to your frontend
const { endpoint, region, short_id, token } = await response.json();
```
The response fields map directly onto the `ViewerProvider` props below. For on-premise accounts, `endpoint` points at your own on-premise server.
#### Rendering the Viewer
Wrap your viewer UI in a `ViewerProvider`, and render the Visitor's screen with the `Content` component:
```tsx
import { Content, ViewerProvider, useUpscopeViewer } from "@upscopeio/viewer-sdk";
function CobrowsingViewer({ endpoint, region, shortId, token }) {
return (
);
}
function Screen() {
const { connected, endSession, sessionStatus } = useUpscopeViewer();
return (
{sessionStatus !== "active" &&
Waiting for the visitor to accept...
}
{connected && endSession && }
);
}
```
##### `ViewerProvider` Props
| Prop | Type | Description |
| --- | --- | --- |
| `token` | `string` | The `token` from the viewer token endpoint. |
| `shortId` | `string` | The Visitor's short id (`short_id` in the response). |
| `region` | `string` | The region the Visitor is connected to (`region` in the response). |
| `endpoint` | `string`, optional | The server to connect to (`endpoint` in the response). Required for on-premise accounts; on cloud accounts it can be omitted and the connection is derived from `region`. |
| `idleDisconnectSeconds` | `number \| null` | Disconnect the viewer after this many seconds without interaction. Pass `null` to never disconnect for idleness. |
##### `Content` Props
`Content` renders the Visitor's screen on a canvas and forwards the selected control tool's interactions (clicks, scrolling, typing, drawing) to the Visitor.
| Prop | Type | Description |
| --- | --- | --- |
| `color` | `string` | The color used for this viewer's cursor, drawings, and pointer. |
| `controlTool` | `"cursor" \| "drawing" \| "pointer" \| null` | The active tool. `cursor` remote-controls the page, `drawing` draws on it, `pointer` highlights without interacting. `null` disables interaction. |
| `maxWidth` | `number` | Maximum width of the rendered screen, in pixels. |
| `maxHeight` | `number` | Maximum height of the rendered screen, in pixels. |
| `activeConnectionId` | `string \| null`, optional | Which of the Visitor's connections (browser tabs or devices) to display. Defaults to the most recently active one. |
| `zoomAreaLabel` | `string`, optional | Accessibility label for the zoom area. |
#### Controlling the Session
##### `useUpscopeViewer()`
Returns Session-level state and actions. Action functions are `undefined` while unavailable (for example before the Session is active), so you can use their presence to enable or disable UI.
| Field | Type | Description |
| --- | --- | --- |
| `connecting` | `boolean` | Whether the SDK is connecting to the server. |
| `connected` | `boolean` | Whether the SDK is connected to the server. |
| `sessionStatus` | `"waiting" \| "pendingRequest" \| "active" \| undefined` | The Session status: waiting for the Visitor, waiting for the Visitor to accept, or active. |
| `loadingStagesLeft` | `("accept" \| "connect" \| "load" \| "firstFrame")[]` | The steps left before the Visitor's screen renders. Empty when the screen is visible; useful for progress UI. |
| `endSession` | `(() => void) \| undefined` | Ends the Session. |
| `visitor` | `object \| undefined` | The Visitor being observed, with fields like `shortId`, `identities`, `metadata`, `deviceType`, `browserName`, `locationCountry`, and `isOnline`. |
| `connections` | `object[]` | The Visitor's open connections (browser tabs or devices). Each has a `uniqueConnectionId`, the `currentUrl`, a `status` (`"active"` or `"disconnected"`), and that connection's SDK configuration. |
| `latestActiveConnectionId` | `string \| undefined` | The id of the Visitor's most recently active connection. |
| `viewers` | `object[]` | The viewers connected to the Session, each with a `connectionId`, `name`, `externalId`, screen size, and audio status. |
| `viewersCount` | `number` | The number of viewers connected to the Session. |
| `mode` | `string \| undefined` | The current sharing mode: `"visitor_browser"` (co-browsing), `"visitor_screen"` (full screen sharing), `"visitor_app"` (mobile app), `"own_viewer_screen"` (you are sharing your screen), or `"other_viewer_screen"` (another viewer is sharing theirs). |
| `availableModes` | `string[]` | The sharing modes the Session can switch to (same values as `mode`). |
| `changeMode` | `(mode) => void` | Requests a switch to another sharing mode. Requires the `allow_request_mode` permission. |
| `agentIdleness` | `"active" \| "willDisconnect" \| "disconnected"` | The idle-disconnect state driven by `idleDisconnectSeconds`. Use `willDisconnect` to warn the viewer before they are disconnected. |
| `forceRefresh` | `(() => void) \| undefined` | Requests a full refresh of the Visitor's screen data. |
| `waitingForceRefresh` | `boolean` | Whether a forced refresh is in progress. |
| `expectedDisconnectInfo` | `object \| undefined` | Present when the active connection is expected to disconnect briefly (for example, the Visitor is navigating to another page). Contains an optional `title` and `message` to show, and `returnTimeSeconds` when the Visitor is expected back. |
| `sendCustomMessage` | `(message: object) => void` | Sends a JSON message to the Visitor's SDK. |
| `listen` | `((event, handler) => void) \| undefined` | Subscribes to low-level Session events from the server connection. |
| `setErrorHandler` | `(handler: (error: ViewerError) => void) => void` | Registers the error handler (see [Handling Errors](#handling-errors)). |
| `dataBounceSpeed` | `number` | The latest measured round-trip time to the Visitor, in milliseconds. |
##### `useUpscopeConnection(connectionId?)`
Returns state and actions for one of the Visitor's connections (defaulting to the most recently active one). Like above, each action is `undefined` whenever it is unavailable — because of the Session mode, the SDK configuration, or the [permissions the token was generated with](https://cobrowsingapi.com/docs/rest-api/api-endpoints.md#generating-a-viewer-token-to-embed-co-browsing).
| Field | Type | Description |
| --- | --- | --- |
| `currentUrl` | `string \| null` | The URL the Visitor is currently on. |
| `size` | `{ width, height } \| undefined` | The size of the shared screen. |
| `setCurrentUrl` | `((url: string) => void) \| undefined` | Redirects the Visitor to another URL. Requires the `allow_redirect` permission. |
| `reloadPage` | `(() => void) \| undefined` | Reloads the Visitor's page. Requires the `allow_redirect` permission. |
| `historyBack` | `(() => void) \| undefined` | Navigates the Visitor's browser history back. Requires the `allow_redirect` permission. |
| `historyForward` | `(() => void) \| undefined` | Navigates the Visitor's browser history forward. Requires the `allow_redirect` permission. |
| `requestControl` | `(() => void) \| undefined` | Asks the Visitor for remote control. Only defined when the Visitor's SDK is configured to require a control request and control is off. |
| `requestFullTab` | `(() => void) \| undefined` | Asks the Visitor to share their full browser tab, when parts of the page (like cross-origin iframes) cannot be co-browsed. Requires the `allow_request_full_tab` permission. |
| `stopFullTab` | `(() => void) \| undefined` | Stops full tab sharing and returns to co-browsing. |
| `runConsoleCommand` | `((command: string) => void) \| undefined` | Runs a command in the Visitor's console. Requires the `allow_console` permission. |
| `consoleLogs` | `object[]` | The Visitor's console output, when remote console is enabled. Each entry has an `id`, a `timestamp`, a `level` (`"error"`, `"warn"`, `"info"`, `"log"`, `"debug"`, `"input"`, or `"output"`), the `message`, and an optional `stack`. |
| `confetti` | `(() => void) \| undefined` | Throws confetti on the Visitor's screen. |
| `emojiConfetti` | `((emoji: string) => void) \| undefined` | Throws emoji confetti on the Visitor's screen. |
| `clearDrawings` | `(() => void) \| undefined` | Clears all drawings from the Visitor's screen. Requires the `allow_draw` permission. |
Remote control actions require the Visitor to have granted control; when control is inactive, calling them triggers the `remote_control:inactive` error instead.
#### Handling Errors
Register an error handler to react to connection and remote control problems:
```tsx
const { setErrorHandler } = useUpscopeViewer();
useEffect(() => {
setErrorHandler((error) => {
if (error === "connection:expired") {
// Fetch a new viewer token and remount the ViewerProvider
}
});
}, [setErrorHandler]);
```
| Error | Description |
| --- | --- |
| `connection:authentication` | The token is invalid. |
| `connection:expired` | The token has expired. Generate a new one. |
| `connection:user_not_found` | The Visitor does not exist. |
| `connection:user_not_online` | The Visitor is not online. |
| `connection:version_not_supported` | The SDK version is not supported by the server. |
| `connection:data` | The connection received invalid data. |
| `remote_control:inactive` | A remote control action was attempted while the viewer does not have control. |
| `remote_control:click_not_allowed` | Remote click is not allowed. |
| `remote_control:scroll_not_allowed` | Remote scroll is not allowed. |
| `remote_control:type_not_allowed` | Remote type is not allowed. |
| `remote_control:element_not_allowed` | The element is blocked from remote control by the Visitor's SDK configuration. |
#### Audio and Video Calls
Audio and video calls are managed by the `AudioProvider` and `VideoProvider` components. Nest them inside the `ViewerProvider` and use the `useAudio` and `useVideo` hooks from components inside them.
Calls are subject to the permissions the token was generated with (`allow_audio` and `allow_video`), and video is also configured through the Visitor's SDK, which controls whether it is two way or one way. Audio calls are not available on premise, and viewer tokens for on-premise accounts currently have video calls disabled as well.
```tsx
import { AudioProvider, CallRingingHandler, VideoFrame, VideoProvider, ViewerProvider } from "@upscopeio/viewer-sdk";
function CobrowsingViewer({ endpoint, region, shortId, token }) {
return (
);
}
```
##### `useAudio()`
Returns the audio call state and actions. Must be used inside an `AudioProvider`.
| Field | Type | Description |
| --- | --- | --- |
| `audioState` | `"off" \| "active"` | Whether an audio call is active on the Session. |
| `audioRinging` | `boolean` | Whether an incoming audio call is ringing, waiting for this viewer to accept. |
| `acceptAudioCall` | `() => void` | Accepts the incoming audio call and starts requesting microphone access. |
| `toggleAudio` | `((on: boolean) => void) \| undefined` | Starts (`true`) or ends (`false`) the audio call. `undefined` when this browser or the Visitor's device does not support audio calls. |
| `muted` | `boolean` | Whether this viewer's microphone is muted. |
| `setMuted` | `(mute: boolean) => void` | Mutes or unmutes this viewer's microphone. |
| `inputDevices` | `object[]` | The available microphones, as browser [`MediaDeviceInfo`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) objects. Populated once the viewer has granted microphone access. |
| `outputDevices` | `object[]` | The available speakers, as browser `MediaDeviceInfo` objects. |
| `activeInputDeviceId` | `string \| undefined` | The id of the microphone in use. |
| `activeOutputDeviceId` | `string \| undefined` | The id of the speaker in use. |
| `setInputDevice` | `(deviceId: string) => void` | Switches to another microphone. |
| `setOutputDevice` | `((deviceId: string) => void) \| undefined` | Switches to another speaker. `undefined` in browsers that do not support switching audio output. |
| `viewerAudioAvailable` | `boolean` | Whether this browser supports audio calls. |
| `visitorAudioAvailable` | `boolean` | Whether the Visitor's device supports audio calls. |
| `viewerAudioError` | `"not_authorized" \| "no_input" \| "no_output" \| undefined` | A problem with this viewer's audio: microphone access was denied, or no microphone or speaker was found. |
| `visitorAudioError` | `"not_connected" \| "not_authorized" \| "no_input" \| "no_output" \| undefined` | A problem with the Visitor's audio. |
| `visitorAudioStatus` | `"off" \| "ringing" \| "accepted" \| "authorizing" \| "active"` | Where the Visitor is in the call flow: not in the call, being rung, accepted, granting microphone access, or connected. |
##### `VideoProvider` Props
| Prop | Type | Description |
| --- | --- | --- |
| `i18n` | `{ requestVideo: string }` | The labels used by the video call widget. `requestVideo` is the label of the button that asks the Visitor to turn their camera on. |
##### `useVideo()`
Returns the video call state and actions. Must be used inside a `VideoProvider`.
| Field | Type | Description |
| --- | --- | --- |
| `videoViewerState` | `"off" \| "ringing" \| "authorizing:{connection_id}" \| "active:{connection_id}"` | The viewers' side of the video call: off, ringing, or which viewer connection is granting camera access or streaming. |
| `videoVisitorState` | `"off" \| "ringing" \| "authorizing:{connection_id}" \| "active:{connection_id}"` | The Visitor's side of the video call. |
| `videoRinging` | `boolean` | Whether an incoming video call is ringing, waiting for this viewer to accept. |
| `ownVideoOn` | `boolean` | Whether this viewer's own camera is on (granting access or streaming). |
| `beginVideo` | `() => void` | Starts the video call in the direction allowed by the Visitor's SDK configuration (two way, visitor to viewer, or viewer to visitor). |
| `endVideo` | `() => void` | Ends the video call on both sides. |
| `toggleOwnVideo` | `() => void` | Turns this viewer's own camera on or off. |
| `videoRequestToVisitor` | `() => void` | Asks the Visitor to turn their camera on. |
| `viewerVideoError` | `"not_authorized" \| "no_input" \| undefined` | A problem with this viewer's video: camera access was denied or no camera was found. |
| `visitorVideoError` | `"not_authorized" \| "no_input" \| undefined` | A problem with the Visitor's video. |
The remaining fields returned by the hook (`sendVideoCallFrame`, `setVideoMeter`, `reportViewerVideoUnauthorized`, `i18n`) are plumbing used by `VideoFrame`; you will not normally call them yourself.
##### `VideoFrame`
Renders the floating video call widget: this viewer's camera preview, the Visitor's video, and the buttons to toggle cameras. It attaches its UI directly to the page (it renders nothing in your React tree), so simply mount it anywhere inside the `VideoProvider`.
| Prop | Type | Description |
| --- | --- | --- |
| `className` | `string`, optional | An extra class for the widget container. |
| `closeButtons` | `boolean`, optional | Whether the video tiles show close buttons. Defaults to `true`. |
| `draggable` | `boolean`, optional | Whether the widget can be dragged around the page. Defaults to `true`. |
| `pipWindow` | `Window`, optional | A [document Picture-in-Picture](https://developer.mozilla.org/en-US/docs/Web/API/Document_Picture-in-Picture_API) window to render the widget into, instead of the page. |
##### `CallRingingHandler`
Coordinates incoming call prompts and plays the ringtone. When a call starts ringing, the matching callback is called with an `accept` function: show your own prompt, and call `accept(true)` or `accept(false)` with the viewer's answer. Return a cleanup function — it is called when the ringing stops (for example, the Visitor cancelled the call), so you can dismiss the prompt.
```tsx
import { CallRingingHandler, OnRinging } from "@upscopeio/viewer-sdk";
const promptForCall: OnRinging = (accept) => {
const dismissPrompt = showIncomingCallPrompt({
onAccept: () => accept(true),
onRefuse: () => accept(false),
});
return dismissPrompt;
};
```
| Prop | Type | Description |
| --- | --- | --- |
| `onAudioRinging` | `(accept: (accepted: boolean) => void) => () => void`, optional | Called when an incoming audio call starts ringing. |
| `onVideoRinging` | `(accept: (accepted: boolean) => void) => () => void`, optional | Called when an incoming video call starts ringing. |
If audio and video ring at the same time, only `onAudioRinging` fires, and accepting or refusing it also accepts or refuses the video call.
## On Premise
Source: https://cobrowsingapi.com/docs/on-premise
### Deploying Co-Browsing API On-Premise
The easiest way to deploy Co-Browsing API is by adopting our cloud solution. It is secure, fast, and straightforward to implement, allowing us to quickly address any issues that arise.
However, we understand that some companies have stringent data security requirements, making our cloud solution unsuitable for them. To accommodate these needs, we have implemented a hybrid solution.
### Quick Start
Source: https://cobrowsingapi.com/docs/on-premise/quick-start
#### Running Co-Browsing API On-Premise
To run Co-Browsing API on your infrastructure, you'll need to either run a Docker image that contains everything or host the components separately yourself.
If you have fewer than 5,000 Visitors online at any given time and no more than 100 concurrent Sessions, a single server will likely be enough. If you have more, you'll likely need to add more servers and scale Co-Browsing API horizontally by having a separate Redis cluster.
**Docker Image:**
Pull [our image](https://hub.docker.com/r/upscope/onpremise) from Docker Hub and run it with the environment variables listed below.
```shell
docker run -d \
-e BASE_ENDPOINT=https://cobrowsing.acmetech.com/ \
-e LICENSE_KEY=https://api.upscope.io/v1.3/.... \
-e SECRET_KEY=myrandomsecretkey... \
-p 5002:5002 \
upscope/onpremise
```
See the [Configuration](#configuration) section for all available environment variables.
**Host MongoDB Connection Issues:**
MongoDB cannot be listening only to localhost, because the container never uses the loopback network for connection. Set the `net.bindIp` to listen on `0.0.0.0` in `/etc/mongod.conf`, or—if it's a security issue—on the Docker network. This is similar for Redis, which should listen to `*:6379`.
**Docker Script:**
We've created a simple startup script to easily start and configure Co-Browsing API to use with Docker.
1. Download the [startup script (.sh file)](https://raw.githubusercontent.com/upscopeio/onprem-scripts/master/start-on-premise.sh).
2. Edit its variables according to the data from your Co-Browsing API dashboard `Settings` » `On Premise`.
3. Make it executable: `chmod +x start-on-premise.sh`.
4. Run it: `./start-on-premise.sh`.
**Host MongoDB Connection Issues:**
MongoDB cannot be listening only to localhost, because the container never uses the loopback network for connection. Set the `net.bindIp` to listen on `0.0.0.0` in `/etc/mongod.conf`, or—if it's a security issue—on the Docker network. This is similar for Redis, which should listen to `*:6379`.
**Binaries:**
If you don't want to use Docker, you'll find Co-Browsing API binaries on the link provided in your Co-Browsing API dashboard `Settings` » `On Premise`.
This link never changes, so you can `curl` the binaries as part of your build process and automatically keep Co-Browsing API up to date. Any breaking change will have a new link, so you don't need to worry about that.
You can start the server by running:
```shell
BASE_ENDPOINT=http://localhost:5002 PORT=5002 \
LICENSE_KEY=https://api.upscope.io/v1.3/.... \
SECRET_KEY=myrandomsecretkey... ./upscope-data-linux
```
#### Installing Co-Browsing API on Your Website
After you run Co-Browsing API, the output will give you instructions for your [JavaScript SDK](https://cobrowsingapi.com/docs/sdk/web/installation.md) installation code. It looks like this (notice `{BASE_ENDPOINT}`):
```html
```
You can add that code to pages like you would with our cloud solution.
#### Installing Co-Browsing API in Your Mobile Apps
The [iOS](https://cobrowsingapi.com/docs/sdk/ios/installation.md), [Android](https://cobrowsingapi.com/docs/sdk/android/installation.md), [Flutter](https://cobrowsingapi.com/docs/sdk/flutter/installation.md), and [React Native](https://cobrowsingapi.com/docs/sdk/react-native/installation.md) SDKs connect to your on-premise instance when you set the `onPremiseBaseEndpoint` configuration option to your `BASE_ENDPOINT`. The SDK then fetches its configuration from `{BASE_ENDPOINT}/sdk-config.json` and connects to `{BASE_ENDPOINT}/session` instead of our cloud servers, so the `region` option is ignored.
**iOS:**
```swift
let config = UpscopeConfiguration(
apiKey: "YOUR_API_KEY",
onPremiseBaseEndpoint: "https://cobrowsing.acmetech.com"
)
try Upscope.shared.initialize(with: config)
```
**Android:**
```kotlin
val config = UpscopeConfiguration.Builder("YOUR_API_KEY")
.onPremiseBaseEndpoint("https://cobrowsing.acmetech.com")
.build()
Upscope.initialize(applicationContext, config)
```
**Flutter:**
```dart
final config = UpscopeConfiguration(
apiKey: 'YOUR_API_KEY',
onPremiseBaseEndpoint: 'https://cobrowsing.acmetech.com',
);
await Upscope.instance.initialize(config);
```
**React Native:**
```typescript
import Upscope from "@upscopeio/react-native-sdk";
Upscope.initialize({
apiKey: "YOUR_API_KEY",
onPremiseBaseEndpoint: "https://cobrowsing.acmetech.com",
});
```
Everything else — installation, configuration options, and SDK functions — works exactly like the cloud version.
#### Your License Key
To run Co-Browsing API, you'll need to retrieve your license key. The license key can be downloaded to your server or read automatically from our server every time the server starts.
You'll need to enter the license key into the `LICENSE_KEY` environment variable. The `LICENSE_KEY` environment variable can be one of:
- The license key content (note it's multi-line)
- A file path to the license key content
- The URL to the license key, the preferred method
If you don't have to restrict the instance's interactions with the internet, entering the URL provided on the [dashboard](https://app.upscope.io/settings/teams/_/on_prem) as the `LICENSE_KEY` environment variable is preferable as you won't need to update it when it expires.
**Good to Know:**
Your JavaScript SDK configuration is also embedded in your license key. This means you can still configure Co-Browsing API on your dashboard and then restart the server to apply the changes.
#### Configuration
The following is configurable through environment variables:
| Environment Variable | Description | Default |
| --- | --- | --- |
| `BASE_ENDPOINT` | The base URL where this component will be mounted. For example, `https://cobrowsing.acmetech.com/`. It can be in a subdirectory. | (nil, **required**) |
| `LICENSE_KEY` | Your unique Co-Browsing API license key (or a link to it). | (nil, **required**) |
| `SECRET_KEY` | A unique secret key used to sign internal JWTs. **It's very important this key is kept safe and it's at least 32 characters long.** | (nil, **required**) |
| `AUTH_ENDPOINT` | URL watch links will be redirected to for authentication. | `https://app.upscope.io/onprem_redirect/TEAM_IDENTIFIER` |
| `HOMEPAGE` | URL unrecognized requests will be redirected to. | `https://upscope.com/` |
| `LOOKUP_CODE_LENGTH` | The number of digits in visitor lookup codes. | `4` |
| `MONGO_URI` | URI to a single MongoDB instance, or MongoDB cluster | If omitted, `mongodb://localhost:27017/upscope`. (In Docker this starts MongoDB within the image). If set to an empty string, it will disable MongoDB. |
| `PORT` | The port the server will listen on. | `5002` |
| `REDIS_URI` | URI to Redis or a Redis cluster. | `redis://localhost:6379`. (In Docker this starts Redis within the image). |
| `REST_KEY` | The authentication API key for your on-premise REST API. | (nil) |
| `SSL_REDIRECT` | When set to on, the server will automatically redirect all requests to https. | `off` |
| `TOKEN_EXPIRY_SECONDS` | The number of seconds watch links and viewer tokens generated through the REST API stay valid. Must be a whole number. | `60` |
If you use `MONGO_URI=mongodb://localhost/upscope` with the Docker image, a MongoDB server will be installed inside the container to serve the application.
If you use `redis://localhost/` with the Docker image, a Redis server will be installed inside the container to serve the application.
#### Session Video Recording
Your on-premise instance can record Sessions and render them to MP4, with the video files never leaving your infrastructure. For recording to work you need:
1. The session recording feature on your plan. It's embedded in your license key, so if you just added it, re-download the license key (or use the URL form of `LICENSE_KEY`) and restart the server.
2. MongoDB (`MONGO_URI` must not be disabled): Session events used for the replay are stored there.
3. For Sessions that include browser co-browsing, a separate Chromium container the server can reach over WebSocket. We test with the [browserless Chromium image](https://github.com/browserless/browserless):
```shell
docker run -d -e TOKEN=mybrowserlesstoken -p 3000:3000 ghcr.io/browserless/chromium
```
Then point your Co-Browsing API instance at it with `BROWSERLESS_ENDPOINT=ws://yourdockerhost:3000?token=mybrowserlesstoken`. Sessions made only of screen sharing frames are rendered with ffmpeg directly and don't need the Chromium container (if you run the binaries instead of Docker, make sure `ffmpeg` is available on the PATH).
Nothing is rendered until you ask for it. Once a Session has ended, `POST` its `session_id` to `{BASE_ENDPOINT}/api/recordings/{visitor_short_id}`, authenticated with a short-lived HS256 token signed with your `SECRET_KEY`. The first call starts the render, later calls report progress, and the video URL comes back once it's ready.
See [Requesting a Session Recording](https://cobrowsingapi.com/docs/on-premise.md#requesting-a-session-recording) for the full request and its responses.
A Session can't be rendered if no events were stored for it, if it needs a browser and `BROWSERLESS_ENDPOINT` is unset, or if MongoDB is disabled.
Recordings can be stored on a local volume (the default) or on S3:
| Environment Variable | Description | Default |
| --- | --- | --- |
| `RECORDINGS_STORAGE` | `volume` stores recordings on disk under `/recordings` (mount a volume there to persist them) and serves them from `{BASE_ENDPOINT}/recordings`; `s3` uploads them to S3 instead. | `volume` |
| `RECORDINGS_S3_BUCKET` | The S3 bucket recordings are uploaded to when using `s3` storage. Falls back to `S3_BUCKET`. | (nil) |
| `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `AWS_REGION` | The AWS credentials used for `s3` storage. | (nil) |
| `RECORDINGS_BASE_URL` | The public base URL recording links point to. Set it when using `s3` storage (your bucket or CDN URL). | `{BASE_ENDPOINT}/recordings` |
| `BROWSERLESS_ENDPOINT` | WebSocket endpoint of the Chromium container used to replay browser Sessions. When unset, only screen sharing Sessions can be recorded. | (nil) |
| `RENDER_RECORD_ENDPOINT` | The URL the Chromium container loads to render the replay. Override it when your `BASE_ENDPOINT` is not reachable from that container. | `{BASE_ENDPOINT}/record` |
Recording file URLs are not guessable (they contain a UUID), matching the access model of our cloud storage.
You can skip recording an individual Session with the `session_properties.record` parameter on the [watch link and viewer token endpoints](https://cobrowsingapi.com/docs/on-premise.md#generating-a-link-to-start-screen-sharing-with-a-visitor).
#### API Endpoint
Check the [on-premise REST API docs](https://cobrowsingapi.com/docs/on-premise.md) to know how to make requests to the on-premise instance.
#### What Doesn't Work On-Premise?
Although we've made our on-premise version as similar as possible to the original, there are a few missing functionalities. You'll need to use Co-Browsing API cloud if you are interested in:
- Presentation sharing
- IP geolocation features
- Audio/video communication
##### Usage Without MongoDB
We are aware some of our customers cannot use MongoDB due to compliance reasons.
Co-Browsing API works fine without MongoDB, but the Search feature will be limited. You'll still be able to search by:
- **Lookup code**
- **Email**
- **Unique ID**
- **Integration IDs**
### REST API (on premise)
Source: https://cobrowsingapi.com/docs/on-premise/rest-api-on-premise
#### On-Premise REST API Overview
The on-premise REST API functions similarly to the cloud version, with some differences detailed below.
#### Enabling the API
By default, the API is disabled. It will only be enabled when you add a `REST_KEY` environment variable.
#### Authentication
To authenticate your requests to the REST API, add an `Authorization` header set to the value you provided in the `REST_KEY` environment variable.
#### The Visitor Object
The **Visitor** object may differ slightly in the on-premise version, depending on your configuration. Most attributes will be present, and all Visitors will have the same properties.
#### Session IDs
The watch link and viewer token endpoints return a `session_id` like `onprem_s_3f2c8a1e-9d47-4b02-8f61-05c7ae13d9b4`. Your instance generates it, so it needs no connection to our servers. Keep it: it's what you pass back to [request the Session's recording](#requesting-a-session-recording).
#### Endpoints
On-premise, the REST API is mounted on the `/api` path of your base endpoint. For example, if your `BASE_ENDPOINT` is `https://support.acmetech.com/cobrowsing`, one of the endpoints will be `https://support.acmetech.com/cobrowsing/api/visitors/list/latest`.
##### Listing the Latest Visitors
Use this endpoint to list the latest online Visitors. This only works with MongoDB.
```http
GET /v1.4/visitors/list/latest
```
| Parameter | Type | Description |
| ------------- | ------------------ | ---------------------------------------- |
| `max_results` | `number`, optional | The max number of results to return. |
**Response**
```javascript
// HTTP 200
{
"status": "ok",
"visitors": [
{
"short_id": "1234",
// ...
}
]
}
```
| Field | Type | Description |
| ---------- | ----------- | ------------------------------------ |
| `visitors` | `Visitor[]` | List of Visitors matching the query. |
##### Searching for a Visitor
Use this endpoint to search for Visitors.
```http
GET /v1.4/visitors/list/search
```
| Parameter | Type | Description |
| ------------- | ------------------ | -------------------------------------------------------------------------------------- |
| `q` | `string`, optional | The search query in this format. If left empty, the latest Visitors will be returned. |
| `max_results` | `number`, optional | The max number of results to return. |
**Response**
```javascript
// HTTP 200
{
"status": "ok",
"visitors": [
{
"short_id": "1234",
// ...
}
]
}
```
| Field | Type | Description |
| ---------- | ----------- | ------------------------------------ |
| `visitors` | `Visitor[]` | List of Visitors matching the query. |
##### Retrieving a Visitor
Use this endpoint to retrieve a specific Visitor.
```http
GET /v1.4/visitors/{visitor_id}
```
| Parameter | Type | Description |
| ---------------- | ------------------- | ---------------------------------------------------------------------- |
| `{visitor_id}` | `string` | The short id of the Visitor. |
| `includeHistory` | `boolean`, optional | Set to `true` to include the Visitor's pageview history (MongoDB only). |
**Response**
```javascript
// HTTP 200
{
"status": "ok",
"visitor": {
"short_id": "1234",
"history": [
// Pageviews, if includeHistory was set to true
],
// ...
}
}
```
| Field | Type | Description |
| ----------------- | ----------------------- | ----------------------------------------------------------------- |
| `visitor` | `Visitor` | The Visitor. |
| `visitor.history` | `Pageview[]`, optional | The Visitor's latest pageviews. Only present with `includeHistory`. |
**Errors**
| Code | Description |
| ----- | --------------------------- |
| `404` | The Visitor does not exist. |
##### Generating a Link to Start Screen Sharing with a Visitor
To start a Session with one of your Visitors, first obtain an authorization token from our server, then make a request to your on-premise REST API.
```javascript
// POST /v1.4/visitors/{visitor_id}/watch_url
{
"licenseToken": "token1234",
"branding": {},
"permissions": {},
"viewer": {
"id": "123",
"name": "Joe Smith"
}
}
```
| Parameter | Type | Description |
| -------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{visitor_id}` | `string` | The short id of the Visitor. |
| `licenseToken` | `string` | The token obtained from [here](https://cobrowsingapi.com/docs/rest-api/api-endpoints.md#authorizing-an-on-premise-session). Reach out to our team if this is incompatible with your flow for alternative options. |
| `viewer.id` | `string` | The ID of the person viewing the screen (required). |
| `viewer.name` | `string`, optional | The name of the person viewing the screen. |
| `agent.id` | `string`, optional | The ID of the Agent responsible for the Session. When set, the Agent (rather than the viewer) is the identity used for licensing and usage tracking, and the `licenseToken` must have been generated for this Agent. Use it when the person viewing the screen is not one of your Agents — for example when the Visitor is viewing their own Session — so each viewer is not counted as a separate Agent. |
| `agent.name` | `string`, optional | The name of the Agent responsible for the Session. |
| `branding.naked` | `"page_only"`, optional | Set to `"page_only"` to remove everything on the page except the shared screen, including the viewer's UI. Ideal when embedding the page inside an iframe. |
| `branding.show_end_button` | `boolean`, optional | Whether an "End session" button should be shown on the viewer page. |
| `branding.on_end_url` | `string \| null`, optional | If set, the viewer will be redirected to this URL after the Session ends. Defaults to `null`. |
| `branding.retry_url` | `string \| null`, optional | If set, the visitor can click a "Retry now" link that redirects to this URL if there are problems. Defaults to `null`. |
| `permissions.allow_click` | `boolean`, optional | Whether the viewer should have access to remote click (defaults to `true`). |
| `permissions.allow_confetti` | `boolean`, optional | Whether the viewer should be able to throw confetti (defaults to `true`). |
| `permissions.allow_console` | `boolean`, optional | Whether the viewer should have access to remote console capabilities (defaults to `false`). |
| `permissions.allow_draw` | `boolean`, optional | Whether the viewer should have access to drawing (defaults to `true`). |
| `permissions.allow_redirect` | `boolean`, optional | Whether the viewer should have access to remote redirect & reload features (defaults to `true`). Called `allow_agent_redirect` before v1.4. |
| `permissions.allow_request_control` | `boolean`, optional | Whether the viewer should be able to request remote control when the Visitor's SDK requires a control request (defaults to `true`). |
| `permissions.allow_request_full_tab` | `boolean`, optional | Whether the viewer should be able to request full browser tab sharing (defaults to `false`). |
| `permissions.allow_request_mode` | `boolean`, optional | Whether the viewer should be able to request a different sharing mode, such as full screen sharing (defaults to `true`). |
| `permissions.allow_request_visitor_screen` | `boolean`, optional | Whether the viewer should be able to ask the Visitor to share their full screen (defaults to `true`). |
| `permissions.allow_scroll` | `boolean`, optional | Whether the viewer should have access to remote scroll (defaults to `true`). |
| `permissions.allow_show_viewer_screen` | `boolean`, optional | Whether the viewer should be able to share their screen with the Visitor (defaults to `true`). Called `allow_show_agent_screen` before v1.4. |
| `permissions.allow_type` | `boolean`, optional | Whether the viewer should have access to remote type (defaults to `true`). |
| `permissions.allow_video` | `boolean`, optional | Whether the viewer should have access to video calls (defaults to `true`). Audio calls are not available on premise. |
| `permissions.hide_private_details` | `boolean`, optional | Whether the Visitor's private information (such as IP address) should be hidden from the viewer (defaults to `false`). |
| `permissions.keeps_session_alive` | `boolean`, optional | Whether this viewer keeps the Session alive. Set to `false` for silent observers, so the Session ends when the last keep-alive viewer leaves (defaults to `true`). |
| `session_properties.controller` | `Array<"viewer" \| "visitor">`, optional | Which sides of the Session can start video calls and request a different sharing mode. Defaults to `["viewer"]`. |
| `session_properties.record` | `boolean`, optional | Whether this Session should be recorded. Defaults to `true` whenever session recording is set up on your server; set it to `false` to skip recording this Session. |
**Upgrading from v1.3?:**
The `agent` object was replaced by the `viewer` object, and `viewer.id` is now required. In v1.4, `agent` is instead an optional, separate object identifying the Agent the Session is licensed to (see above). The `permissions.allow_agent_redirect` and `permissions.allow_show_agent_screen` options were renamed to `permissions.allow_redirect` and `permissions.allow_show_viewer_screen`. Requests to the `/v1.3/` endpoints keep working with the old names.
**Response**
```javascript
// HTTP 200
{
"status": "ok",
"watch_url": "https://support.acmetech.com/cobrowsing/screen?id=jfoiajsdoif&token=osdjfoijo",
"session_id": "onprem_s_3f2c8a1e-9d47-4b02-8f61-05c7ae13d9b4"
}
```
| Field | Type | Description |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `watch_url` | `string` | The Secure watch URL. It stays valid for 60 seconds (configurable on your instance with `TOKEN_EXPIRY_SECONDS`), so open it right away. |
| `session_id` | `string` | The id of the Session this link starts. Use it to [request the Session's recording](#requesting-a-session-recording). |
**Errors**
| Code | Description |
| ----- | ---------------------------------------------------------- |
| `400` | A required parameter is missing or invalid. |
| `402` | This viewer would put you over your subscription limits. |
| `404` | The Visitor does not exist. |
| `409` | The Visitor's browser is not supported. |
##### Generating a Viewer Token to Embed Co-Browsing
Use this endpoint to generate a viewer token instead of a watch link. The token lets you embed the co-browsing screen directly in your own application with the [viewer SDK](https://cobrowsingapi.com/docs/rest-api/viewer-sdk.md), instead of opening the hosted watch page. The Visitor's browser is asked to prepare for the Session right away, so only request a token when the viewer is about to connect.
```javascript
// POST /v1.4/visitors/{visitor_id}/viewer_token
{
"licenseToken": "token1234",
"permissions": {},
"viewer": {
"id": "123",
"name": "Joe Smith"
}
}
```
| Parameter | Type | Description |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{visitor_id}` | `string` | The short id of the Visitor. |
| `licenseToken` | `string` | The token obtained from [here](https://cobrowsingapi.com/docs/rest-api/api-endpoints.md#authorizing-an-on-premise-session). Reach out to our team if this is incompatible with your flow for alternative options. |
The endpoint also accepts the same `viewer`, `agent`, `permissions` and `session_properties` parameters as the watch link endpoint above.
**Response**
```javascript
// HTTP 200
{
"status": "ok",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
"endpoint": "https://support.acmetech.com/cobrowsing",
"region": "onpremise",
"short_id": "1234",
"session_id": "onprem_s_3f2c8a1e-9d47-4b02-8f61-05c7ae13d9b4",
"expiration": "2026-01-11T18:01:49.700Z"
}
```
| Field | Type | Description |
| --- | --- | --- |
| `token` | `string` | The token to pass to the viewer SDK. |
| `endpoint` | `string` | The server the viewer should connect to (your on-premise instance). |
| `region` | `string` | Always `onpremise`. |
| `short_id` | `string` | The short id of the Visitor. |
| `session_id` | `string` | The id of the Session this token starts. Use it to [request the Session's recording](#requesting-a-session-recording). |
| `expiration` | `Datetime` (ISO 8601) | Time at which the token is no longer valid. It's 60 seconds after issue unless your instance sets `TOKEN_EXPIRY_SECONDS`. Use it right away. |
**Errors**
| Code | Description |
| ----- | ---------------------------------------------------------- |
| `400` | A required parameter is missing or invalid. |
| `402` | This viewer would put you over your subscription limits. |
| `404` | The Visitor does not exist. |
| `409` | The Visitor's browser is not supported. |
##### Requesting a Session Recording
Renders an ended Session to MP4 on your own instance. See [Session Video Recording](https://cobrowsingapi.com/docs/on-premise/quick-start.md#session-video-recording) for the storage and Chromium setup it needs.
**This Endpoint Authenticates Differently:**
This one does not use `REST_KEY`. Send an `Authorization: Bearer ` header holding a short-lived HS256 JWT signed with your `SECRET_KEY`, with the payload `{"scope": "cobrowsing-data-call", "apiKeys": "*"}`.
```javascript
// POST /v1.4/recordings/{visitor_id}
{
"sessionId": "onprem_s_3f2c8a1e-9d47-4b02-8f61-05c7ae13d9b4"
}
```
| Parameter | Type | Description |
| -------------- | -------- | ----------------------------------------------------------------------------------------- |
| `{visitor_id}` | `string` | The short id of the Visitor. |
| `sessionId` | `string` | The `session_id` returned when you generated the watch link or viewer token. |
Rendering is asynchronous. The first request starts it, and further requests report progress until the video is ready. Poll about once a minute rather than tightly, as rendering a long Session takes a while.
**Response**
```javascript
// HTTP 200, still rendering
{
"status": "ok",
"video_status": "recording"
}
// HTTP 200, finished
{
"status": "ok",
"video_status": "ready",
"video_url": "https://support.acmetech.com/cobrowsing/recordings/APIKEY/1234/6f1b....mp4"
}
```
| Field | Type | Description |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `video_status` | `string` | `recording` while the render is in progress, `ready` once the video is available. |
| `video_url` | `string` | Present when `video_status` is `ready`. Points at your own storage. Held for 6 hours after the render completes. |
**Errors**
| Code | Description |
| ----- | --------------------------------------------------------------------------------------------------------- |
| `404` | No events were recorded for this Session, so there is nothing to render. |
| `501` | MongoDB is disabled on your instance, or the Session needs a browser and `BROWSERLESS_ENDPOINT` is unset. |
##### Preparing a Session
Use this endpoint to ask the Visitor's browser to prepare for a Session ahead of time, so the Session starts faster. This is done automatically when you generate a watch link.
```http
POST /v1.4/visitors/{visitor_id}/session/prepare
```
| Parameter | Type | Description |
| -------------- | -------- | ---------------------------- |
| `{visitor_id}` | `string` | The short id of the Visitor. |
**Response**
```javascript
// HTTP 200
{
"status": "ok"
}
```
**Errors**
| Code | Description |
| ----- | --------------------------- |
| `404` | The Visitor does not exist. |
##### Stopping an Active Session
Use this endpoint to stop the Visitor's active Session.
```http
DELETE /v1.4/visitors/{visitor_id}/session
```
| Parameter | Type | Description |
| -------------- | -------- | ---------------------------- |
| `{visitor_id}` | `string` | The short id of the Visitor. |
**Response**
```javascript
// HTTP 200
{
"status": "ok",
"visitor": {
"short_id": "1234",
// ...
}
}
```
| Field | Type | Description |
| --------- | --------- | ------------ |
| `visitor` | `Visitor` | The Visitor. |
**Errors**
| Code | Description |
| ----- | --------------------------- |
| `404` | The Visitor does not exist. |
##### Deleting a Visitor
Use this endpoint to delete a Visitor entirely, including their pageview history and Session recordings. You can only delete Visitors who are not currently online or in a Session.
```http
DELETE /v1.4/visitors/{visitor_id}
```
| Parameter | Type | Description |
| -------------- | -------- | ---------------------------- |
| `{visitor_id}` | `string` | The short id of the Visitor. |
**Response**
```javascript
// HTTP 200
{
"status": "ok"
}
```
**Errors**
| Code | Description |
| ----- | ------------------------------------------- |
| `404` | The Visitor does not exist. |
| `409` | The Visitor is online or in a Session. |
##### Deleting All Visitors
Use this endpoint to delete all Visitors, along with their pageview history and Session recordings.
```http
DELETE /v1.4/visitors
```
**Response**
```javascript
// HTTP 200
{
"status": "ok"
}
```
## Presentation Sharing
Source: https://cobrowsingapi.com/docs/presentation-sharing
Presentation Sharing allows agents to share internal presentations or dashboards with external viewers. This mode is designed for platforms where you need to generate a public link that customers can view without authentication.
### How It Works
1. **Add the SDK** - Install the Co-Browsing API SDK on your presentation platform
2. **Get a Public Link** - Use the `getPublicLink` function to generate a shareable URL
3. **Share with Viewers** - Send the link to anyone who needs to see your presentation
### Use Cases
- Sales presentations from internal dashboards
- Training content from internal systems
- Demos from platforms like Salesforce
### Setup
This mode is typically set up by administrators. No agent accounts need to be created - the presenting user's information is passed directly to the SDK.
### Getting Started
1. [SDK Integration](https://cobrowsingapi.com/docs/presentation-sharing/sdk-integration.md) - Add the SDK to your platform
2. [Getting Public Links](https://cobrowsingapi.com/docs/presentation-sharing/getting-public-link.md) - Generate shareable URLs
3. [Salesforce Example](https://cobrowsingapi.com/docs/presentation-sharing/salesforce-example.md) - Complete Salesforce Visualforce implementation
### SDK Integration
Source: https://cobrowsingapi.com/docs/presentation-sharing/sdk-integration
Add the Co-Browsing API SDK to any page or application where you want to enable presentation sharing.
#### Installation
Get the installation code from your [Co-Browsing API dashboard](https://cobrowsingapi.com/install) and add it to your page.
#### What Gets Shared
The SDK shares the entire page. If you only want to share a specific section of the page, place that content in an iframe and initialize the SDK within that iframe instead.
#### Session Metadata
You can associate additional data with the session, such as customer information:
```javascript
Upscope("updateConnection", {
metadata: {
customerId: "12345",
accountName: "Acme Corp"
}
});
```
This metadata will be stored with the session.
### Getting Public Links
Source: https://cobrowsingapi.com/docs/presentation-sharing/getting-public-link
#### The getPublicLink Function
Use the `getPublicLink` SDK function to generate a shareable URL that external viewers can access without authentication.
##### Basic Usage
```javascript
Upscope("getPublicLink", {
agentId: "agent-unique-id",
agentName: "Agent Name"
}, function(link) {
console.log("Share this link: " + link);
});
```
##### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agentId` | string | Yes | A unique identifier for the agent (e.g., user ID from your system) |
| `agentName` | string | Yes | Display name shown to viewers |
##### Callback Response
The callback receives a URL string that viewers can open directly in their browser.
Example link format: `https://company.cobrowsingapi.com/123456`
**Custom Domain:**
If you want to change your company domain, please contact support.
#### Displaying the Link
Here's an example of how you might display the link in your UI:
```javascript
function displayLink() {
Upscope("getPublicLink", {
agentId: currentUser.id,
agentName: currentUser.name
}, function(link) {
document.getElementById("public-link").textContent = link;
document.getElementById("link-container").style.display = "block";
});
}
```
### Salesforce Visualforce Example
Source: https://cobrowsingapi.com/docs/presentation-sharing/salesforce-example
#### Complete Salesforce Implementation
This example shows how to add presentation sharing to a Salesforce Visualforce page.
##### Visualforce Page
```html
```
##### Key Points
1. **Aura Compatibility Flag**: The `window.__upscopeFlags__ = ["aura_compatibility"]` line ensures the SDK works correctly within Salesforce's Lightning framework.
2. **User Context**: We use Visualforce merge fields (`{!$User.Id}`, `{!JSENCODE($User.Name)}`) to automatically get the current Salesforce user's information.
3. **JSENCODE**: Always use `{!JSENCODE()}` for string values to prevent issues with quotes.
4. **Metadata**: Pass relevant Salesforce record information via `updateConnection` to provide context in reports.