Labsco
anthropics logo

zoom-cobrowse-sdk

✓ Official★ 22,378

by anthropic · part of anthropics/knowledge-work-plugins

Reference skill for Zoom Cobrowse SDK. Use after routing to a collaborative-support workflow when implementing browser co-browsing, annotation tools, privacy masking, remote assist, or PIN-based session sharing.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#git
🧩 One of 7 skills in the anthropics/knowledge-work-plugins package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

Zoom Cobrowse SDK - Web Development

Background reference for collaborative browsing on the web with Zoom Cobrowse SDK. Use this after the support workflow is clear and you need implementation detail.

Official Documentation: https://developers.zoom.us/docs/cobrowse-sdk/
API Reference: https://marketplacefront.zoom.us/sdk/cobrowse/
Quickstart Repository: https://github.com/zoom/CobrowseSDK-Quickstart
Auth Endpoint Sample: https://github.com/zoom/cobrowsesdk-auth-endpoint-sample

New to Cobrowse SDK? Follow this path:

  1. Get Started Guide - Complete setup from credentials to first session
  2. Session Lifecycle - Understanding customer and agent flows
  3. JWT Authentication - Token generation and security
  4. Customer Integration - Integrate SDK into your website
  5. Agent Integration - Set up agent portal (iframe or npm)

Core Concepts:

Features:

Troubleshooting:

Reference:

SDK Overview

The Zoom Cobrowse SDK is a JavaScript library that provides:

  • Real-Time Co-Browsing: Agent sees customer's browser activity live
  • PIN-Based Sessions: Secure 6-digit PIN for customer-to-agent connection
  • Annotation Tools: Drawing, highlighting, vanishing pen, rectangle, color picker
  • Privacy Masking: CSS selector-based masking of sensitive form fields
  • Remote Assist: Agent can scroll customer's page (with consent)
  • Multi-Tab Persistence: Session continues when customer opens new tabs
  • Auto-Reconnection: Session recovers from page refresh (2-minute window)
  • Session Events: Real-time events for session state changes
  • HTTPS Required: Secure connections (HTTP only works on loopback/local development hosts)
  • No Plugins: Pure JavaScript, no browser extensions needed

Two Roles Architecture

Cobrowse has two distinct roles, each with different integration patterns:

Rolerole_typeIntegrationJWT RequiredPurpose
Customer1Website integration (CDN or npm)YesUser who shares their browser session
Agent2Iframe (CDN) or npm (BYOP only)YesSupport staff who views/assists customer

Key Insight: Customer and agent use different integration methods but the same JWT authentication pattern.

Read This First (Critical)

For customer/agent demos, treat the PIN from customer SDK event pincode_updated as the only user-facing PIN.

  • Show one clearly labeled value in UI (for example, Support PIN).
  • Use that same PIN for agent join.
  • Do not expose provisional/debug PINs from backend pre-start records to users.

If these rules are ignored, agent desk often fails with Pincode is not found / code 30308.

Typical Production Flow (Most Common)

This is the flow most teams implement first, and what users usually expect in demos:

  1. Customer starts session first (role_type=1)
    • Backend creates/records session
    • Backend returns customer JWT
    • Customer SDK starts and receives a PIN
  2. Agent joins second (role_type=2)
    • Agent enters customer PIN
    • Backend validates PIN and session state
    • Backend returns agent JWT
    • Agent opens Zoom-hosted desk iframe (or custom npm agent UI in BYOP)

If a demo only has one generic "session" user, it is incomplete for real cobrowse operations.

Key Features

1. Annotation Tools

Both customer and agent can draw on the shared screen:

const settings = {
  allowAgentAnnotation: true,      // Agent can draw
  allowCustomerAnnotation: true    // Customer can draw
};

Available tools:

  • Pen (persistent)
  • Vanishing pen (disappears after 4 seconds)
  • Rectangle
  • Color picker
  • Eraser
  • Undo/Redo

2. Privacy Masking

Hide sensitive fields from agents using CSS selectors:

const settings = {
  piiMask: {
    maskType: "custom_input",           // Mask specific fields
    maskCssSelectors: ".pii-mask, #ssn", // CSS selectors
    maskHTMLAttributes: "data-sensitive=true" // HTML attributes
  }
};

Supported masking:

  • Text nodes ✓
  • Form inputs ✓
  • Select elements ✓
  • Images ✗ (not supported)
  • Links ✗ (not supported)

