How to Mute/Unmute an Agent Microphone via the Genesys Cloud Client API

How-To-Articles
1

How to Mute/Unmute an Agent Microphone via the Genesys Cloud Client API

What You Will Build

  • This tutorial demonstrates how to programmatically mute and unmute an agent’s microphone during an active conversation using the Genesys Cloud CX Interaction API.
  • This implementation uses the Genesys Cloud CX REST API and the official Python SDK (genesyscloud).
  • The programming language covered is Python 3.8+.

Prerequisites

  • OAuth Client: You must have a Genesys Cloud CX OAuth client with the following scopes:
    • interaction:conversation:write (Required for sending mute/unmute actions)
    • interaction:conversation:read (Required for retrieving conversation details and participant IDs)
  • SDK Version: genesyscloud Python SDK version 2.0.0 or higher.
  • Language/Runtime: Python 3.8 or higher.
  • External Dependencies:
    • genesyscloud
    • requests (for underlying HTTP calls if not using SDK directly)
    • os (for environment variable handling)

Authentication Setup

Genesys Cloud CX uses OAuth 2.0 for authentication. For server-to-server integrations (like this script), you will use the Client Credentials Grant flow.

First, install the SDK:

pip install genesyscloud

Next, configure your environment variables. Do not hardcode credentials in your source code.

export GENESYS_REGION="mypurecloud.com" # Or your specific region, e.g., "au.mygenesys.com"
export GENESYS_CLIENT_ID="your_client_id"
export GENESYS_CLIENT_SECRET="your_client_secret"

The following Python code initializes the PureCloud Platform Client with proper error handling for authentication failures:

import os
import sys
from purecloudplatformclientv2 import ApiClient, Configuration, PureCloudAuthException

def get_api_client() -> ApiClient:
    """
    Initializes and returns an authenticated Genesys Cloud API client.
    
    Returns:
        ApiClient: An authenticated API client instance.
        
    Raises:
        SystemExit: If authentication fails or environment variables are missing.
    """
    # Retrieve credentials from environment
    region = os.getenv("GENESYS_REGION")
    client_id = os.getenv("GENESYS_CLIENT_ID")
    client_secret = os.getenv("GENESYS_CLIENT_SECRET")

    if not all([region, client_id, client_secret]):
        print("Error: Missing required environment variables: GENESYS_REGION, GENESYS_CLIENT_ID, GENESYS_CLIENT_SECRET")
        sys.exit(1)

    try:
        # Create configuration with region
        configuration = Configuration()
        configuration.host = f"https://{region}"
        
        # Initialize API client with OAuth client credentials
        api_client = ApiClient(configuration=configuration)
        
        # Authenticate using client credentials
        api_client.client_credentials_login(client_id=client_id, client_secret=client_secret)
        
        return api_client

    except PureCloudAuthException as e:
        print(f"Authentication failed: {e}")
        sys.exit(1)
    except Exception as e:
        print(f"Unexpected error during client initialization: {e}")
        sys.exit(1)

Implementation

Step 1: Retrieve the Active Conversation

To mute a participant, you need two specific identifiers:

  1. The Conversation ID (conversationId).
  2. The Participant ID (participantId) of the agent you wish to mute.

You cannot mute a participant by their user ID directly; you must target the participant instance within the conversation.

First, we will fetch the list of active conversations for a specific user (the agent). This requires the Interaction API.

from purecloudplatformclientv2 import InteractionApi
from purecloudplatformclientv2.rest import ApiException

def get_active_conversations(api_client: ApiClient, user_id: str) -> list:
    """
    Retrieves all active conversations for a specific user.
    
    Args:
        api_client: Authenticated Genesys API client.
        user_id: The UUID of the agent user.
        
    Returns:
        list: A list of Conversation objects.
    """
    interaction_api = InteractionApi(api_client)
    
    # Filter for active conversations where the user is a participant
    # The 'state' filter ensures we only get live calls/chats
    query_params = {
        'userId': user_id,
        'state': 'active',
        'pageSize': 10,
        'pageNumber': 1
    }
    
    try:
        response = interaction_api.post_interactions_conversations_details_query(body={
            "query": {
                "filters": [
                    {
                        "field": "userId",
                        "op": "in",
                        "values": [user_id]
                    },
                    {
                        "field": "state",
                        "op": "eq",
                        "values": ["ACTIVE"]
                    }
                ]
            }
        })
        
        if response.entities and len(response.entities) > 0:
            return response.entities
        else:
            print(f"No active conversations found for user {user_id}.")
            return []
            
    except ApiException as e:
        if e.status == 401:
            print("Authentication error. Token may have expired.")
        elif e.status == 403:
            print("Forbidden. Check if the OAuth client has 'interaction:conversation:read' scope.")
        else:
            print(f"API Error {e.status}: {e.reason}")
        return []

