Setting the file. One moment.
Subchapter 106.27
get-started.mdMarkdown15 KBView on GitHub
Complete setup guide from credentials to your first cobrowse session.
In a cobrowse session, there are two roles:
This guide shows you how to set up a customer-initiated session (the most common pattern).
Zoom Workplace Account with SDK Universal Credit
Video SDK App in Zoom Marketplace
Access your SDK account web portal:
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.
Both customers and agents require JSON Web Tokens (JWTs) for authentication.
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
}| 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 with your SDK Secret (not API Secret):
HMACSHA256(
base64UrlEncode(header) + '.' + base64UrlEncode(payload),
ZOOM_SDK_SECRET
);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 startThe 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
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.
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>Set the SDK VERSION using semantic versioning:
js/2.13.2 - Use exact version 2.13.2js/2.13.x - Use latest >=2.13.0 and <2.14.0Current version: 2.13.2 (as of February 2026)
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);
}
});// 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 });<!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>Agents connect to cobrowse sessions by embedding an 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>The allow attribute must include these permissions:
autoplay * - Auto-play mediacamera * - Camera accessmicrophone * - Microphone accessdisplay-capture * - Screen capturegeolocation * - Location servicesOpen two browsers (or use incognito + normal mode):
Customer browser:
Agent browser:
Verify connection:
Test features:
End session:
| 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) |
Now that you have a working cobrowse session, add features:
Enable drawing tools for customer and/or agent:
const settings = {
allowAgentAnnotation: true, // Agent can draw
allowCustomerAnnotation: true // Customer can draw
};Hide sensitive fields from agents:
const settings = {
piiMask: {
maskType: 'custom_input',
maskCssSelectors: '.sensitive-field, #ssn, #credit-card',
maskHTMLAttributes: 'data-sensitive=true'
}
};Allow agent to scroll the customer’s page:
const settings = {
remoteAssist: {
enable: true,
enableCustomerConsent: true, // Customer must approve
remoteAssistTypes: ['scroll_page']
}
};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
});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:
Custom PIN flow (BYOP):
session.start({ customPinCode: 'MYPIN', sdkToken })BYOP enables:
See: Bring Your Own PIN (BYOP) for complete guide.
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.