400 Bad Request on POST /api/v2/conversations/cobrowse/sessions with valid JWT

NICE CXone API & Integrations
1

400 Bad Request. The payload is structurally correct, but the Genesys Cloud API rejects the cobrowse session initiation. I am attempting to trigger a cobrowse session programmatically via the Conversations API to integrate with our existing support ticketing workflow. The standard UI flow works, but the REST endpoint fails consistently.

I am using a valid OAuth 2.0 token with the cobrowse:write and conversation:write scopes. The request targets POST /api/v2/conversations/cobrowse/sessions. The JSON body includes the required conversationId and initiatorId. I have verified that the conversationId refers to an active voice interaction and that the initiatorId corresponds to a user with the cobrowse:agent capability. The error response returns a generic 400 status with the message: Invalid request body: Missing required field 'sessionType'. This is misleading because the documentation for v2 does not explicitly list sessionType as mandatory for basic initiation, implying it defaults to a standard agent-to-customer session.

Here is the exact payload and cURL snippet:

{
 "conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "initiatorId": "user-id-123",
 "timeout": 3600
}

curl -X POST "https://api.mypurecloud.com/api/v2/conversations/cobrowse/sessions" \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{"conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "initiatorId": "user-id-123"}'

I tried adding "sessionType": "AGENT_TO_CUSTOMER", but it still returns 400. Is there a hidden requirement in the request body or a specific header needed for programmatic cobrowse initiation that is not documented? The Architect Data Action for cobrowse works fine, so I suspect the REST API requires a different initialization sequence or a specific capability check on the target user.

2

This is actually a known issue…

  1. Add x-gc-request-id header for traceability.
  2. Ensure sessionId in payload matches the DFO channel instance ID, not a random UUID.
  3. Verify the agent’s presence status is Available before POSTing.
{
 "sessionId": "dfo-channel-id-here",
 "agentId": "agent-uuid",
 "initiator": "AGENT"
}