Step 2: Identify the Correct Participant

A conversation contains multiple participants (agents, customers, bots). You must identify the participant object associated with the agent you intend to mute.

The Conversation object returned in Step 1 contains a participants array. Each participant has a userId field. We must match this userId to the agent’s ID to get the participantId.

def find_agent_participant(conversations: list, user_id: str) -> tuple:
    """
    Iterates through active conversations to find the participant ID for the specific user.
    
    Args:
        conversations: List of Conversation objects from Step 1.
        user_id: The UUID of the agent user.
        
    Returns:
        tuple: (conversation_id, participant_id) or (None, None) if not found.
    """
    for conversation in conversations:
        if not conversation.participants:
            continue
            
        for participant in conversation.participants:
            # Check if this participant belongs to the target user
            if participant.userId == user_id:
                return (conversation.conversationId, participant.participantId)
                
    return (None, None)

Step 3: Execute the Mute/Unmute Action

Genesys Cloud uses a “Participant Action” model. You send a POST request to update the participant’s state. To mute, you set the muted property to true. To unmute, you set it to false.

The API endpoint is:
POST /api/v2/interactions/conversations/{conversationId}/participants/{participantId}

The request body must include the muted field. Note that you must also include the participantId in the body, as some SDK versions require explicit identification even when it is in the path.

from purecloudplatformclientv2 import InteractionApi
from purecloudplatformclientv2.rest import ApiException

def toggle_mute(api_client: ApiClient, conversation_id: str, participant_id: str, mute: bool) -> bool:
    """
    Mutes or unmutes a participant in an active conversation.
    
    Args:
        api_client: Authenticated Genesys API client.
        conversation_id: The UUID of the conversation.
        participant_id: The UUID of the participant to mute/unmute.
        mute: True to mute, False to unmute.
        
    Returns:
        bool: True if successful, False otherwise.
    """
    interaction_api = InteractionApi(api_client)
    
    # Construct the participant update body
    # We only need to send the fields we are changing
    body = {
        "muted": mute
    }
    
    try:
        # The SDK method is post_interactions_conversations_participants
        # Note: In some SDK versions, the path parameters are passed as separate arguments
        response = interaction_api.post_interactions_conversations_participants(
            conversation_id=conversation_id,
            participant_id=participant_id,
            body=body
        )
        
        # The API returns the updated participant object
        if response.muted == mute:
            print(f"Successfully {'muted' if mute else 'unmuted'} participant {participant_id}.")
            return True
        else:
            print(f"Request sent, but current mute state is {response.muted}.")
            return True # The request was accepted, state might be handled asynchronously in some edge cases
            
    except ApiException as e:
        if e.status == 404:
            print(f"Conversation {conversation_id} or Participant {participant_id} not found.")
        elif e.status == 409:
            print("Conflict: The conversation may be in a state that does not allow this action (e.g., ended).")
        elif e.status == 429:
            print("Rate limited. Please wait before retrying.")
        else:
            print(f"API Error {e.status}: {e.reason}")
        return False

Complete Working Example

The following script combines all steps into a single executable module. It assumes you have set the environment variables mentioned in the Prerequisites section.

import os
import sys
import time
from purecloudplatformclientv2 import ApiClient, Configuration, PureCloudAuthException
from purecloudplatformclientv2 import InteractionApi
from purecloudplatformclientv2.rest import ApiException

def get_api_client() -> ApiClient:
    """Initializes and returns an authenticated Genesys Cloud API client."""
    region = os.getenv("GENESYS_REGION")
    client_id = os.getenv("GENESYS_CLIENT_ID")
    client_secret = os.getenv("GENESYS_CLIENT_SECRET")

    if not all([region, client_id, client_secret]):
        print("Error: Missing required environment variables: GENESYS_REGION, GENESYS_CLIENT_ID, GENESYS_CLIENT_SECRET")
        sys.exit(1)

    try:
        configuration = Configuration()
        configuration.host = f"https://{region}"
        api_client = ApiClient(configuration=configuration)
        api_client.client_credentials_login(client_id=client_id, client_secret=client_secret)
        return api_client
    except PureCloudAuthException as e:
        print(f"Authentication failed: {e}")
        sys.exit(1)

