# Amazon Connect Agent Workspace Voice API
Voice

The Amazon Connect SDK provides an `VoiceClient` which serves as an interface that your app in the Amazon Connect agent workspace can use to make data requests on voice contact.

The `VoiceClient` accepts an optional constructor argument, ` ConnectClientConfig` which itself is defined as:

```
export type ConnectClientConfig = {  
    context?: ModuleContext;  
    provider?: AmazonConnectProvider;
};
```

If you do not provide a value for this config, then the client will default to using the ** AmazonConnectProvider** set in the global provider scope. You can also manually configure this using **setGlobalProvider**.

You can instantiate the agent client as follows:

```
import { VoiceClient } from "@amazon-connect/voice";

const voiceClient = new VoiceClient({ provider });
```

**Note**  
You must first instantiate the [ AmazonConnectApp](getting-started-initialize-sdk.md) which initializes the default AmazonConnectProvider and returns ` { provider } `. This is the recommended option.

Alternatively, providing a constructor argument:

```
import { VoiceClient } from "@amazon-connect/voice";
            
const voiceClient = new VoiceClient({
    context: sampleContext,  
    provider: sampleProvider
});
```

**Note**  
Third-party applications must be configured with \$1 permission in order to utilize the VoiceClient APIs.

The following sections describe API calls for working with the Voice API.

**Topics**
+ [canResumeParticipant()](3P-apps-voice-requests-canresumeparticipant.md)
+ [canResumeSelf()](3P-apps-voice-requests-canresumeself.md)
+ [conferenceParticipants()](3P-apps-voice-requests-conferenceparticipants.md)
+ [createOutboundCall()](3P-apps-voice-requests-createoutboundcall.md)
+ [getInitialCustomerPhoneNumber()](3P-apps-voice-requests-getinitialcustomerphonenumber.md)
+ [getOutboundCallPermission()](3P-apps-voice-requests-getoutboundcallpermission.md)
+ [holdParticipant()](3P-apps-voice-requests-holdparticipant.md)
+ [getVoiceEnhancementMode()](3P-apps-voice-requests-getvoiceenhancementmode.md)
+ [getVoiceEnhancementPaths()](3P-apps-voice-requests-getvoiceenhancementpaths.md)
+ [isParticipantOnHold()](3P-apps-voice-requests-isparticipantonhold.md)
+ [listDialableCountries()](3P-apps-voice-requests-listdialablecountries.md)
+ [offCanResumeParticipantChanged()](3P-apps-voice-requests-offcanresumeparticipantchanged.md)
+ [offCanResumeSelfChanged()](3P-apps-voice-requests-offcanresumeselfchanged.md)
+ [offParticipantHold()](3P-apps-voice-requests-offparticipanthold.md)
+ [offParticipantResume()](3P-apps-voice-requests-offparticipantresume.md)
+ [offSelfHold()](3P-apps-voice-requests-offselfhold.md)
+ [offSelfResume()](3P-apps-voice-requests-offselfresume.md)
+ [offVoiceEnhancementModeChanged()](3P-apps-voice-requests-offvoiceenhancementmodechanged.md)
+ [onCanResumeParticipantChanged()](3P-apps-voice-requests-oncanresumeparticipantchanged.md)
+ [onCanResumeSelfChanged()](3P-apps-voice-requests-oncanresumeselfchanged.md)
+ [onParticipantHold()](3P-apps-voice-requests-onparticipanthold.md)
+ [onParticipantResume()](3P-apps-voice-requests-onparticipantresume.md)
+ [onSelfHold()](3P-apps-voice-requests-onselfhold.md)
+ [onSelfResume()](3P-apps-voice-requests-onselfresume.md)
+ [onVoiceEnhancementModeChanged()](3P-apps-voice-requests-onvoiceenhancementmodechanged.md)
+ [resumeParticipant()](3P-apps-voice-requests-resumeparticipant.md)
+ [setVoiceEnhancementMode()](3P-apps-voice-requests-setvoiceenhancementmode.md)

# Check if a participant can be resumed from hold in Amazon Connect Agent Workspace
canResumeParticipant()

Checks whether a specific participant can be resumed from hold.

 **Signature** 

```
canResumeParticipant(participantId: string): Promise<boolean>
```

 **Usage** 

