Can anyone clarify the correct sequence for terminating a Web Messaging session from the backend? I am building a TypeScript service that manages session state independently of the client SDK. The goal is to programmatically close the conversation when specific backend conditions are met, ensuring the client receives the proper termination signal without manual intervention.
I am using the genesys-cloud/platform-client-sdk (v2.20.0). I successfully create the conversation using the standard POST /api/v2/conversations/messaging endpoint. However, closing it is problematic. The documentation suggests updating the conversation state, but Web Messaging sessions do not have a traditional ‘state’ like voice calls. I attempted to use the PATCH /api/v2/conversations/messaging/{conversationId} endpoint with a payload intended to signal closure, but the client SDK remains in an ‘active’ state and does not emit the expected close event.
The API returns HTTP 200 OK, confirming the request was accepted. Yet, the conversation.conversationState remains unchanged in subsequent GET requests, and the guest client does not disconnect. I also tried deleting the conversation via DELETE /api/v2/conversations/messaging/{conversationId}, but this returns a 409 Conflict with the message “Conversation cannot be deleted while active.” This implies a specific transition is required before deletion or that a different mechanism exists for graceful shutdown.
Is there a specific endpoint or payload structure to trigger the session end? Or is the only viable path to send a close message via the messaging API and then wait for client acknowledgment? I need a deterministic backend-driven closure pattern.
Check your implementation of the session termination logic. The issue likely stems from attempting to close the conversation resource directly rather than ending the participant’s engagement properly. In Web Messaging, simply deleting the conversation can lead to state mismatches between the backend and the client SDK.
Cause:
The DELETE /api/v2/conversations/webmessaging/{conversationId} endpoint removes the conversation record but does not always trigger the correct “ended” event on the client side if the participant is still technically active. The client SDK expects an explicit end state from the participant resource to clear the UI and stop polling.
Solution:
You must first end the participant using the Conversations API, then optionally delete the conversation if you want to purge the history. Use the PureCloudPlatformClientV2 SDK in TypeScript. Here is the correct sequence:
import { WebMessagingApi, ConversationParticipant } from '@genesyscloud/platform-client-sdk';
async function closeWebMessagingSession(conversationId: string, participantId: string, webMessagingApi: WebMessagingApi) {
// 1. End the participant to signal the client
const endParticipantBody: ConversationParticipant = {
ended: true,
endedReason: "agent" // or "other" depending on your flow
};
try {
await webMessagingApi.postConversationWebmessagingParticipantEnd({
conversationId: conversationId,
conversationParticipantId: participantId,
body: endParticipantBody
});
console.log(`Participant ${participantId} ended successfully.`);
// 2. Optional: Delete the conversation if retention policies allow
// await webMessagingApi.deleteConversationWebmessaging({ conversationId: conversationId });
} catch (error) {
console.error("Failed to end participant:", error);
throw error;
}
}
Ensure you have the conversation:write OAuth scope. This approach guarantees the client receives the termination signal and updates its UI state correctly.