3. Remote Assist

Agent can scroll the customer's page:

const settings = {
  remoteAssist: {
    enable: true,
    enableCustomerConsent: true,        // Customer must approve
    remoteAssistTypes: ['scroll_page'], // Only scroll supported
    requireStopConfirmation: false      // Confirmation when stopping
  }
};

4. Multi-Tab Session Persistence

Session continues when customer opens new tabs:

const settings = {
  multiTabSessionPersistence: {
    enable: true,
    stateCookieKey: '$$ZCB_SESSION$$'  // Cookie key (base64 encoded)
  }
};

Session Lifecycle

Customer Flow

  1. Load SDK → CDN script loads ZoomCobrowseSDK
  2. Initialize → ZoomCobrowseSDK.init(settings, callback)
  3. Fetch JWT → Request token from your server (role_type=1)
  4. Start Session → session.start({ sdkToken })
  5. PIN Generated → pincode_updated event fires
  6. Share PIN → Customer gives 6-digit PIN to agent
  7. Agent Joins → agent_joined event fires
  8. Session Active → Real-time synchronization begins
  9. End Session → session.end() or agent leaves

Agent Flow

  1. Fetch JWT → Request token from your server (role_type=2)
  2. Load Iframe → Point to Zoom agent portal with token
  3. Enter PIN → Agent inputs customer's 6-digit PIN
  4. Connect → session_joined event fires
  5. View Session → Agent sees customer's browser
  6. Use Tools → Annotations, remote assist, zoom
  7. Leave Session → Click "Leave Cobrowse" button

Session Recovery (Auto-Reconnect)

When customer refreshes the page:

ZoomCobrowseSDK.init(settings, function({ success, session, error }) {
  if (success) {
    const sessionInfo = session.getSessionInfo();
    
    // Check if session is recoverable
    if (sessionInfo.sessionStatus === 'session_recoverable') {
      session.join();  // Auto-rejoin previous session
    } else {
      // Start new session
      session.start({ sdkToken });
    }
  }
});

Recovery window: 2 minutes. After 2 minutes, session ends.

Critical Gotchas and Best Practices

⚠️ CRITICAL: SDK Secret Must Stay Server-Side

Problem: Developers often accidentally embed SDK Secret in frontend code.

Solution:

  • ✓ SDK Key → Safe to expose (embedded in CDN URL)
  • ✗ SDK Secret → Never expose (use for JWT signing server-side)
// ❌ WRONG - Secret exposed in frontend
const jwt = signJWT(payload, 'YOUR_SDK_SECRET');  // Security risk!

// ✅ CORRECT - Secret stays on server
const response = await fetch('/api/token', {
  method: 'POST',
  body: JSON.stringify({ role: 1, userId, userName })
});
const { token } = await response.json();

SDK Key vs API Key (Different Purposes!)

CredentialUsed ForJWT Claim
SDK KeyCDN URL, JWT app_keyapp_key: "SDK_KEY"
API KeyREST API calls (optional)Not used in JWT

Common mistake: Using API Key instead of SDK Key in JWT app_key claim.

Session Limits

LimitValueWhat Happens
Customers per session1Error 1012: SESSION_CUSTOMER_COUNT_LIMIT
Agents per session5Error 1013: SESSION_AGENT_COUNT_LIMIT
Active sessions per browser1Error 1004: SESSION_COUNT_LIMIT
PIN code length10 chars maxError 1008: SESSION_PIN_INVALID_FORMAT

Session Timeout Behavior

EventTimeoutWhat Happens
Agent waiting for customer3 minutesSession ends automatically
Page refresh reconnection2 minutesSession ends if not reconnected
Reconnection attempts2 times maxSession ends after 2 failed attempts

HTTPS Requirement

Problem: SDK doesn't load on HTTP sites.

Solution:

  • Production: Use HTTPS ✓
  • Development: Use a loopback host for local HTTP testing ✓
  • Development: Use a local HTTPS endpoint with a trusted/self-signed cert if required ✓

Third-Party Cookies Required

Problem: Refresh reconnection doesn't work.

Solution: Enable third-party cookies in browser settings.

Affected scenarios:

  • Browser privacy mode
  • Safari with "Prevent cross-site tracking" enabled
  • Chrome with "Block third-party cookies" enabled

Distribution Method Confusion