```
const canResume = await voiceClient.canResumeParticipant("participant-456");
if (canResume) {
  await voiceClient.resumeParticipant("participant-456");
}
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| participantId Required | string | The unique identifier for the participant | 

 **Output** 

Returns a Promise that resolves to a boolean: true if the participant can be resumed, false otherwise

# Check if the current user can be resumed from hold in Amazon Connect Agent Workspace
canResumeSelf()

Checks whether the current user's participant can be resumed from hold for a specific contact.

 **Signature** 

```
canResumeSelf(contactId: string): Promise<boolean>
```

 **Usage** 

```
const canResume = await voiceClient.canResumeSelf("contact-123");
if (canResume) {
  // Resume logic here
}
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| contactId Required | string | The unique identifier for the contact | 

 **Output** 

Returns a Promise that resolves to a boolean: true if the current user can be resumed, false otherwise

# Conference all participants on a contact in Amazon Connect Agent Workspace
conferenceParticipants()

Conferences all participants on a contact together, removing any hold states and enabling all participants to communicate with each other.

 **Signature** 

```
conferenceParticipants(contactId: string): Promise<void>
```

 **Usage** 

```
await voiceClient.conferenceParticipants("contact-123");
console.log("All participants are now conferenced");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| contactId Required | string | The unique identifier for the contact | 

# Create an outbound call to phone number in Amazon Connect Agent Workspace
createOutboundCall()

Creates an outbound call to the given phone number and returns the contactId. It takes an optional parameter `queueARN` which specifies the outbound queue associated with the call, if omitted the default outbound queue defined in the agent's routing profile will be used.

 **Signature** 

```
  createOutboundCall(
    phoneNumber: string,
    options?: CreateOutboundCallOptions,
  ): Promise<CreateOutboundCallResult>
```

 **Usage** 

```
const outboundCallResult:CreateOutboundCallResult = await voiceClient.createOutboundCall("+18005550100");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
|  phoneNumber Required  |  string  |  The phone number specified in E.164 format  | 
|  options.queueARN  |  string  |  It specifies the outbound queue associated with the call, if omitted the default outbound queue defined in the agent's routing profile will be used.  | 
|  options.relatedContactId  |  string  |  Optional parameter to supply related contactId  | 

 **Output - *CreateOutboundCallResult*** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
|  contactId  |  string  |  The contactId of the created outbound call.  | 

 **Permissions required:** 

```
Contact.Details.Edit      
```

# Gets the phone number of the initial customer connection in Amazon Connect Agent Workspace
getInitialCustomerPhoneNumber()

 Gets the phone number of the initial customer connection. Applicable only for voice contacts. 

 **Signature** 

```
getInitialCustomerPhoneNumber(contactId: string): Promise<string>
```

 **Usage** 

```
const initialCustomerPhoneNumber: string = await voiceClient.getInitialCustomerPhoneNumber(contactId);        
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
|  contactId Required  |  string  |  The id of the contact for which the data is requested.  | 

 **Permissions required:** 

```
Contact.CustomerDetails.View      
```

# Gets the outbound call permission configured for the agent in Amazon Connect Agent Workspace
getOutboundCallPermission()

Gets true if the agent has the security profile permission for making outbound calls, false otherwise.

 **Signature** 

```
getOutboundCallPermission(): Promise<boolean>
```

 **Usage** 

```
const outboundCallPermission: boolean = await voiceClient.getOutboundCallPermission();
```

 **Permissions required:** 

```
User.Configuration.View      
```

# Place a participant on hold in Amazon Connect Agent Workspace
holdParticipant()

Places a specific participant on hold.

 **Signature** 

```
holdParticipant(participantId: string): Promise<void>
```

 **Usage** 

```
await voiceClient.holdParticipant("participant-456");
console.log("Participant is now on hold");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| participantId Required | string | The unique identifier for the participant to place on hold | 

# Get the voice enhancement mode in Amazon Connect Agent Workspace
getVoiceEnhancementMode()

Gets the voice enhancement mode of the user that's currently logged in to Amazon Connect agent workspace. The voice enhancement mode can have the following values:
+ `VOICE_ISOLATION`: it suppresses background noise and isolates the agent's voice. This mode should only be enabled if the agent uses a wired headsets.
+ `NOISE_SUPPRESSION`: it suppresses the background noise. We recommend using this mode with any type of headset.
+ `NONE`: no voice enhancement applies.

 **Signature** 