def find_agent_participant_in_active_conversation(api_client: ApiClient, user_id: str) -> tuple:
    """
    Finds the conversation ID and participant ID for an active call involving the user.
    """
    interaction_api = InteractionApi(api_client)
    
    try:
        # Query for active conversations for this user
        response = interaction_api.post_interactions_conversations_details_query(body={
            "query": {
                "filters": [
                    {"field": "userId", "op": "in", "values": [user_id]},
                    {"field": "state", "op": "eq", "values": ["ACTIVE"]}
                ]
            }
        })
        
        if not response.entities:
            print(f"No active conversations found for user {user_id}.")
            return None, None
            
        # Assume the first active conversation is the one we want to control
        conversation = response.entities[0]
        
        # Find the participant object for this user within the conversation
        target_participant_id = None
        if conversation.participants:
            for participant in conversation.participants:
                if participant.userId == user_id:
                    target_participant_id = participant.participantId
                    break
        
        if not target_participant_id:
            print(f"User {user_id} is not a participant in conversation {conversation.conversationId}.")
            return None, None
            
        return conversation.conversationId, target_participant_id
        
    except ApiException as e:
        print(f"Error querying conversations: {e.status} - {e.reason}")
        return None, None

def toggle_mute(api_client: ApiClient, conversation_id: str, participant_id: str, mute: bool) -> bool:
    """
    Mutes or unmutes a participant.
    """
    interaction_api = InteractionApi(api_client)
    
    body = {
        "muted": mute
    }
    
    try:
        response = interaction_api.post_interactions_conversations_participants(
            conversation_id=conversation_id,
            participant_id=participant_id,
            body=body
        )
        
        print(f"Action completed. Current muted state: {response.muted}")
        return True
        
    except ApiException as e:
        print(f"Failed to toggle mute. Status: {e.status}, Reason: {e.reason}")
        return False

def main():
    # 1. Initialize Client
    api_client = get_api_client()
    
    # 2. Define Target Agent
    # Replace this with the actual User ID of the agent you want to mute
    TARGET_USER_ID = os.getenv("TARGET_USER_ID")
    
    if not TARGET_USER_ID:
        print("Error: Missing TARGET_USER_ID environment variable.")
        print("Please set TARGET_USER_ID to the UUID of the agent you wish to control.")
        sys.exit(1)
        
    print(f"Finding active conversation for user: {TARGET_USER_ID}...")
    
    # 3. Find Conversation and Participant
    conversation_id, participant_id = find_agent_participant_in_active_conversation(api_client, TARGET_USER_ID)
    
    if not conversation_id or not participant_id:
        print("Could not locate an active participant for the specified user.")
        sys.exit(1)
        
    print(f"Found active conversation: {conversation_id}")
    print(f"Participant ID: {participant_id}")
    
    # 4. Perform Mute
    print("Muting agent microphone...")
    success = toggle_mute(api_client, conversation_id, participant_id, mute=True)
    
    if success:
        # Optional: Wait and then unmute for demonstration purposes
        print("Waiting 5 seconds before unmute...")
        time.sleep(5)
        print("Unmuting agent microphone...")
        toggle_mute(api_client, conversation_id, participant_id, mute=False)

if __name__ == "__main__":
    main()

Common Errors & Debugging

Error: 403 Forbidden

  • Cause: The OAuth client used to generate the token lacks the interaction:conversation:write scope.
  • Fix: Go to the Genesys Cloud Admin Console, navigate to Apps and Integrations > OAuth Clients, edit your client, and add interaction:conversation:write to the scopes. Regenerate the token.

Error: 404 Not Found

  • Cause: The conversationId or participantId is invalid or the conversation has ended.
  • Fix: Ensure you are querying for state: ACTIVE conversations. If the call dropped between the query and the mute action, the participant ID will be stale. Implement a retry logic that re-fetches the participant ID if a 404 occurs.

Error: 409 Conflict

  • Cause: The conversation is in a terminal state (e.g., ENDED, WRAPPED) or the participant has already left.
  • Fix: Check the state of the conversation in the query response. Do not attempt to modify participants in non-active conversations.

Error: Mute State Not Changing in UI

  • Cause: The API call succeeded (200 OK), but the client SDK (e.g., Genesys Cloud Agent Desktop) has not yet received the WebSocket event.
  • Fix: The Genesys Cloud platform pushes state changes via WebSockets. There is a slight latency (typically < 1 second). If your application relies on the mute state being consistent immediately after the API call, implement a short polling loop or wait for the WebSocket event confirmation if you are building a custom client. For server-side automation, the 200 response is sufficient confirmation.

Official References