MethodUse CaseAgent IntegrationBYOP Required
CDNMost use casesZoom-hosted iframeNo (auto PIN)
npmCustom agent UI, full controlCustom npm integrationYes (required)

Key Insight: If you want npm integration, you must use BYOP (Bring Your Own PIN) mode.

Cross-Origin Iframe Handling

Problem: Cobrowse doesn't work in cross-origin iframes.

Solution: Inject SDK snippet into cross-origin iframes:

<script>
const ZOOM_SDK_KEY = "YOUR_SDK_KEY_HERE";

(function(r,a,b,f,c,d){r[f]=r[f]||{init:function(){r.ZoomCobrowseSDKInitArgs=arguments}};
var fragment=a.createDocumentFragment();function loadJs(url) {c=a.createElement(b);d=a.getElementsByTagName(b)[0];c.async=false;c.src=url;fragment.appendChild(c);};
loadJs('https://us01-zcb.zoom.us/static/resource/sdk/${ZOOM_SDK_KEY}/js');d.parentNode.insertBefore(fragment,d);})(window,document,'script','ZoomCobrowseSDK');
</script>

Same-origin iframes: No extra setup needed.

Complete Documentation Library

This skill includes comprehensive guides organized by category:

Core Concepts

Examples

References

Troubleshooting

Resources

Need help? Start with Integrated Index section below for complete navigation.

Integrated Index

This section was migrated from SKILL.md.

Complete navigation guide for all Cobrowse SDK documentation.

Core Concepts

Foundational concepts you need to understand:

Examples and Patterns

Complete working examples for common scenarios:

Session Management

Features

References

Complete API and configuration references:

SDK Reference

  • API Reference - All SDK methods and interfaces

    • ZoomCobrowseSDK.init()
    • session.start()
    • session.join()
    • session.end()
    • session.on()
    • session.getSessionInfo()

  • Settings Reference - All initialization settings

    • allowAgentAnnotation
    • allowCustomerAnnotation
    • piiMask
    • remoteAssist
    • multiTabSessionPersistence

  • Session Events Reference - All event types

    • pincode_updated
    • session_started
    • session_ended
    • agent_joined
    • agent_left
    • session_error
    • session_reconnecting
    • remote_assist_started
    • remote_assist_stopped

Error Reference

  • Error Codes - Complete error code reference
    • 1001-1017: Session errors
    • 2001: Token errors
    • 9999: Service errors

Official Documentation

By Use Case

Find documentation by what you're trying to do:

I want to...

Set up cobrowse for the first time:

Add annotation tools:

Hide sensitive data from agents:

Let agents control customer's page:

Use custom PIN codes:

Handle page refreshes:

Integrate with npm (not CDN):

Debug session connection issues:

Configure CORS and CSP headers:

By Error Code

Quick lookup for error code solutions:

Session Errors

PIN Errors

Auth Errors

Service Errors

Official Resources

External documentation and samples:

Documentation Structure

cobrowse-sdk/
├── SKILL.md                    # Main skill entry point
├── SKILL.md                    # This file - complete navigation
├── get-started.md              # Step-by-step setup guide
│
├── concepts/                   # Core concepts
│   ├── two-roles-pattern.md
│   ├── session-lifecycle.md
│   ├── jwt-authentication.md
│   └── distribution-methods.md
│
├── examples/                   # Working examples
│   ├── customer-integration.md
│   ├── agent-integration.md
│   ├── annotations.md
│   ├── privacy-masking.md
│   ├── remote-assist.md
│   ├── multi-tab-persistence.md
│   ├── byop-custom-pin.md
│   ├── session-events.md
│   └── auto-reconnection.md
│
├── references/                 # API and config references
│   ├── api-reference.md        # SDK methods
│   ├── settings-reference.md   # Init settings
│   ├── session-events.md       # Event types
│   ├── error-codes.md          # Error reference
│   ├── get-started.md          # Official docs (crawled)
│   ├── features.md             # Official docs (crawled)
│   ├── authorization.md        # Official docs (crawled)
│   └── api.md                  # API docs (crawled)
│
└── troubleshooting/            # Problem resolution
    ├── common-issues.md
    ├── error-codes.md
    ├── cors-csp.md
    └── browser-compatibility.md

Search Tips

Find by keyword:

Not finding what you need? Check the Official Documentation or ask on the Dev Forum.

Environment Variables