mirrors/anthropics--knowledge-work-plugins

Fork 0

Files

T

wehub-resource-sync f4548892ad chore: import upstream snapshot with attribution

2026-07-13 12:20:06 +08:00

15 KiB

Raw Permalink Blame History

Get Started with Zoom Cobrowse SDK

Complete setup guide from credentials to your first cobrowse session.

Overview

In a cobrowse session, there are two roles:

Customer (role_type=1) – Integrates the SDK into their website
Agent (role_type=2) – Uses an embedded iframe to interact with the customer

This guide shows you how to set up a customer-initiated session (the most common pattern).

Step 1: Get SDK Credentials

Requirements

Zoom Workplace Account with SDK Universal Credit
- See Build platform - create or update account for details
Video SDK App in Zoom Marketplace
- Cobrowse SDK is a feature of Video SDK (not a separate product)

Get Your Credentials

Access your SDK account web portal:
- In your Zoom Workplace account, go to Advanced > Zoom CPaaS > Manage
Click Build App
Locate your SDK credentials in the Cobrowse tab

You'll receive 4 credentials:

Credential	Type	Purpose
SDK Key	Public	Used in CDN URL and JWT `app_key` claim
SDK Secret	Private	Used to sign JWTs (server-side only)
API Key	Private	REST API authentication (optional)
API Secret	Private	REST API authentication (optional)

Save these credentials securely - you'll need them in the next step.

Step 2: Generate JWT Tokens

Both customers and agents require JSON Web Tokens (JWTs) for authentication.

JWT Structure

All JWTs have the same header:

{
  "alg": "HS256",
  "typ": "JWT"
}

The payload differs by role:

Customer JWT payload (role_type=1):

{
  "user_id": "user1_customer",
  "app_key": "YOUR_SDK_KEY",
  "role_type": 1,
  "user_name": "customer",
  "exp": 1723103759,
  "iat": 1723102859
}

Agent JWT payload (role_type=2):

{
  "user_id": "user2_agent",
  "app_key": "YOUR_SDK_KEY",
  "role_type": 2,
  "user_name": "agent",
  "exp": 1723103759,
  "iat": 1723102859
}

JWT Payload Fields

Field	Required	Description
`app_key`	Yes	Your Zoom SDK Key (not API Key)
`role_type`	Yes	User role: `1` = customer, `2` = agent
`iat`	Yes	Token issue timestamp (epoch)
`exp`	Yes	Token expiration timestamp (epoch). Min: 30 minutes, Max: 48 hours
`user_id`	Yes	Uniquely identifiable user ID
`user_name`	Yes	User name (max 80 characters)
`enable_byop`	Optional	Enable Bring Your Own PIN: `1` = yes, `0` or omit = no

Sign the JWT

Sign the JWT with your SDK Secret (not API Secret):

HMACSHA256(
  base64UrlEncode(header) + '.' + base64UrlEncode(payload),
  ZOOM_SDK_SECRET
);

Set Up a Token Server

CRITICAL: JWT signing must happen server-side to protect your SDK Secret.

Use the official auth endpoint sample:

# Clone the sample
git clone https://github.com/zoom/cobrowsesdk-auth-endpoint-sample.git
cd cobrowsesdk-auth-endpoint-sample

# Install dependencies
npm install

# Create .env file
cat > .env << EOF
ZOOM_SDK_KEY=your_sdk_key_here
ZOOM_SDK_SECRET=your_sdk_secret_here
PORT=4000
EOF

# Start the server
npm start

The server will run on the base URL you configure for your token service.

Token Request:

// POST https://YOUR_TOKEN_SERVICE_BASE_URL
{
  "role": 1,           // 1 = customer, 2 = agent
  "userId": "user123",
  "userName": "John Doe"
}

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

See also: JWT Authentication Concept

Step 3: Integrate the Customer SDK

The customer integrates the Cobrowse SDK into their website using the CDN.

Critical PIN Rule

The PIN agents should use comes from customer SDK event pincode_updated. Do not show or rely on provisional PIN values from backend/session placeholders. In UI, display one explicit value (for example, Support PIN) and pass only that to agent flow.

Load the SDK

Include the SDK snippet in the <head> tag of your HTML page:

