Trying to kick off a cobrowse session via the API. The docs say POST /api/v2/conversations/{conversationId}/cobrowse.
POST /api/v2/conversations/{conversationId}/cobrowse
Getting a 409 Conflict. Body says conversation already exists. I checked the active conversations endpoint, nothing is running. Is there a stale session lock I need to clear first? Or is the SDK handling the handshake differently than raw HTTP?
The 409 Conflict usually isn’t a stale lock. It’s the platform trying to prevent duplicate session creation for the same user context. The API is strict about the conversation state. If you try to start a cobrowse session on a conversation that already has an active cobrowse session, Genesys will flag it as a conflict.
You need to ensure the target conversation does not already have an active cobrowse session. Do not attempt to create a new session on an existing active one. Also, check if you are missing the required permissions. The endpoint requires conversation:cobrowse:add (for web messaging) or conversation:cobrowsevoice:add.
Here is the correct endpoint structure I use in my integration tests:
POST /api/v2/conversations/{conversationId}/cobrowse
Note that this endpoint does not accept a request body. The conversationId is the only path parameter required.
If you are still getting 409 after ensuring the conversation is clear of other cobrowse sessions, check the GET /api/v2/conversations/cobrowsesessions endpoint. Sometimes a session is marked as “ended” in the summary view but still active in the cobrowse service for a short retention period.
Also, verify your OAuth scope. You need the appropriate cobrowse permissions mentioned above. If the token lacks the write/add permission, it can sometimes throw misleading errors, though usually it’s a 403. But 409 is definitely a resource conflict.
Try clearing your browser cache on the agent side too. The cobrowse client might be holding onto a stale session token. I’ve seen this happen when agents refresh the page mid-session. The API thinks the session is still alive because the client hasn’t sent the proper close signal.
If the issue persists, check the server logs for the specific conversation ID. The error response should include a conversationId. Use that to query GET /api/v2/conversations/{conversationId}. That will tell you the actual state. It might be pending or active even if it looks dead to you.
the earlier post’s got the right idea with the sessionId uniqueness, but there’s another gotcha I’ve run into with the JS SDK that often trips people up. The 409 usually means the platform thinks the conversation is still active on the server side, even if your local state says otherwise.
Check your auth headers first. If you’re reusing an expired token or missing the application/json content type, the platform might throw a conflict instead of a bad request. Also, make sure you’re actually waiting for the previous cobrowse session to fully terminate before kicking off a new one. The API doesn’t clean up instantly.
Here’s how I handle the cleanup in Node.js before starting a new session:
const { ConversationApi } = require('purecloud-platform-client-v2');
async function cleanupAndStart(userId, newSessionId) {
const conversationApi = new ConversationApi();
// List active cobrowse conversations for this user
const active = await conversationApi.postConversationsCobrowseList({
body: { userIds: [userId] }
});
if (active.entities && active.entities.length > 0) {
console.log('Active session found, disconnecting first...');
const convId = active.entities[0].id;
await conversationApi.postConversationsIdDisconnect(convId, {
body: { participantId: 'user' } // Disconnect the user side
});
}
// Now start fresh
return await conversationApi.postConversationsCobrowse({
body: {
userId: userId,
sessionId: newSessionId, // Ensure this is truly unique, e.g., UUID v4
duration: 300
}
});
}
Double-check that sessionId is a fresh UUID every time. Reusing one is the fastest way to get that 409.