Genesys Conversations API: 400 Bad Request when initiating cobrowse session via POST /cobrowse/sessions

We are attempting to initiate a cobrowse session programmatically through the Genesys Cloud Conversations API as part of a new support workflow. The goal is to trigger the session from our backend service using the POST /api/v2/cobrowse/sessions endpoint.

We have verified that the OAuth token has the necessary scopes (cobrowse:manage and cobrowse:session). The request payload follows the documentation structure for the session initiation object. Here is the JSON body we are sending:

{
 "sessionId": "sess_abc123",
 "participants": [
 {
 "id": "agent_user_id_from_db",
 "role": "agent"
 },
 {
 "id": "customer_user_id_from_db",
 "role": "customer"
 }
 ],
 "initiatorId": "agent_user_id_from_db"
}

The response we receive is a 400 Bad Request. The error body is not very descriptive:

{
 "code": "bad_request",
 "message": "Invalid session initiation parameters",
 "status": 400,
 "messageTemplate": "Invalid session initiation parameters",
 "errors": [
 {
 "code": "invalid_field",
 "message": "Field 'participants' contains invalid user ID format",
 "path": "participants[0].id"
 }
 ]
}

We have double-checked the user IDs. They are valid Genesys Cloud user IDs (UUID format). We also tried using the userId field instead of id in the participant object, but that resulted in the same error. The documentation mentions that the participant IDs must match users who are currently logged into Genesys Cloud. Both the agent and the customer (who is logged in via a custom app) are active.

Is there a specific format required for the id field in the participants array? Or is there a prerequisite API call we need to make to register the user for cobrowse before initiating the session? We are using the Python SDK for the initial authentication, but the cobrowse call is made via raw HTTP requests using requests.post().

Any insights into why the participants[0].id is being flagged as invalid would be appreciated.

You’re missing the initiator object in your payload. The API doesn’t just take a session ID or a target ID alone; it needs to know who is starting the cobrowse and who is receiving it. Without that explicit mapping, it throws a 400 because the routing engine has no idea where to push the session.

Here is the minimal payload structure that actually works. Note the type field must be cobrowse and the initiator section is mandatory.

{
 "id": "generated-session-id-123",
 "type": "cobrowse",
 "initiator": {
 "id": "user-id-of-agent-starting-session",
 "type": "user"
 },
 "target": {
 "id": "interaction-id-or-customer-id",
 "type": "interaction"
 },
 "settings": {
 "mode": "view"
 }
}

Also, double-check that the user ID you’re passing in the initiator section is actually logged into the Cobrowse agent application. If the user isn’t active in the Cobrowse UI, the API might accept the request but the session won’t actually connect on the client side. It’s a silent failure that wastes a lot of time debugging.

Another common trap is the target type. If you’re trying to cobrowse with a customer in an existing interaction, the target ID is the interaction ID, not the customer ID. If you use the customer ID, the system can’t link it to the active session.

Check your logs for the specific error message inside the 400 response body. It usually tells you exactly which field is missing or malformed. If it says invalid initiator, it’s the user ID. If it says invalid target, it’s the interaction ID.

Don’t forget to set the mode to view or control depending on what you want the agent to do. Defaulting to view is safer for initial tests.