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

StarAdmin · May 15, 2026, 9:00am

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

What You Will Build

You will build a JavaScript module that programmatically mutes and unmutes the local audio stream of a Genesys Cloud agent during an active WebRTC conversation.
This implementation uses the @genesyscloud/purecloud-platform-client-genesyscloud-web SDK to manipulate the underlying MediaStreamTrack.
The tutorial covers Node.js and browser environments using modern JavaScript (ES6+) and async/await patterns.

Prerequisites

OAuth Client: A Genesys Cloud OAuth client with the webchat:read and conversation:read scopes is required to initialize the client, though the actual mute action is client-side state management.
SDK Version: @genesyscloud/purecloud-platform-client-genesyscloud-web v3.0.0 or higher.
Runtime: Node.js 18+ or a modern browser environment.
Dependencies:
- @genesyscloud/purecloud-platform-client-genesyscloud-web
- @genesyscloud/purecloud-platform-client-logging (for debugging)

Authentication Setup

The Genesys Cloud WebRTC client handles authentication via the PureCloudPlatformClientV2 wrapper. You must initialize the platform client with your region and OAuth credentials before initializing the WebRTC client.

// auth.js
import { PureCloudPlatformClientV2 } from '@genesyscloud/purecloud-platform-client-genesyscloud-web';

const REGION = 'mypurecloud.com'; // Use 'mypurecloud.ie', 'mypurecloud.com.au', etc. as needed
const CLIENT_ID = process.env.GENESYS_CLIENT_ID;
const CLIENT_SECRET = process.env.GENESYS_CLIENT_SECRET;

const platformClient = new PureCloudPlatformClientV2();

/**
 * Initializes the platform client and retrieves an access token.
 * @returns {Promise<void>}
 */
export async function initializePlatform() {
  platformClient.setEnvironment(REGION);
  platformClient.authApi.loginClientCredentials(CLIENT_ID, CLIENT_SECRET);

  // Wait for the token to be ready
  const token = await platformClient.authApi.getAccessToken();
  if (!token) {
    throw new Error('Failed to retrieve access token');
  }
  console.log('Platform initialized. Token expires:', token.expiresAt);
}

Implementation

Step 1: Initialize the WebRTC Client and Join a Conversation

To mute the microphone, you must first have an active Conversation object. The WebRTC client manages the audio tracks. We will create a helper to initialize the client and join a specific conversation (e.g., a test chat or voice call).

// webrtc-init.js
import { WebRTCClient } from '@genesyscloud/purecloud-platform-client-genesyscloud-web';
import { initializePlatform } from './auth.js';

let webrtcClient;
let activeConversation;

/**
 * Initializes the WebRTC client and joins a conversation.
 * @param {string} conversationId - The ID of the conversation to join.
 * @param {string} userId - The ID of the user joining.
 */
export async function joinConversation(conversationId, userId) {
  await initializePlatform();

  // Initialize the WebRTC client
  webrtcClient = new WebRTCClient();
  
  // Configure the client with the platform client for auth
  webrtcClient.setPlatformClient(platformClient);

  // Start the client
  await webrtcClient.start();

  // Join the conversation
  // Note: In a real scenario, you might use webrtcClient.joinConversation() 
  // or handle the 'conversationJoined' event from a UI component.
  // Here we simulate accessing an existing conversation object once joined.
  
  // For demonstration, we assume the conversation is already joined and available
  // via the client's internal state or a UI framework integration.
  // The WebRTCClient exposes a 'conversations' map.
  
  activeConversation = webrtcClient.conversations.get(conversationId);
  
  if (!activeConversation) {
    throw new Error(`Conversation ${conversationId} not found or not joined.`);
  }

  console.log(`Joined conversation: ${conversationId}`);
}

Step 2: Implement the Mute/Unmute Logic

The core functionality resides in manipulating the MediaStreamTrack of the local audio sender. The Genesys Cloud SDK provides access to the underlying WebRTC RTCPeerConnection and senders. However, the SDK also provides a higher-level API on the Conversation object to manage local media settings.

Critical Note: The Conversation object in the WebRTC SDK has a localMedia property. You can toggle the enabled property of the audioTrack.

// mute-control.js
import { joinConversation } from './webrtc-init.js';