```
async getVoiceEnhancementMode(): Promise<VoiceEnhancementMode>
```

 **Usage** 

```
const voiceEnhancementMode: VoiceEnhancementMode = await voiceClient.getVoiceEnhancementMode();
```

 **Permissions required:** 

```
*
```

# Get voice enhancement model paths in Amazon Connect Agent Workspace
getVoiceEnhancementPaths()

Returns the voice enhancements models static assets URL paths.

 **Signature** 

```
async getVoiceEnhancementPaths(): Promise<VoiceEnhancementPaths>
```

 **Usage** 

```
voiceClient.getVoiceEnhancementPaths();

// VoiceEnhancementPaths structure
interface VoiceEnhancementPaths {
  processors: string;
  workers: string;
  wasm: string;
  models: string;
}
```

 **Permissions required:** 

```
*
```

# Check if a participant is on hold in Amazon Connect Agent Workspace
isParticipantOnHold()

Checks whether a specific participant is currently on hold.

 **Signature** 

```
isParticipantOnHold(participantId: string): Promise<boolean>
```

 **Usage** 

```
const isOnHold = await voiceClient.isParticipantOnHold("participant-456");
if (isOnHold) {
  console.log("Participant is on hold");
} else {
  console.log("Participant is active");
}
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| participantId Required | string | The unique identifier for the participant | 

 **Output** 

Returns a Promise that resolves to a boolean: true if the participant is on hold, false otherwise

# Get a list of dialable countries in Amazon Connect Agent Workspace
listDialableCountries()

 Get a list of `DialableCountry` that contains the country code and calling code that the Amazon Connect instance is allowed to make calls to. 

 **Signature** 

```
listDialableCountries(): Promise<DialableCountry[]>
```

 **Usage** 

```
const dialableCountries:DialableCountry[] = await voiceClient.listDialableCountries();
```

 **Output - *DialableCountry*** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
|  countryCode  |  string  |  The ISO country code  | 
|  callingCode  |  string  |  The calling code for the country  | 
|  label  |  string  |  The name of the country  | 

 **Permissions required:** 

```
User.Configuration.View      
```

# Unsubscribe from participant resume capability change events in Amazon Connect Agent Workspace
offCanResumeParticipantChanged()

Unsubscribes from participant capability change events.

 **Signature** 

```
offCanResumeParticipantChanged(
  handler: CanResumeParticipantChangedHandler,
  participantId?: string
): void
```

 **Usage** 

```
voiceClient.offCanResumeParticipantChanged(handleCanResumeChanged);
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | CanResumeParticipantChangedHandler | Event handler function to remove | 
| participantId | string | Optional participant ID to unsubscribe from specific participant events | 

# Unsubscribe from self resume capability change events in Amazon Connect Agent Workspace
offCanResumeSelfChanged()

Unsubscribes from capability change events for the current user.

 **Signature** 

```
offCanResumeSelfChanged(
  handler: CanResumeParticipantChangedHandler,
  contactId?: string
): void
```

 **Usage** 

```
voiceClient.offCanResumeSelfChanged(handleCanResumeSelfChanged);
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | CanResumeParticipantChangedHandler | Event handler function to remove | 
| contactId | string | Optional contact ID to unsubscribe from specific contact events | 

# Unsubscribe from participant hold events in Amazon Connect Agent Workspace
offParticipantHold()

Unsubscribes from participant hold events.

 **Signature** 

```
offParticipantHold(
  handler: ParticipantHoldHandler,
  participantId?: string
): void
```

 **Usage** 

```
voiceClient.offParticipantHold(handleParticipantHold);
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | ParticipantHoldHandler | Event handler function to remove | 
| participantId | string | Optional participant ID to unsubscribe from specific participant events | 

# Unsubscribe from participant resume events in Amazon Connect Agent Workspace
offParticipantResume()

Unsubscribes from participant resume events.

 **Signature** 

```
offParticipantResume(
  handler: ParticipantResumeHandler,
  participantId?: string
): void
```

 **Usage** 

