How to initiate a cobrowse session programmatically via Conversations API?

NICE CXone API & Integrations
1

I’ve been wrestling with the Conversations API for a bit now, trying to figure out the right way to kick off a cobrowse session directly from our backend service. The goal is pretty straightforward. We want to start a session without the agent having to click anything in the UI. The agent just needs to be in a voice or chat interaction, and then our system triggers the cobrowse.

I found the POST /api/v2/conversations/{conversationId}/cobrowse endpoint in the docs, but I’m not sure if that’s the right one for initiating it from the server side. Or maybe I need to use the cobrowse.initiate action in an Architect flow first? I tried sending a simple JSON payload to that endpoint, but I keep getting a 400 Bad Request. The error message is pretty vague, just saying “Invalid request body.” Here’s what I’ve been sending:

{
 "sessionId": "new-session",
 "type": "cobrowse"
}

I also tried including the agent’s user ID in the payload, thinking maybe the API needs to know who is starting the session. But that didn’t help either. I’m using the Python SDK, and here’s the snippet I’m working with:

from genesyscloud.conversations import ConversationsApi

api_instance = ConversationsApi(api_client)
body = {
 "sessionId": "test-session",
 "type": "cobrowse"
}
try:
 api_response = api_instance.post_conversations_cobrowse(conversation_id, body)
 print(api_response)
except Exception as e:
 print("Exception when calling ConversationsApi->post_conversations_cobrowse: %s\n" % e)

The error I’m getting is something like {'status': 400, 'message': 'Invalid request body', 'errors': [...]}. I’ve checked the conversation ID, and it’s definitely active. The agent is logged in and has the right permissions. Is there a specific field I’m missing? Or is this endpoint not meant for server-side initiation? I’m a bit stuck on this one. Any pointers would be great.

2

Are you passing the agent ID in the request body, or just hitting the endpoint with the conversation ID? That endpoint is pretty strict about context.

Here’s what usually gets it working:

  • Make sure the agent is actually in an active conversation. You can’t cobrowse a void.
  • Use the POST /api/v2/conversations/{conversationId}/cobrowse endpoint.
  • The payload needs the agentId and cobrowseType. If you leave cobrowseType off, it defaults to view, which might not be what you want if you need control.
{
 "agentId": "your-agent-id-here",
 "cobrowseType": "control"
}

If you’re using the Python SDK, it looks like this:

from platformclientv2 import CobrowseParticipant

cobrowse_req = CobrowseParticipant(
 agent_id="your-agent-id-here",
 cobrowse_type="control"
)

# Assuming `conversations_api` is your initialized API instance
result = conversations_api.post_conversations_cobrowse(
 conversation_id="your-conversation-id",
 body=cobrowse_req
)

Watch out for the 403 if the agent doesn’t have the cobrowse:agent permission. It’s easy to miss that in the role config.