# Amazon Connect Agent Workspace Voice API
<a name="api-reference-3P-apps-voice-client"></a>

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
<a name="3P-apps-voice-requests-canresumeparticipant"></a>

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
<a name="3P-apps-voice-requests-canresumeself"></a>

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
<a name="3P-apps-voice-requests-conferenceparticipants"></a>

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
<a name="3P-apps-voice-requests-createoutboundcall"></a>

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
<a name="3P-apps-voice-requests-getinitialcustomerphonenumber"></a>

 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
<a name="3P-apps-voice-requests-getoutboundcallpermission"></a>

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
<a name="3P-apps-voice-requests-holdparticipant"></a>

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
<a name="3P-apps-voice-requests-getvoiceenhancementmode"></a>

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
<a name="3P-apps-voice-requests-getvoiceenhancementpaths"></a>

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
<a name="3P-apps-voice-requests-isparticipantonhold"></a>

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
<a name="3P-apps-voice-requests-listdialablecountries"></a>

 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
<a name="3P-apps-voice-requests-offcanresumeparticipantchanged"></a>

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
<a name="3P-apps-voice-requests-offcanresumeselfchanged"></a>

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
<a name="3P-apps-voice-requests-offparticipanthold"></a>

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
<a name="3P-apps-voice-requests-offparticipantresume"></a>

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
<a name="3P-apps-voice-requests-offselfhold"></a>

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
<a name="3P-apps-voice-requests-offselfresume"></a>

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
<a name="3P-apps-voice-requests-offvoiceenhancementmodechanged"></a>

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
<a name="3P-apps-voice-requests-oncanresumeparticipantchanged"></a>

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
<a name="3P-apps-voice-requests-oncanresumeselfchanged"></a>

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
<a name="3P-apps-voice-requests-onparticipanthold"></a>

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
<a name="3P-apps-voice-requests-onparticipantresume"></a>

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
<a name="3P-apps-voice-requests-onselfhold"></a>

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
<a name="3P-apps-voice-requests-onselfresume"></a>

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
<a name="3P-apps-voice-requests-onvoiceenhancementmodechanged"></a>

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
<a name="3P-apps-voice-requests-resumeparticipant"></a>

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
<a name="3P-apps-voice-requests-setvoiceenhancementmode"></a>

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:** 

```
*
```