Conversations API: Hanging up single participant in conference without killing the call

Hey folks,

We’re trying to build a supervisor tool that lets them drop a specific agent from a conference call without terminating the whole thing. The usual pattern seems to be to just end the conversation, but that kills it for everyone, which is exactly what we don’t want.

I found this endpoint: POST /api/v2/conversations/voice/legactions/participants. The docs say you can use action: "hangup" to disconnect a participant. Seems straightforward enough. Here is the payload I’m sending:

{
 "participants": [
 {
 "id": "agent-uuid-123"
 }
 ],
 "action": "hangup"
}

I’m getting a 202 Accepted back, so the API thinks everything is fine. But the agent stays on the line. They can still hear the other participants. I’ve waited a few minutes, checked the conversation logs in the UI, and nothing happened to that leg.

I’ve tried using action: "mute" and that works instantly, so I know I have the right participant ID and the right conversation ID. I’m using the standard Python SDK, just calling post_voice_leg_actions_participants.

Am I missing a step? Is there a different endpoint I should be hitting for this? The docs are pretty sparse on the “how-to” for this specific use case.

Here’s the relevant bit of Python code:

from purecloudplatformclientv2 import ConversationApi, VoiceLegActionsParticipants

api_instance = ConversationApi(configuration)
body = VoiceLegActionsParticipants(
 participants=[{'id': 'agent-uuid-123'}],
 action='hangup'
)
try:
 api_response = api_instance.post_voice_leg_actions_participants(conversation_id, body)
 print(api_response) # Returns 202
except Exception as e:
 print("Exception when calling ConversationApi->post_voice_leg_actions_participants: %s\n" % e)

Anyone else run into this?

The endpoint is correct, but the payload structure trips people up constantly. You need to target the specific leg, not just the conversation. The docs for LegActionsParticipant mention: “The participantId is required. The action determines the type of leg action.”

Here’s how I do it in C# using the SDK. It’s async, obviously.

var client = new PureCloudPlatformClientV2.Configuration(...);
var callsApi = new PlatformClient.CallsApi(client);

var action = new PostConversationVoiceLegactionsParticipantsRequest
{
 ConversationId = "your-conv-id",
 ParticipantId = "agent-leg-id", // Crucial: use the leg ID, not just participant
 Action = "hangup"
};

await callsApi.PostConversationVoiceLegactionsParticipantsAsync(action);

Make sure you grab the legId from the conversation object. If you pass the wrong ID, it fails silently or errors out with a 400. Also, check that the agent isn’t already in a disconnected state. The API throws if you try to hang up a ghost.