Could someone explain the exact payload structure required to initiate a cobrowse session programmatically through the Genesys Cloud Conversations API when triggered by a PagerDuty incident webhook? I am building an auto-escalation flow where a critical SLA breach in GC triggers a PagerDuty event, which then needs to immediately start a cobrowse session with the agent handling the conversation to allow remote debugging. I have the conversation ID and the agent ID from the analytics alert, but I am struggling to find the correct endpoint under /api/v2/conversations. I tried making a POST request to /api/v2/conversations/webchat/{conversationId}/cobrowse using the standard OAuth2 bearer token, but I am consistently receiving a 404 Not Found error. Here is the JSON payload I am sending: { “participantId”: “agent-id-123”, “sessionId”: “session-456”, “initiatorType”: “agent” }. I suspect that the cobrowse initiation might require a different sub-resource or perhaps needs to be handled through the Guest API or a specific Data Action in Architect rather than a direct REST call. I have checked the API documentation for cobrowse, but it mostly focuses on the UI integration and the JavaScript SDK methods like cobrowse.initiate(). I need a pure API approach because this is running in a serverless function handling the PagerDuty webhook. Is there a specific header or query parameter I am missing? Also, does the agent need to have an active webchat session for this API call to succeed, or can it be pre-emptively created? Any code examples showing the exact HTTP request format would be appreciated. I want to ensure that the session link is generated correctly so I can push it back to the PagerDuty incident notes for audit trails. My environment is using the latest GC API version, and I have verified that the user making the request has the cobrowse:initiate permission. Please advise on the correct endpoint path and payload schema.
I think the Conversations API does not support direct cobrowse initiation via a single HTTP POST. You must use the Genesys Cloud Client SDK to emit a cobrowse:start event within the active conversation. This approach is more reliable for CI/CD tested workflows because it respects the WebSocket handshake required for media streams. Below is a Node.js example using the purecloud-platform-client-v2 SDK.
const platformClient = require("purecloud-platform-client-v2");
async function startCobrowse(conversationId, agentId) {
try {
const conversationsApi = platformClient.ConversationsApi();
// 1. Retrieve the active conversation to get the participant ID
const conversation = await conversationsApi.getConversation(conversationId);
const agentParticipant = conversation.participants.find(p => p.id === agentId);
if (!agentParticipant) {
throw new Error("Agent not found in conversation");
}
// 2. Emit the cobrowse start event
const eventPayload = {
eventType: "cobrowse:start",
data: {
initiatorId: agentParticipant.id,
targetId: agentParticipant.id, // Self-initiated or specify other
mode: "interactive"
}
};
await conversationsApi.postConversationEvent(conversationId, {
body: eventPayload
});
console.log("Cobrowse session initiated successfully.");
} catch (error) {
console.error("Failed to start cobrowse:", error.message);
}
}
Ensure your OAuth token includes conversation:view and cobrowse:write scopes. The PagerDuty webhook should call a middleware endpoint (e.g., Express.js) that executes this logic, rather than hitting the GC API directly, to handle authentication securely.