POST /api/v2/interactions/cobrowse/sessions returning 422 when passing participant IDs through the JS SDK

PureCloudPlatformClientV2 actually expects the cobrowse payload to follow a specific structure, but I’m hitting a wall trying to initiate a session programmatically through the Conversations API. I’ve been trying to spin up a cobrowse session directly from our Node.js gateway service instead of relying on the web widget handshake. The docs say a POST to /api/v2/interactions/cobrowse/sessions should do it, but the response keeps coming back with a 422.

Here’s what the payload looks like when we push it through the SDK method:

const cobrowseBody = {
 conversationId: 'conv-8f3a2b1c-9d4e-4f1a-b2c3-d4e5f6a7b8c9',
 initiator: {
 id: 'user-123',
 type: 'agent'
 },
 participants: [
 { id: 'user-456', type: 'customer' }
 ],
 settings: {
 blockImages: false,
 enableAnnotations: true
 }
};

try {
 const session = await client.Cobrowse.createCobrowseSession(cobrowseBody);
 console.log('Session started:', session);
} catch (err) {
 console.error('Cobrowse failed:', err.status, err.body);
}

The error payload just says {"code":"unprocessable_entity","message":"Participant validation failed. Missing required interaction context.","status":422}. I know the conversation exists. We’ve already attached the customer to it via the webchat API. The user IDs are definitely valid in the org.

PureCloudPlatformClientV2 doesn’t expose a direct createCobrowseSession method anyway, so I’m actually dropping down to client.post('/api/v2/interactions/cobrowse/sessions', cobrowseBody) under the hood. That part works fine for other endpoints. The revision headers aren’t needed here either.

I tried stripping the settings object. Tried swapping the participant type to external. Same 422 every time. The interaction context is supposed to carry over from the parent conversation, but maybe the cobrowse endpoint expects a separate interactionId field instead of conversationId? Honestly, the swagger spec reads like it was written by a different team.

We’ve got a queue of agents waiting on this to test the new desktop assist flow. Any chance you’ve hit this validation wall before? Just looking for the exact JSON shape the endpoint actually wants. The queue is backing up anyway. Still debugging the payload shape.

Problem
The 422 error usually screams a schema mismatch. The cobrowse endpoint is strict about the participants array structure. You can’t just pass a raw ID string. The API expects a nested object with the id field inside the participant object. Missing the type field breaks the validation immediately.

Code
Check the payload shape. It’s gotta look like this before it hits the wire:

{
 "participants": [
 {
 "id": "your-participant-id-here",
 "type": "agent"
 }
 ],
 "interactionType": "cobrowse"
}

You’ll need to verify the serializer isn’t flattening the object. The SDK often drops nested keys if the definition isn’t explicit.

Error
A 422 means the server understands the content type but can’t process the instructions. In this case, the backend rejects the request because the participants array lacks the mandatory type discriminator. Check the errors array in the response JSON for the exact field name.

Question
Are you using a user access token or a client credential grant? The cobrowse session creation requires specific scopes. If the token lacks cobrowse:write, the request won’t clear the gateway config.