/**
 * Mutes the local microphone for the active conversation.
 * @param {string} conversationId - The ID of the conversation.
 */
export async function muteMicrophone(conversationId) {
  if (!webrtcClient) {
    throw new Error('WebRTC Client not initialized.');
  }

  const conversation = webrtcClient.conversations.get(conversationId);
  if (!conversation) {
    throw new Error(`Conversation ${conversationId} not found.`);
  }

  // Access the local media object
  const localMedia = conversation.localMedia;
  
  if (!localMedia) {
    throw new Error('Local media not initialized for this conversation.');
  }

  // Get the audio track
  const audioTrack = localMedia.audioTrack;
  
  if (!audioTrack) {
    throw new Error('No audio track found in local media.');
  }

  // Mute the track
  audioTrack.enabled = false;
  
  console.log('Microphone muted.');
}

/**
 * Unmutes the local microphone for the active conversation.
 * @param {string} conversationId - The ID of the conversation.
 */
export async function unmuteMicrophone(conversationId) {
  if (!webrtcClient) {
    throw new Error('WebRTC Client not initialized.');
  }

  const conversation = webrtcClient.conversations.get(conversationId);
  if (!conversation) {
    throw new Error(`Conversation ${conversationId} not found.`);
  }

  const localMedia = conversation.localMedia;
  
  if (!localMedia) {
    throw new Error('Local media not initialized for this conversation.');
  }

  const audioTrack = localMedia.audioTrack;
  
  if (!audioTrack) {
    throw new Error('No audio track found in local media.');
  }

  // Unmute the track
  audioTrack.enabled = true;
  
  console.log('Microphone unmuted.');
}

Step 3: Handling State and Events

Muting a track does not automatically notify the other party in all contexts unless the WebRTC signaling handles it. The Genesys Cloud platform typically handles the “muted” state signaling internally when using the standard WebRTC client. However, you should listen for the mute and unmute events on the conversation to update your UI.

// event-handlers.js
import { WebRTCClient } from '@genesyscloud/purecloud-platform-client-genesyscloud-web';

let webrtcClient;

/**
 * Sets up event listeners for mute/unmute state changes.
 * @param {WebRTCClient} client - The initialized WebRTC client.
 */
export function setupMuteEvents(client) {
  webrtcClient = client;

  // Listen for conversation join events
  webrtcClient.on('conversationJoined', (event) => {
    const conversation = event.conversation;
    console.log(`Conversation joined: ${conversation.id}`);
    
    // Attach specific listeners to this conversation
    conversation.on('mute', (data) => {
      console.log(`Conversation ${conversation.id} muted by: ${data.userId || 'local'}`);
      // Update UI: Show microphone icon as muted
    });

    conversation.on('unmute', (data) => {
      console.log(`Conversation ${conversation.id} unmuted by: ${data.userId || 'local'}`);
      // Update UI: Show microphone icon as active
    });
    
    // Listen for remote participant mute states
    conversation.on('participantMuted', (data) => {
      console.log(`Remote participant ${data.userId} muted.`);
    });
  });
}

Complete Working Example

This is a complete, runnable Node.js script that demonstrates initializing the client, joining a mock conversation structure (for testing purposes), and toggling the mute state. In a production environment, you would integrate this with a UI framework (React, Angular, Vue) that manages the Conversation lifecycle.

// main.js
import { PureCloudPlatformClientV2, WebRTCClient } from '@genesyscloud/purecloud-platform-client-genesyscloud-web';
import { setupMuteEvents } from './event-handlers.js';

const REGION = 'mypurecloud.com';
const CLIENT_ID = process.env.GENESYS_CLIENT_ID || 'YOUR_CLIENT_ID';
const CLIENT_SECRET = process.env.GENESYS_CLIENT_SECRET || 'YOUR_CLIENT_SECRET';
const CONVERSATION_ID = 'YOUR_CONVERSATION_ID'; // Replace with a real active conversation ID

let platformClient;
let webrtcClient;