```
voiceClient.offParticipantResume(handleParticipantResume);
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | ParticipantResumeHandler | Event handler function to remove | 
| participantId | string | Optional participant ID to unsubscribe from specific participant events | 

# Unsubscribe from self hold events in Amazon Connect Agent Workspace
offSelfHold()

Unsubscribes from self hold events.

 **Signature** 

```
offSelfHold(
  handler: ParticipantHoldHandler,
  contactId?: string
): void
```

 **Usage** 

```
voiceClient.offSelfHold(handleSelfHold);
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | ParticipantHoldHandler | Event handler function to remove | 
| contactId | string | Optional contact ID to unsubscribe from specific contact events | 

# Unsubscribe from self resume events in Amazon Connect Agent Workspace
offSelfResume()

Unsubscribes from self resume events.

 **Signature** 

```
offSelfResume(
  handler: ParticipantResumeHandler,
  contactId?: string
): void
```

 **Usage** 

```
voiceClient.offSelfResume(handleSelfResume);
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | ParticipantResumeHandler | Event handler function to remove | 
| contactId | string | Optional contact ID to unsubscribe from specific contact events | 

# Unsubscribe from voice enhancement mode change events in Amazon Connect Agent Workspace
offVoiceEnhancementModeChanged()

Unsubscribes a callback function registered for voice enhancements mode changed event.

 **Signature** 

```
offVoiceEnhancementModeChanged(handler: VoiceEnhancementModeChangedHandler)
```

 **Usage** 

```
const handler: VoiceEnhancementModeChangedHandler = async (data: VoiceEnhancementModeChanged) => {
  console.log("User VoiceEnhancementMode changed! " + data);
}

// subscribe a callback for mode change
voiceClient.onVoiceEnhancementModeChanged(handler);

// unsubsribes a callback for mode change
voiceClient.offVoiceEnhancementModeChanged(handler);
```

 **Permissions required:** 

```
*
```

# Subscribe to participant resume capability change events in Amazon Connect Agent Workspace
onCanResumeParticipantChanged()

Subscribes to events when a participant's capability to be resumed from hold changes.

 **Signature** 

```
onCanResumeParticipantChanged(
  handler: CanResumeParticipantChangedHandler,
  participantId?: string
): void
```

 **Usage** 

```
const handleCanResumeChanged = (event) => {
  console.log(`Participant ${event.participantId} resume capability: ${event.canResumeConnection}`);
  if (event.canResumeConnection) {
    // Enable resume button for this participant
  } else {
    // Disable resume button for this participant
  }
};
voiceClient.onCanResumeParticipantChanged(handleCanResumeChanged, "participant-456");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | CanResumeParticipantChangedHandler | Event handler function to call when the capability changes | 
| participantId | string | Optional participant ID to filter events for a specific participant | 

# Subscribe to self resume capability change events in Amazon Connect Agent Workspace
onCanResumeSelfChanged()

Subscribes to events when the current user's capability to be resumed from hold changes.

 **Signature** 

```
onCanResumeSelfChanged(
  handler: CanResumeParticipantChangedHandler,
  contactId?: string
): void
```

 **Usage** 

```
const handleCanResumeSelfChanged = (event) => {
  if (event.canResumeConnection) {
    console.log("You can now be resumed from hold");
    // Enable resume button in UI
  } else {
    console.log("You cannot be resumed at this time");
    // Disable resume button in UI
  }
};
voiceClient.onCanResumeSelfChanged(handleCanResumeSelfChanged, "contact-123");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | CanResumeParticipantChangedHandler | Event handler function to call when the capability changes | 
| contactId | string | Optional contact ID to filter events for a specific contact | 

# Subscribe to participant hold events in Amazon Connect Agent Workspace
onParticipantHold()

Subscribes to events when any participant is put on hold.

 **Signature** 

```
onParticipantHold(
  handler: ParticipantHoldHandler,
  participantId?: string
): void
```

 **Usage** 

```
const handleParticipantHold = (event) => {
  console.log(`Participant ${event.participantId} is now on hold`);
  console.log(`Contact: ${event.contactId}`);
};
// Subscribe to all participants
voiceClient.onParticipantHold(handleParticipantHold);
// Or subscribe to a specific participant
voiceClient.onParticipantHold(handleParticipantHold, "participant-456");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | ParticipantHoldHandler | Event handler function to call when participants are put on hold | 
| participantId | string | Optional participant ID to filter events for a specific participant | 