<script type="module">
  const ZOOM_SDK_KEY = 'YOUR_SDK_KEY';
  
  (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/2.13.2`
    );
    d.parentNode.insertBefore(fragment, d);
  })(window, document, 'script', 'ZoomCobrowseSDK');
</script>

SDK Version

Set the SDK VERSION using semantic versioning:

Fixed version: js/2.13.2 - Use exact version 2.13.2
Latest patch: js/2.13.x - Use latest >=2.13.0 and <2.14.0

Current version: 2.13.2 (as of February 2026)

Initialize the SDK

const settings = {
  allowCustomerAnnotation: true,
  piiMask: { maskType: 'all_input' },
};

ZoomCobrowseSDK.init(settings, function ({ success, session, error }) {
  if (success) {
    console.log("SDK initialized successfully");
    // session object is now available
  } else {
    console.error("SDK init failed:", error);
  }
});

Start a Session

// Fetch JWT from your server
const response = await fetch('https://YOUR_TOKEN_SERVICE_BASE_URL', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    role: 1,
    userId: 'customer_' + Date.now(),
    userName: 'Customer'
  })
});
const { token } = await response.json();

// Start cobrowse session
session.start({ sdkToken: token });

Complete Customer Example

<!DOCTYPE html>
<html>
<head>
  <title>Customer - Cobrowse Support</title>
  <script type="module">
    const ZOOM_SDK_KEY = 'YOUR_SDK_KEY';
    
    // Load SDK from CDN
    (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/2.13.2`);
      d.parentNode.insertBefore(fragment, d);
    })(window, document, "script", "ZoomCobrowseSDK");
  </script>
</head>
<body>
  <h1>Need Help?</h1>
  <button id="cobrowse-btn" disabled>Loading...</button>
  <div id="pin-display"></div>
  
  <script type="module">
    let sessionRef = null;
    
    const settings = {
      allowAgentAnnotation: true,
      allowCustomerAnnotation: true,
      piiMask: {
        maskType: "custom_input",
        maskCssSelectors: ".sensitive-field"
      }
    };
    
    ZoomCobrowseSDK.init(settings, function({ success, session, error }) {
      if (success) {
        sessionRef = session;
        
        // Listen for PIN code
        session.on("pincode_updated", (payload) => {
          console.log("PIN Code:", payload.pincode);
          // This is the authoritative PIN for agent join
          document.getElementById("pin-display").innerHTML = 
            `<p><strong>Your PIN:</strong> ${payload.pincode}</p>
             <p>Share this with your support agent</p>`;
        });
        
        // Enable button
        document.getElementById("cobrowse-btn").disabled = false;
        document.getElementById("cobrowse-btn").innerText = "Start Support Session";
      } else {
        console.error("SDK init failed:", error);
      }
    });
    
    // Handle button click
    document.getElementById("cobrowse-btn").addEventListener("click", async () => {
      try {
        // Fetch JWT from your server
        const response = await fetch("https://YOUR_TOKEN_SERVICE_BASE_URL", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            role: 1,
            userId: "customer_" + Date.now(),
            userName: "Customer"
          })
        });
        const { token } = await response.json();
        
        // Start session
        sessionRef.start({ sdkToken: token });
      } catch (error) {
        console.error("Failed to start session:", error);
      }
    });
  </script>
</body>
</html>

Step 4: Use Zoom-Hosted Agent Portal

Agents connect to cobrowse sessions by embedding an iframe.

Agent Portal Iframe

<!DOCTYPE html>
<html>
<head>
  <title>Agent Portal</title>
</head>
<body>
  <h1>Agent Support Portal</h1>
  <iframe 
    id="agent-iframe"
    width="1024" 
    height="768"
    src=""
    allow="autoplay *; camera *; microphone *; display-capture *; geolocation *;"
  ></iframe>
  
  <script>
    async function connectAgent() {
      try {
        // Fetch JWT from your server
        const response = await fetch("https://YOUR_TOKEN_SERVICE_BASE_URL", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            role: 2,
            userId: "agent_" + Date.now(),
            userName: "Support Agent"
          })
        });
        const { token } = await response.json();
        
        // Load Zoom agent portal with token
        const iframe = document.getElementById("agent-iframe");
        iframe.src = `https://us01-zcb.zoom.us/sdkapi/zcb/frame-templates/desk?access_token=${token}`;
      } catch (error) {
        console.error("Failed to connect agent:", error);
      }
    }
    
    // Auto-connect on page load
    connectAgent();
  </script>
</body>
</html>

Iframe Permissions

