POST /api/v2/conversations/webchat returned 400 Bad Request: {“code”:“bad.request”,“message”:“Invalid request body. The ‘cobrowse’ field requires a valid session initiation object.”,“status”:“Bad Request”}
I am trying to programmatically initiate a cobrowse session from a custom Node.js microservice that integrates with our Genesys Cloud observability stack. The goal is to start a cobrowse session immediately after a specific high-severity APM trace is detected in Datadog, allowing our support agents to jump into the user’s context without manual intervention.
I have successfully authenticated using client credentials and obtained a valid access token. The standard webchat conversation creation works fine. However, when I add the cobrowse object to the payload, the API rejects it. I have verified that my user has the cobrowse:write permission and that the cobrowse feature is enabled in our Genesys Cloud organization settings.
Here is the payload I am sending:
{
"type": "webchat",
"to": {
"id": "webchat-session-12345",
"type": "webchat"
},
"cobrowse": {
"action": "initiate",
"session": {
"id": "new-cobrowse-session",
"mode": "interactive"
}
}
}
The webchat-session-12345 is a valid, active session ID retrieved from the /api/v2/conversations endpoint. I also tried using the cobrowse field at the root level of the payload, but that resulted in a 422 Unprocessable Entity error stating that the field is not recognized in that context.
I suspect I might be missing a specific header or the structure of the cobrowse object is slightly off, perhaps requiring a specific correlationId or a nested context object that is not clearly documented in the standard OpenAPI spec. Has anyone successfully initiated a cobrowse session this way? I am looking for the exact JSON structure expected by the cobrowse field within the conversation creation payload.
Have you tried restructuring the cobrowse object to explicitly include the initiatorId and participantId fields? The 400 Bad Request error usually stems from an incomplete initiation object rather than authentication issues.
In Genesys Cloud, a cobrowse session requires a clear definition of who is initiating the session and who is being monitored. If you omit the initiatorId, the platform cannot assign the session to an agent or supervisor. Additionally, ensure the cobrowse field is nested correctly within the main conversation body, not at the root level.
Here is the corrected JSON payload structure for POST /api/v2/conversations/webchat:
{
"to": {
"id": "your-queue-id",
"type": "queue"
},
"from": {
"id": "your-webchat-widget-id",
"type": "webchat"
},
"cobrowse": {
"initiatorId": "agent-user-id-or-supervisor-id",
"participantId": "guest-id-or-external-id",
"reason": "High severity APM trace detected"
},
"wrapUpCode": null
}
Make sure agent-user-id-or-supervisor-id is a valid Genesys Cloud user ID with cobrowse permissions. The guest-id-or-external-id should match the identifier used in your webchat widget configuration. If you are using the Node.js SDK, you can construct this using CreateConversationWebchatRequest.
Also, verify that your OAuth token includes the cobrowse:write scope. Without it, even a perfectly formatted payload will fail. Check your Express middleware logs to ensure the scope is present in the request headers. If the error persists, enable debug logging on the Genesys Cloud side to capture the exact validation failure. This often reveals missing nested fields that the generic 400 error doesn’t specify.
To fix this easily, this is to ensure the cobrowse object strictly follows the initiation schema with explicit IDs, as the validator rejects partial payloads.
{
"cobrowse": {
"initiatorId": "agent-uuid-here",
"participantId": "user-uuid-here",
"type": "initiate"
}
}
Missing either ID triggers that exact 400 bad request, so double-check your UUIDs are not null.
If I remember right, the type field must be initiate to avoid that 400 error.
{
"cobrowse": {
"initiatorId": "agent-uuid-here",
"participantId": "user-uuid-here",
"type": "initiate"
}
}
I had the same issue in my Terraform data source until I fixed the payload structure.
How I usually solve this is by verifying the oauth token has the conversation:webchat:write scope. the payload structure is correct but missing scopes cause schema validation failures in the node sdk. check your platformClient credentials.