Initiating Cobrowse Session via Conversations API

Hey folks,

I’m trying to programmatically start a cobrowse session using the Genesys Cloud Conversations API. We need this for a specific workflow where the agent triggers the session from an external tool rather than the standard agent desktop UI.

I’ve been looking at the documentation for /api/v2/conversations/webchat and the cobrowse endpoints, but I’m a bit lost on the exact payload structure required to initiate the session. I tried sending a POST request to the cobrowse endpoint with a basic JSON body containing the conversation ID and participant IDs, but I keep getting a 400 Bad Request error.

Here’s the cURL command I’ve been testing:

curl -X POST "https://{{my-domain}}.mypurecloud.com/api/v2/conversations/cobrowse/sessions" \
 -H "Authorization: Bearer {{access_token}}" \
 -H "Content-Type: application/json" \
 -d '{
 "conversationId": "12345678-abcd-1234-abcd-123456789abc",
 "initiatorId": "87654321-dcba-4321-dcba-987654321xyz"
 }'

The error response just says “Invalid request body” without much detail. I’ve checked the OAuth token and it’s valid for the scope cobrowse:write. Is there a specific field I’m missing or a different endpoint I should be hitting? I’ve tried looking at the SDK examples but they seem to focus more on the client-side JavaScript integration.

Any help would be appreciated.

Are you trying to inject the cobrowse session into an existing webchat conversation, or is this a standalone session? The payload structure changes significantly depending on the context. If it’s tied to a webchat, you don’t POST to the cobrowse endpoint directly. You use the webchat conversation ID to create the cobrowse participant.

Here’s the curl command we use in our custom desktop to attach cobrowse to an active webchat session. Make sure your token has the cobrowse:session:create scope, or it’ll fail with a 403.

curl -X POST "https://api.mypurecloud.com/api/v2/conversations/webchat/{conversationId}/cobrowse" \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "type": "cobrowse",
 "initiatorType": "agent",
 "capabilities": ["screen", "mouse", "keyboard"]
 }'

The response gives you the session ID you’ll need for the client SDK. If you’re building a custom agent desktop, watch out for the latency on the handshake. The client app needs to receive the session token before the browser extension can attach. We’ve seen race conditions where the agent clicks “start” but the customer’s browser hasn’t initialized the listener yet.