Kickstarting a Cobrowse session via API for outbound flows?

NICE CXone API & Integrations
1

Hey folks,

I’m trying to automate the start of a cobrowse session from within our outbound dialer logic. The goal is to have the agent click a button in the desktop app, which hits our backend, and that backend calls Genesys to force the customer’s browser into cobrowse mode.

I’ve been digging through the Conversations API docs and the Cobrowse specific endpoints, but it feels like the initiate action is strictly tied to the participant’s active web session cookie, which makes sense for inbound. For outbound, the customer isn’t in the browser yet when the call connects.

I tried hitting the standard conversation update endpoint with the cobrowse payload, but it just fails with a 400 Bad Request. Here’s the payload I’m sending to PATCH /api/v2/conversations/{conversationId}:

{
 "actions": [
 {
 "type": "update",
 "settings": {
 "cobrowse": {
 "enabled": true,
 "url": "https://www.example.com/support"
 }
 }
 }
 ]
}

The error response is pretty vague:

{
 "code": "badRequest",
 "message": "Invalid cobrowse action. Participant does not have an active web session."
}

Here’s the setup:

  • Genesys Cloud version: 2024-02
  • Auth: OAuth2 client credentials flow, scopes include cobrowse:write and conversation:write
  • The conversation ID is valid and the call is active (state: connected)
  • We’re using Python requests library

Is there a specific sequence I’m missing? Do I need to push a deep link to the customer’s phone first via SMS, wait for them to open it, and then trigger the API call? Or is there a way to bind the cobrowse session to the outbound call ID directly?

Any code snippets or examples of how you’ve handled this would be huge. I feel like I’m banging my head against a wall here.

2

Are you trying to push the cobrowse session directly from the server, or are you just generating the invite token? The POST /api/v2/cobrowse/invites endpoint doesn’t actually start the session on the client side. It just creates an invite object. You’ll need the client SDK to accept it.

Here’s how I handle this in my instrumentation layer. First, create the invite.

const platformClient = require('genesyscloud');

async function createCobrowseInvite(conversationId, participantId) {
 const cobrowseApi = platformClient.CobrowseApi();
 
 const inviteBody = {
 conversationId: conversationId,
 participantId: participantId,
 initiatorId: "SYSTEM_AUTO" // or your agent ID if needed
 };

 try {
 const invite = await cobrowseApi.postCobrowseInvites(inviteBody);
 console.log("Invite created:", invite.id);
 return invite;
 } catch (error) {
 console.error("Failed to create invite:", error);
 throw error;
 }
}

The tricky part is that the customer’s browser needs to poll for this invite or have the SDK initialized to listen for the event. If you’re using the Web Messaging SDK, you can hook into the cobrowse.invite event.

const webMessagingSdk = new genesyscloud.webmessaging.WebMessaging({
 appId: "your-app-id",
 organizationId: "your-org-id"
});

webMessagingSdk.on('cobrowse.invite', (event) => {
 console.log("Cobrowse invite received", event);
 // Auto-accept or prompt user
 // webMessagingSdk.acceptCobrowseInvite(event.inviteId);
});

If you’re trying to force it without the client SDK being ready, you’re out of luck. The API just sets the state in Genesys. The client has to do the heavy lifting. Make sure your outbound flow waits for the cobrowse.started event before proceeding.

3

’s got the right idea about the invite, but there’s a bigger fish here. You can’t just “force” a browser into cobrowse mode from the server side via an API call. That’s not how the security model works. The client has to opt-in.

The outbound flow needs to look different. You don’t kickstart the session with an API call to the customer. You kickstart it by pushing the invite token to the customer’s channel, then letting their browser handle the handshake.

Here’s the pattern that actually sticks:

  1. Agent clicks the button in the desktop app.
  2. Your backend calls POST /api/v2/cobrowse/invites.
  3. You grab the invite.id from the response.
  4. You push that ID to the customer using the active conversation channel (usually a custom message or a specific URL if it’s webchat).

If you’re on a voice call, you’re stuck. Cobrowse is web-only. If it’s webchat or messaging, you can send the invite link.

// Genesys Cloud SDK v2 (Node.js)
const { platformClient } = require('genesyscloud');

async function createCobrowseInvite(conversationId) {
 const cobrowseApi = platformClient.CobrowseApi;

 const invite = {
 conversationId: conversationId,
 initiatorRole: 'agent' // or 'customer' depending on who starts
 };

 try {
 const result = await cobrowseApi.postCobrowseInvites(invite);
 console.log('Invite created:', result.id);
 return result;
 } catch (error) {
 console.error('Failed to create invite:', error);
 throw error;
 }
}

The tricky part is getting that invite.id into the customer’s hand. You can’t just email it. It needs to be injected into their active session. If you’re using the Genesys Web Messaging widget, there’s a method to accept invites, but it has to be triggered by the client.

If you’re building a custom frontend, you’d use the genesyscloud-messaging-web SDK to listen for the invite event and prompt the user.

// Client-side snippet (conceptual)
const messagingClient = new GenesysCloudMessagingWeb();

messagingClient.on('inviteReceived', (invite) => {
 // Show UI to user: "Agent wants to cobrowse. Accept?"
 if (userAccepts) {
 messagingClient.acceptInvite(invite.id);
 }
});

Don’t waste time trying to find a “force start” endpoint. It doesn’t exist. The security boundary is intentional. Focus on the UX of how the customer accepts the invite.