# Subscribe to participant resume events in Amazon Connect Agent Workspace
onParticipantResume()

Subscribes to events when any participant is taken off hold.

 **Signature** 

```
onParticipantResume(
  handler: ParticipantResumeHandler,
  participantId?: string
): void
```

 **Usage** 

```
const handleParticipantResume = (event) => {
  console.log(`Participant ${event.participantId} has been resumed`);
};
voiceClient.onParticipantResume(handleParticipantResume, "participant-456");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | ParticipantResumeHandler | Event handler function to call when participants are taken off hold | 
| participantId | string | Optional participant ID to filter events for a specific participant | 

# Subscribe to self hold events in Amazon Connect Agent Workspace
onSelfHold()

Subscribes to events when the current user's participant is put on hold.

 **Signature** 

```
onSelfHold(
  handler: ParticipantHoldHandler,
  contactId?: string
): void
```

 **Usage** 

```
const handleSelfHold = (event) => {
  console.log("You have been put on hold");
  console.log(`Contact: ${event.contactId}`);
};
// Subscribe to all contacts
voiceClient.onSelfHold(handleSelfHold);
// Or subscribe to a specific contact
voiceClient.onSelfHold(handleSelfHold, "contact-123");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | ParticipantHoldHandler | Event handler function to call when the current user's participant is put on hold | 
| contactId | string | Optional contact ID to filter events for a specific contact | 

# Subscribe to self resume events in Amazon Connect Agent Workspace
onSelfResume()

Subscribes to events when the current user's participant is taken off hold.

 **Signature** 

```
onSelfResume(
  handler: ParticipantResumeHandler,
  contactId?: string
): void
```

 **Usage** 

```
const handleSelfResume = (event) => {
  console.log("You have been resumed from hold");
};
voiceClient.onSelfResume(handleSelfResume, "contact-123");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| handler Required | ParticipantResumeHandler | Event handler function to call when the current user's participant is taken off hold | 
| contactId | string | Optional contact ID to filter events for a specific contact | 

# Subscribe to voice enhancement mode change events in Amazon Connect Agent Workspace
onVoiceEnhancementModeChanged()

Subscribes a callback function whenever voice enhancements mode is changed in user's profile.

 **Signature** 

```
onVoiceEnhancementModeChanged(handler: VoiceEnhancementModeChangedHandler)
```

 **Usage** 

```
const handler: VoiceEnhancementModeChangedHandler = async (data: VoiceEnhancementModeChanged) => {
  console.log("User VoiceEnhancementMode changed! " + data);
}

voiceClient.onVoiceEnhancementModeChanged(handler);

// VoiceEnhancementModeChanged structure
{
  voiceEnhancementMode: string
  previous: {
     voiceEnhancementMode: string
  } 
}
```

 **Permissions required:** 

```
*
```

# Resume a participant from hold in Amazon Connect Agent Workspace
resumeParticipant()

Resumes a specific participant from hold.

 **Signature** 

```
resumeParticipant(participantId: string): Promise<void>
```

 **Usage** 

```
await voiceClient.resumeParticipant("participant-456");
console.log("Participant has been resumed");
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| participantId Required | string | The unique identifier for the participant to resume | 

# Set the voice enhancement mode in Amazon Connect Agent Workspace
setVoiceEnhancementMode()

Sets the voice enhancement mode of the user that's currently logged in to Amazon Connect agent workspace. The voice enhancement mode can have the following values:
+ `VOICE_ISOLATION`: it suppresses background noise and isolates the agent's voice. This mode should only be enabled if the agent uses a wired headsets.
+ `NOISE_SUPPRESSION`: it suppresses the background noise. We recommend using this mode with any type of headset.
+ `NONE`: no voice enhancement applies.

 **Signature** 

```
async setVoiceEnhancementMode(voiceEnhancementMode: VoiceEnhancementMode): Promise<void>
```

 **Usage** 

```
await voiceClient.setVoiceEnhancementMode(VoiceEnhancementMode.NOISE_SUPPRESSION);
```

 **Input** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| voiceEnhancementMode Required | VoiceEnhancementMode | The mode to set on the user. Values accepted: VOICE\$1ISOLATION, NOISE\$1SUPPRESSION, NONE | 

 **Permissions required:** 

```
*
```