The allow attribute must include these permissions:

autoplay * - Auto-play media
camera * - Camera access
microphone * - Microphone access
display-capture * - Screen capture
geolocation * - Location services

Step 5: Test the Cobrowse SDK

Testing Steps

Open two browsers (or use incognito + normal mode):
- Browser A: Customer page
- Browser B: Agent page
Customer browser:
- Open customer page
- Click "Start Support Session" button
- Note the 6-digit PIN displayed
Agent browser:
- Open agent page
- Enter the PIN code in the iframe
Verify connection:
- Agent should now see the customer's browser
- Both sides should show "Connected" status
Test features:
- Annotations: Agent can draw on the screen
- Data masking: Masked fields show asterisks for agent
- Remote assist: Agent can scroll the page (if enabled)
End session:
- Either side can click "End Session" to terminate

Troubleshooting Test Issues

Issue	Solution
SDK doesn't load	Verify SDK Key is correct in CDN URL
PIN not showing	Check browser console for errors
Agent can't connect	Verify PIN is correct and session is still active
Connection fails	Check HTTPS is being used (or a loopback host for development)

Step 6: Add Features

Now that you have a working cobrowse session, add features:

Annotation Tools

Enable drawing tools for customer and/or agent:

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

See: Annotation Tools Example

Data Masking

Hide sensitive fields from agents:

const settings = {
  piiMask: {
    maskType: 'custom_input',
    maskCssSelectors: '.sensitive-field, #ssn, #credit-card',
    maskHTMLAttributes: 'data-sensitive=true'
  }
};

See: Privacy Masking Example

Remote Assist

Allow agent to scroll the customer's page:

const settings = {
  remoteAssist: {
    enable: true,
    enableCustomerConsent: true,        // Customer must approve
    remoteAssistTypes: ['scroll_page']
  }
};

See: Remote Assist Example

Bring Your Own PIN (BYOP)

Use custom PIN codes instead of auto-generated ones:

Enable BYOP in JWT payload:
```
{
  "enable_byop": 1,
  ...
}
```

Provide custom PIN when starting session:

session.start({
  customPinCode: 'MYPIN123',
  sdkToken: token
});

See: BYOP Custom PIN Example

Next Steps

Learn core concepts: Session Lifecycle
Explore features: Complete documentation index
Handle errors: Error Codes Reference
Production checklist: CORS and CSP Configuration

PIN Code Access - Bring Your Own PIN (BYOP)

The Cobrowse SDK supports connecting agents and customers using a PIN code. In the simple example above, Zoom automatically generates a 6-digit PIN code displayed to the customer.

Auto-generated PIN flow:

Customer clicks "Start Support Session"
Zoom generates 6-digit PIN
Customer shares PIN with agent
Agent enters PIN to connect

Custom PIN flow (BYOP):

Your app generates custom PIN code (1-10 characters, letters/numbers)
Pass PIN when starting session: session.start({ customPinCode: 'MYPIN', sdkToken })
Agent enters your custom PIN to connect

BYOP enables:

Integration with existing support ticket systems
Use of case/ticket IDs as PINs
npm integration for custom agent UI

See: Bring Your Own PIN (BYOP) for complete guide.

Resources

Official Docs: https://developers.zoom.us/docs/cobrowse-sdk/
API Reference: https://marketplacefront.zoom.us/sdk/cobrowse/
Quickstart Repo: https://github.com/zoom/CobrowseSDK-Quickstart
Auth Endpoint Sample: https://github.com/zoom/cobrowsesdk-auth-endpoint-sample
Dev Forum: https://devforum.zoom.us/

Common Questions

Q: Can I use HTTP instead of HTTPS?
A: Only for loopback/local development. Production must use HTTPS.

Q: What's the difference between SDK Key and API Key?
A: SDK Key is used in the CDN URL and JWT app_key claim. API Key is for optional REST API calls.

Q: Can multiple agents join the same session?
A: Yes, up to 5 agents can join a single customer session.

Q: Does the customer need to install anything?
A: No, it's pure JavaScript delivered via CDN. No plugins or extensions needed.

Q: What happens if the customer refreshes the page?
A: The session will attempt to automatically reconnect within a 2-minute window.

Q: Can I customize the agent portal UI?
A: Not with the iframe approach. For custom UI, use npm integration with BYOP mode.

15 KiB Raw Permalink Blame History Unescape Escape