HTTP 409 Conflict When Disconnecting Participant via Conversations API

NICE CXone API & Integrations
1
  • Environment: NICE CXone Studio, Asia/Singapore
  • Method: REST Proxy (GetRESTProxy)
  • Endpoint: POST /api/v2/conversations/{conversationId}/participants/{participantId}/disconnect

Can anyone clarify the precise payload requirements for this endpoint? I am executing a POST request to terminate a specific participant within a conference call. However, the system consistently returns an HTTP 409 Conflict error. The request body contains the standard JSON structure, yet the operation fails to acknowledge the disconnection command. The inline code logic appears sound, yet the API rejects the call.

2

I’d recommend looking at at the request payload structure. The 409 conflict usually indicates a missing or malformed reason field. Ensure you provide a valid string for the disconnection cause.

{
 "reason": "user_request"
}

Verify the conversationId and participantId match the active session. Mismatched IDs also trigger this conflict status.

3

The quickest way to solve this is to ensure your ApiClient is configured with the correct region endpoint, as the Java SDK documentation states “base path must match the deployment environment,” which often causes silent routing failures.

  • Verify PlatformClientFactory region configuration
  • Check thread safety for concurrent disconnect calls
4

This looks like a common issue when the payload structure doesn’t align with what the GC API expects for participant disconnection. I’ve hit similar 409 errors in my Laravel apps using Guzzle. While reason: "user_request" is valid, you often need to include the cause field as well, depending on the conversation type.

Try this payload structure with Guzzle:

$client->post("/api/v2/conversations/{$convId}/participants/{$partId}/disconnect", [
 'json' => [
 'cause' => 'user_request',
 'reason' => 'Participant disconnected by user request'
 ],
 'headers' => [
 'Authorization' => 'Bearer ' . $token,
 'Content-Type' => 'application/json'
 ]
]);

Ensure your $token has the conversations:participant:disconnect scope. If you’re still getting a 409, check if the participant is already in a offline or dropped state, as disconnecting an already inactive participant throws a conflict. Also, verify the conversationId isn’t for a conversation that has already been fully terminated.

5

The way I solve this is by ensuring the reason field is strictly valid.

Cause: The 409 conflict often stems from an invalid reason string or missing cause.

Solution:

  1. Use "reason": "user_request".
  2. Verify participant status is connected.
{
 "reason": "user_request"
}