async function main() {
  try {
    console.log('1. Initializing Platform Client...');
    platformClient = new PureCloudPlatformClientV2();
    platformClient.setEnvironment(REGION);
    
    // Login using client credentials
    await platformClient.authApi.loginClientCredentials(CLIENT_ID, CLIENT_SECRET);
    const token = await platformClient.authApi.getAccessToken();
    if (!token) {
      throw new Error('Authentication failed');
    }
    console.log('2. Platform Client Initialized.');

    console.log('3. Initializing WebRTC Client...');
    webrtcClient = new WebRTCClient();
    webrtcClient.setPlatformClient(platformClient);
    
    // Setup events
    setupMuteEvents(webrtcClient);

    // Start the WebRTC client
    await webrtcClient.start();
    console.log('4. WebRTC Client Started.');

    // NOTE: In a real application, you would trigger 'joinConversation' from a UI button click
    // after the user has been matched to a conversation. 
    // Here, we simulate the existence of a conversation for the sake of the mute logic demonstration.
    // You cannot programmatically join a random conversation ID without proper context.
    // Instead, we will demonstrate how to toggle mute if you already have a conversation object.
    
    // For this demo, we assume the conversation is joined via the UI and stored in a global scope
    // Let's create a mock scenario where we retrieve an existing conversation
    // In reality, you would do: const conversation = webrtcClient.conversations.get(id);
    
    console.log('5. Waiting for conversation join event from UI...');
    console.log('   (In production, call muteMicrophone() after the user clicks "Join")');

    // Example function to be called by UI
    window.muteMic = async (convId) => {
      const conv = webrtcClient.conversations.get(convId);
      if (!conv) {
        console.error('Conversation not found');
        return;
      }
      const track = conv.localMedia?.audioTrack;
      if (track) {
        track.enabled = false;
        console.log('Microphone Muted');
      }
    };

    window.unmuteMic = async (convId) => {
      const conv = webrtcClient.conversations.get(convId);
      if (!conv) {
        console.error('Conversation not found');
        return;
      }
      const track = conv.localMedia?.audioTrack;
      if (track) {
        track.enabled = true;
        console.log('Microphone Unmuted');
      }
    };

  } catch (error) {
    console.error('Error during initialization:', error);
    process.exit(1);
  }
}

main();

Common Errors & Debugging

Error: `TypeError: Cannot read properties of undefined (reading 'audioTrack')`

Cause: The localMedia object is not yet initialized. This happens if you attempt to mute before the WebRTC peer connection has established the local tracks.
Fix: Ensure the conversationJoined event has fired and that conversation.localMedia exists. Add a null check.

Code Fix:

if (!conversation.localMedia || !conversation.localMedia.audioTrack) {
  console.warn('Audio track not ready yet. Wait for localMediaInitialized event.');
  return;
}

Error: `SecurityError: The MediaStreamTrack has been ended`

Cause: The conversation has ended, or the track was explicitly stopped by the SDK during cleanup.
Fix: Verify the conversation state. Do not attempt to mute an ended conversation.

Code Fix:

if (conversation.state === 'ended') {
  throw new Error('Cannot mute an ended conversation.');
}

Error: `401 Unauthorized` during Platform Initialization

Cause: Invalid Client ID, Client Secret, or the token has expired.
Fix: Verify your OAuth credentials in the Genesys Cloud Admin portal. Ensure the client has the correct scopes. Implement token refresh logic if using a long-running process.

Error: `ReferenceError: webrtcClient is not defined`

Cause: The WebRTC client was not instantiated or the scope is incorrect.
Fix: Ensure WebRTCClient is imported and instantiated before calling mute/unmute functions.

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

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

What You Will Build

Prerequisites

Authentication Setup

Implementation

Step 1: Initialize the WebRTC Client and Join a Conversation

Step 2: Implement the Mute/Unmute Logic

Step 3: Handling State and Events

Complete Working Example

Common Errors & Debugging

Error: TypeError: Cannot read properties of undefined (reading 'audioTrack')

Error: SecurityError: The MediaStreamTrack has been ended

Error: 401 Unauthorized during Platform Initialization

Error: ReferenceError: webrtcClient is not defined

Official References

Error: `TypeError: Cannot read properties of undefined (reading 'audioTrack')`

Error: `SecurityError: The MediaStreamTrack has been ended`

Error: `401 Unauthorized` during Platform Initialization

Error: `ReferenceError: webrtcClient is not defined`