# Amazon Connect Agent Workspace API reference
This Amazon Connect agent workspace API reference enumerates the agent events, agent requests, contact events, and contact requests that are supported by the [Amazon Connect SDK](https://github.com/amazon-connect/AmazonConnectSDK).
**Topics**
+ [Activity](api-reference-3P-apps-activity-client.md)
+ [Agent](api-reference-3P-apps-agent-client.md)
+ [AppController](api-reference-3P-apps-app-controller.md)
+ [Contact](api-reference-3P-apps-contact-client.md)
+ [Email](api-reference-3P-apps-email-client.md)
+ [File](api-reference-3P-apps-file-client.md)
+ [MessageTemplate](api-reference-3P-apps-message-template-client.md)
+ [QuickResponses](api-reference-3P-apps-quick-responses-client.md)
+ [User](api-reference-3P-apps-user.md)
+ [Voice](api-reference-3P-apps-voice-client.md)
# Amazon Connect Agent Workspace Activity API
The Amazon Connect SDK provides a `SessionExpirationWarningClient` which serves as an interface that your app in the Amazon Connect agent workspace can use to subscribe to events related to session expiration due to inactivity and to signal the Amazon Connect that the agent is active.
The `SessionExpirationWarningClient` 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 client as follows:
```
import { SessionExpirationWarningClient } from "@amazon-connect/activity";
const sessionExpirationWarningClient = new SessionExpirationWarningClient();
```
**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, you can provide a constructor argument:
```
import { SessionExpirationWarningClient } from "@amazon-connect/activity";
const sessionExpirationWarningClient = new SessionExpirationWarningClient({
context: sampleContext,
provider: sampleProvider
});
```
The following sections describe the API calls for working with the SessionExpirationWarning API.
**Topics**
+ [onExpirationWarning()](3P-apps-activity-offexpirationwarning.md)
+ [offExpirationWarningCleared()](3P-apps-activity-offexpirationwarningcleared.md)
+ [offSessionExtensionError()](3P-apps-activity-offsessionextensionerror.md)
+ [onExpirationWarning()](3P-apps-activity-onexpirationwarning.md)
+ [onExpirationWarningCleared()](3P-apps-activity-onexpirationwarningcleared.md)
+ [onSessionExtensionError()](3P-apps-activity-onsessionextensionerror.md)
+ [sendActivity()](3P-apps-activity-sendactivity.md)
# Unsubscribe a callback function from the expiration warning event
Unsubscribes a callback function from the expiration warning event that is triggered when the agent is nearing expiration due to inactivity.
**Signature**
```
offExpirationWarning(handler: ExpirationWarningHandler);
```
**Usage**
```
sessionExpirationWarningClient.offExpirationWarning(handler);
```
# Unsubscribe a callback function from the expiration warning cleared event
Unsubscribes a callback function from the expiration warning cleared event that is triggered when the expiration warning is dismissed due to the agent choosing to stay logged in.
**Signature**
```
offExpirationWarningCleared(handler: ExpirationWarningClearedHandler);
```
**Usage**
```
sessionExpirationWarningClient.offExpirationWarningCleared(handler);
```
# Unsubscribe a callback function from the session extension error event
Unsubscribes a callback function from the session extension error event that is triggered when the agent's session fails to update.
**Signature**
```
offSessionExtensionError(handler: SessionExtensionErrorHandler);
```
**Usage**
```
sessionExpirationWarningClient.offSessionExtensionError(handler);
```
# Subscribe to session expiration warning event in Amazon Connect Agent Workspace
Subscribes a callback function to be invoked whenever the agent's session is about to expire due to inactivity.
**Signature**
```
onExpirationWarning(handler: ExpirationWarningHandler);
```
**Usage**
```
const handler: ExpirationWarningHandler = (data: SessionExpirationInformation) => {
console.log("Agent's session expiring at:", data);
}
sessionExpirationWarningClient.onExpirationWarning(handler);
// SessionExpirationInformation Structure
{
expiration: number;
}
```
# Subscribe to expiration warning cleared event in Amazon Connect Agent Workspace
Subscribes a callback function to be invoked when the agent has acknowledged the expiration warning and chooses to update their session.
**Signature**
```
onExpirationWarningCleared(handler: ExpirationWarningClearedHandler);
```
**Usage**
```
const handler: ExpirationWarningClearedHandler = () => {
console.log("My session was extended after I was warned!");
}
sessionExpirationWarningClient.onExpirationWarningCleared(handler);
```
# Subscribe to session extension errors in Amazon Connect Agent Workspace
Subscribes a callback function to be invoked when an attempt to extend the agent's session fails.
**Signature**
```
onSessionExtensionError(handler: SessionExtensionErrorHandler);
```
**Usage**
```
const handler: SessionExtensionErrorHandler = (details: SessionExtensionErrorData) => {
console.log("Failed to extend my session!", details);
}
sessionExpirationWarningClient.onSessionExtensionError(handler);
// SessionExtensionErrorData Structure
{
isWarningActive: boolean;
errorDetails: Record;
}
```
# Inform Amazon Connect that the agent is active
Sends a signal to the Amazon Connect indicating that the agent is active and should not be logged out. It takes a provider as a parameter.
**Signature**
```
sendActivity(provider): void
```
**Usage**
```
import { sendActivity } from '@amazon-connect/activity';
const handleActivity = () => {
sendActivity(sampleProvider);
};
window.addEventListener("click", handleActivity);
```
# Amazon Connect Agent Workspace Agent API
The Amazon Connect SDK provides an `AgentClient` which serves as an interface that your app in the Amazon Connect agent workspace can use to subscribe to agent events and make agent data requests.
The `AgentClient` 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 { AgentClient } from "@amazon-connect/contact";
const agentClient = new AgentClient({ 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 { AgentClient } from "@amazon-connect/contact";
const agentClient = new AgentClient({
context: sampleContext,
provider: sampleProvider
});
```
The following sections describe API calls for working with the Agent API.
**Topics**
+ [getARN()](3P-apps-agent-requests-getarn.md)
+ [getChannelConcurrency()](3P-apps-agent-requests-getchannelconcurrency.md)
+ [getExtension()](3P-apps-agent-requests-getextension.md)
+ [getName()](3P-apps-agent-requests-getname.md)
+ [getRoutingProfile()](3P-apps-agent-requests-getroutingprofile.md)
+ [getState()](3P-apps-agent-requests-getstate.md)
+ [listAvailabilityStates()](3P-apps-agent-requests-listavailabilitystates.md)
+ [listQuickConnects()](3P-apps-agent-requests-listquickconnects.md)
+ [offEnabledChannelListChanged()](3P-apps-agent-requests-off-enabledchannellistchanged.md)
+ [offRoutingProfileChanged()](3P-apps-agent-requests-off-routingprofilechanged.md)
+ [onEnabledChannelListChanged()](3P-apps-agent-requests-on-enabledchannellistchanged.md)
+ [onRoutingProfileChanged()](3P-apps-agent-requests-on-routingprofile-changed.md)
+ [setAvailabilityState()](3P-apps-agent-requests-setavailabilitystate.md)
+ [setAvailabilityStateByName()](3P-apps-agent-requests-setavailabilitystatebyname.md)
+ [setOffline()](3P-apps-agent-requests-setoffline.md)
+ [onStateChanged()](3P-apps-agent-events-statechanged-sub.md)
+ [offStateChanged()](3P-apps-agent-events-statechanged-unsub.md)
# Get the ARN of the agent in Amazon Connect Agent Workspace
Returns the Amazon Resource Name(ARN) of the user that's currently logged in to the Amazon Connect agent workspace.
```
async getARN(): Promise
```
**Permissions required:**
```
User.Details.View
```
# Get the limit of contacts for the agent in Amazon Connect Agent Workspace
Returns a map of `ChannelType`-to-number indicating how many concurrent contacts can an Amazon Connect agent workspace agent have on a given channel. 0 represents a disabled channel.
```
async getChannelConcurrency(): Promise
```
**Permissions required:**
```
User.Configuration.View
```
# Get the extension of the agent in Amazon Connect Agent Workspace
Returns phone number of the agent currently logged in to the Amazon Connect agent workspace. This is the phone number that is dialed by the Amazon Connect to connect calls to the agent for incoming and outgoing calls if soft phone is not enabled.
```
async getExtension(): Promise
```
**Permissions required:**
```
User.Configuration.View
```
# Get the name of the agent in Amazon Connect Agent Workspace
Returns the name of the user that's currently logged in to the Amazon Connect agent workspace.
```
async getName(): Promise
```
**Permissions required:**
```
User.Details.View
```
# Get the routing profile of the agent in Amazon Connect Agent Workspace
Returns the routing profile of the agent currently logged in to the Amazon Connect agent workspace. The routing profile contains the following fields:
+ `channelConcurrencyMap`: See agent.[Get the limit of contacts for the agent in Amazon Connect Agent Workspace](3P-apps-agent-requests-getchannelconcurrency.md) for more info.
+ `defaultOutboundQueue`: The default queue which should be associated with outbound contacts. See queues for details on properties.
+ `name`: The name of the routing profile.
+ `queues`: The queues contained in the routing profile. Each queue object has the following properties:
+ `name`: The name of the queue.
+ `queueARN`: The ARN of the queue.
+ `queueId`: Alias for queueARN.
+ `routingProfileARN`: The routing profile ARN.
+ `routingProfileId`: Alias for `routingProfileARN`.
```
async getRoutingProfile(): Promise
```
**Permissions required:**
```
User.Configuration.View
```
# Get the current state of the agent in Amazon Connect Agent Workspace
Returns the Amazon Connect agent workspace agent's current `AgentState` object indicating their availability state type. This object contains the following fields:
+ `agentStateARN`: The agent's current state ARN.
+ `name`: The name of the agent's current availability state.
+ `startTimestamp`: A `Date` object that indicates when the state was set.
+ `type`: The agent's current availability state type, as per the ` AgentStateType` enumeration. The different values are as follows:
+ `routable`
+ `not_routable`
+ `after_call_work`
+ `system`
+ `error`
+ `offline`
```
async getState(): Promise
```
**Permissions required:**
```
User.Status.View
```
# Get all the availability states configured for the current agent in Amazon Connect Agent Workspace
Get all the availability states configured for the current agent.
**Signature**
```
listAvailabilityStates(): Promise
```
**Usage**
```
const availabilityStates: AgentState[] = await agentClient.listAvailabilityStates();
```
**Output - AgentState**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| agentStateARN | string | Amazon Reference Number of agent state |
| type | string | It could be "routable" \$1 "not\$1routable" \$1 "after\$1call\$1work" \$1 "system" \$1 "error" \$1 "offline" |
| name | string | Name of the agent state like Available or Offline |
| startTimestamp | Date | A Date object that indicates when the state was set. |
**Permissions required:**
```
User.Configuration.View
```
# Get the list of Quick Connect endpoints associated with a given queue in Amazon Connect Agent Workspace
Get the list of Quick Connect endpoints associated with the given queue(s). Optionally you can pass in a parameter to override the default max-results value of 500.
**Signature**
```
listQuickConnects(
queueARNs: QueueARN | QueueARN[],
options?: ListQuickConnectsOptions,
): Promise
```
**Usage**
```
const routingProfile: AgentRoutingProfile = await agentClient.getRoutingProfile();
const quickConnects: ListQuickConnectsResult = await agentClient.listQuickConnects(routingProfile.queues[0].queueARN);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| queueARNs Required | string \$1 string[] | One or more Queue ARNs for which the Queue Connects need to be retrieved |
| options.maxResults | number | The maximum number of results to return per page. The default value is 500 |
| options.nextToken | string | The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results. |
**Output - ListQuickConnectsResult**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| quickConnects | QuickConnect[] | Its either AgentQuickConnect or QueueQuickConnect or PhoneNumberQuickConnect which contains endpointARN and name. Additionally PhoneNumberQuickConnect contains phoneNumber |
| nextToken | string | If there are additional results, this is the token for the next set of results. |
**Permissions required:**
```
User.Configuration.View
```
# Unsubscribe from agent enabled channel list changes in Amazon Connect Agent Workspace
Unsubscribes from EnabledChannelListChanged event.
**Signature**
```
offEnabledChannelListChanged(handler: EnabledChannelListChangedHandler): void
```
# Unsubscribe from agent routing profile changes in Amazon Connect Agent Workspace
Unsubscribes from RoutingProfileChanged event.
**Signature**
```
offRoutingProfileChanged(handler: RoutingProfileChangedHandler): void
```
# Subscribe to agent enabled channel list changes in Amazon Connect Agent Workspace
Creates a subscription for EnabledChannelListChanged event. This gets triggered when an Agent's enabled channels get updated.
**Signature**
```
const handler: EnabledChannelListChangedHandler = async (data: EnabledChannelListChanged) => {
console.log("Agent channel list change occurred! " + data);
};
agentClient.onEnabledChannelListChanged(handler);
// EnabledChannelListChanged Structure
{
enabledChannels: AgentRoutingProfileChannelTypes[];
previous?: {
enabledChannels: AgentRoutingProfileChannelTypes[];
};
}
```
**Permissions required:**
```
*
```
# Subscribe to agent routing profile changes in Amazon Connect Agent Workspace
Creates a subscription for RoutingProfileChanged event. This gets triggered when an Agent's routing profile gets updated.
**Signature**
```
const handler: RoutingProfileChangedHandler = async (data: AgentRoutingProfileChanged) => {
console.log("Agent routing profile change occurred! " + data);
};
agentClient.onRoutingProfileChanged(handler);
// AgentRoutingProfileChanged Structure
{
routingProfile: AgentRoutingProfile;
previous?: {
routingProfile: AgentRoutingProfile;
};
}
```
**Permissions required:**
```
*
```
# Set the agent state with the given agent state ARN in Amazon Connect Agent Workspace
Set the agent state with the given agent state ARN. By default, the promise resolves after the agent state is set in the backend. The response status is either `updated` or `queued` based on the current agent state.
**Signature**
```
setAvailabilityState(
agentStateARN: string,
): Promise
```
**Usage**
```
const availabilityStates: AgentState[] = await agentClient.listAvailabilityStates();
const availabilityStateResult:SetAvailabilityStateResult = await agentClient.setAvailabilityState(availabilityStates[0].agentStateARN);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| agentStateARN Required | string | The ARN of the agent state |
**Output - SetAvailabilityStateResult**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| status | string | The status will be updated or queued depending on if the agent is currently handling an active contact. |
| current | AgentState | Reperesents the current state of the agent. |
| next | AgentState | It'll be the target state if the agent is handling active contact. Applicable when the status is queued. |
**Permissions required:**
```
User.Configuration.Edit
```
# Set the agent state with the given agent state name in Amazon Connect Agent Workspace
Sets the agent state with the given agent state name. The promise resolves after the agent state is set in the backend. The response status is either `updated` or ` queued` based on the current agent state.
**Signature**
```
setAvailabilityStateByName(
agentStateName: string,
): Promise
```
**Usage**
```
const availabilityStateResult: SetAvailabilityStateResult = await agentClient.setAvailabilityStateByName('Available');
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| agentStateName Required | string | The name of the agent state |
**Output - SetAvailabilityStateResult**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| status | string | The status will be "updated" or "queued" depends on if the agent is currently handling an active contact. |
| current | AgentState | Reperesents the current state of the agent. |
| next | AgentState | It'll be the target state if the agent is handling active contact. Applicable when the status is queued |
**Permissions required:**
```
User.Configuration.Edit
```
# Sets the agent state to Offline in Amazon Connect Agent Workspace
Sets the agent state to Offline. The promise resolves after the agent state is set in the backend.
**Signature**
```
setOffline(): Promise
```
**Usage**
```
const availabilityStateResult: SetAvailabilityStateResult = await agentClient.setOffline();
```
**Output - SetAvailabilityStateResult**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| status | string | The status will be updated or queued depending on if the agent is currently handling an active contact. |
| current | AgentState | Represents the current state of the agent. |
| next | AgentState | It'll be the target state if the agent is handling active contact. Applicable when the status is queued. |
**Permissions required:**
```
User.Configuration.Edit
```
# Subscribe a callback function when an Amazon Connect Agent Workspace agent state changes
Subscribes a callback function to-be-invoked whenever an agent state changed event occurs in the Amazon Connect agent workspace.
**Signature**
```
onStateChanged(handler: AgentStateChangedHandler)
```
**Usage**
```
const handler: AgentStateChangedHandler = async (data: AgentStateChangedEventData) => {
console.log("Agent state change occurred! " + data);
};
agentClient.onStateChanged(handler);
// AgentStateChangedEventData Structure
{
state: string;
previous: {
state: string;
};
}
```
**Permissions required:**
```
User.Status.View
```
# Unsubscribe a callback function when an Amazon Connect Agent Workspace agent state changes
Unsubscribes the callback function from the agent stated change event in the Amazon Connect agent workspace.
**Signature**
```
offStateChanged(handler: AgentStateChangedHandler)
```
**Usage**
```
agentClient.offStateChanged(handler);
```
# Amazon Connect Agent Workspace AppController API
The Amazon Connect SDK provides an `AppControllerClient` to control applications in the Amazon Connect agent workspace.
The `AppControllerClient` accepts an optional 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 AppControllerClient as follows:
```
import { AppControllerClient } from "@amazon-connect/app-controller";
const appControllerClient = new AppControllerClient({ provider });
```
The following sections describe API calls for working with the App Controller API.
**Topics**
+ [closeApp()](api-reference-3P-apps-app-controller-closeapp.md)
+ [focusApp()](api-reference-3P-apps-app-controller-focusapp.md)
+ [getApp()](api-reference-3P-apps-app-controller-getapp.md)
+ [getAppCatalog()](api-reference-3P-apps-app-controller-getappcatalog.md)
+ [getAppConfig()](api-reference-3P-apps-app-controller-getappconfig.md)
+ [getApps()](api-reference-3P-apps-app-controller-getapps.md)
+ [launchApp()](api-reference-3P-apps-app-controller-launchapp.md)
# Close an application in Amazon Connect Agent Workspace
Closes the application for the given application instance ID in the Amazon Connect agent workspace.
**Signature**
```
closeApp(instanceId: string): Promise
```
**Usage**
```
await appControllerClient.closeApp(appInstanceId);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| appInstanceId Required | string | The instance ID of the application |
**Permissions required:**
```
*
```
# Focus an application in Amazon Connect Agent Workspace
Brings the application into focus in the Amazon Connect agent workspace for the given application instance ID.
**Signature**
```
focusApp(instanceId: string): Promise
```
**Usage**
```
const applicationFocusResult: AppFocusResult = await appControllerClient.focusApp(appInstanceId);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| appInstanceId Required | string | The instance ID of the application |
**Output - AppFocusResult**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| instanceId | string | The AmazonResourceName(ARN) of the application |
| result | "queued" \$1 "completed" \$1 "failed" | Indicates if the request is queued, completed or failed |
**Permissions required:**
```
*
```
# Get application information in Amazon Connect Agent Workspace
Returns the application information for the given application instance ID in the Amazon Connect agent workspace.
**Signature**
```
getApp(instanceId: string): Promise
```
**Usage**
```
const applicationInfo: AppInfo = await appControllerClient.getApp(appInstanceId);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| appInstanceId Required | string | The instance ID of the application |
**Output - AppInfo**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| instanceId | string | Unique ID of the application instance |
| config | Config | The configuration of the application |
| startTime | Date | Time when the application is launched |
| state | AppState | Current state of the application |
| appCreateOrder | number | Sequentially incremented counter upon new application launches |
| accessUrl | string | Access URL of the application |
| parameters | AppParameters \$1 undefined | Key value pair of parameters passed to the application |
| launchKey | string | A unique id to avoid duplicate application being launched with multiple invocation of launchApp API |
| scope | ContactScope \$1 IdleScope | Indicates if the application is launched with idle i.e when there are no contacts or launched during an active contact |
**Permissions required:**
```
*
```
# Get the application catalog in Amazon Connect Agent Workspace
Returns all the applications that are available in the Amazon Connect agent workspace for the current logged-in user.
**Signature**
```
getAppCatalog(): Promise
```
**Usage**
```
const applications: AppConfig[] = await appControllerClient.getAppCatalog();
```
**Output - AppConfig**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| arn | string | The AmazonResourceName(ARN) of the application |
| namespace | string | The immutable application namespace used at the time of registration |
| id | string | The unique identifier of the application |
| name | string | Name of the application |
| description | string | Description of the application |
| accessUrl | string | URL to access the application |
| initializationTimeout | number | The maximum time allowed in milliseconds to establish a connection with the workspace |
| contactHandling.scope | PER\$1CONTACT \$1 CROSS\$1CONTACTS | Indicates whether the application refreshes for each contact |
**Permissions required:**
```
*
```
# Get the application configuration in Amazon Connect Agent Workspace
Returns the application configuration for the given application ARN in the Amazon Connect agent workspace.
**Signature**
```
getAppConfig(appArn: string): Promise
```
**Usage**
```
const applicationConfig: AppConfig = await appControllerClient.getAppConfig(arn);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| arn Required | string | The ARN of the application |
**Output - AppConfig**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| arn | string | The AmazonResourceName(ARN) of the application |
| namespace | string | The immutable application namespace used at the time of registration |
| id | string | The unique identifier of the application |
| name | string | Name of the application |
| description | string | Description of the application |
| accessUrl | string | URL to access the application |
| initializationTimeout | number | The maximum time allowed to establish a connection with the workspace |
| contactHandling.scope | PER\$1CONTACT \$1 CROSS\$1CONTACTS | Indicates whether the application refreshes for each contact |
**Permissions required:**
```
*
```
# Get all active application information in Amazon Connect Agent Workspace
Returns the application information for all active application instances in the Amazon Connect agent workspace.
**Signature**
```
getApps(): Promise
```
**Usage**
```
const applicationInfo: AppInfo[] = await appControllerClient.getApps();
```
**Output - AppInfo**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| instanceId | string | Unique ID of the application instance |
| config | Config | The configuration of the application |
| startTime | Date | Time when the application is launched |
| state | AppState | Current state of the application |
| appCreateOrder | number | Sequentially incremented counter upon new application launches |
| accessUrl | string | Access URL of the application |
| parameters | AppParameters \$1 undefined | Key value pair of parameters passed to the application |
| launchKey | string | A unique id to avoid duplicate application being launched with multiple invocation of launchApp API |
| scope | ContactScope \$1 IdleScope | Indicates if the application is launched with idle i.e when there are no contacts or launched during an active contact |
**Permissions required:**
```
*
```
# Launch an application in Amazon Connect Agent Workspace
Launch the application in the agent workspace for the given application ARN or name. It supports optional launch options to fine tune the launch behavior.
**Signature**
```
launchApp(arnOrName: string, options?: AppLaunchOptions): Promise
```
**Usage**
```
const applicationsConfig: AppConfig[] = await appControllerClient.getAppCatalog();
const appInfo: AppInfo = await appControllerClient.launchApp(applicationsConfig[0].arn);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| arnOrName Required | string | The ARN or name of the application |
| options.parameters | AppParameters | Key value pair of parameters passed to the application |
| options.launchKey | string | A unique id to avoid duplicate application being launched with multiple invocation of launchApp API |
| options.openInBackground | boolean | If set to true, the application won't be set to focus after its launched |
| options.scope | ContactScope \$1 IdleScope | Indicates if the application is launched with idle i.e when there are no contacts or launched during an active contact |
**Output - AppInfo**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| instanceId | string | Unique ID of the application instance |
| config | Config | The configuration of the application |
| startTime | Date | Time when the application is launched |
| state | AppState | Current state of the application |
| appCreateOrder | number | Sequentially incremented counter upon new application launches |
| accessUrl | string | Access URL of the application |
| parameters | AppParameters \$1 undefined | Key value pair of parameters passed to the application |
| launchKey | string | A unique id to avoid duplicate application being launched with multiple invocation of launchApp API |
| scope | ContactScope \$1 IdleScope | Indicates if the application is launched with idle i.e when there are no contacts or launched during an active contact |
**Permissions required:**
```
*
```
# Amazon Connect Agent Workspace Contact API
The Amazon Connect SDK provides an `ContactClient` which serves as an interface that your app in the Amazon Connect agent workspace can use to subscribe to contact events and make contact data requests.
The `ContactClient` 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 { ContactClient } from "@amazon-connect/contact";
const contactClient = new ContactClient({ 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 { ContactClient } from "@amazon-connect/contact";
const contactClient = new ContactClient({
context: sampleContext,
provider: sampleProvider
});
```
The following sections describe API calls for working with the Contact API.
**Topics**
+ [accept()](3P-apps-contact-requests-accept.md)
+ [addParticipant()](3P-apps-contact-requests-addparticipant.md)
+ [clear()](3P-apps-contact-requests-clear.md)
+ [onCleared()](3P-apps-contact-requests-clearedsubscribing.md)
+ [offCleared()](3P-apps-contact-requests-clearedunsubscribing.md)
+ [onConnected()](3P-apps-contact-events-connected-sub.md)
+ [offConnected()](3P-apps-contact-events-connected-unsub.md)
+ [disconnectParticipant()](3P-apps-contact-requests-disconnectparticipant.md)
+ [engagePreviewContact()](3P-apps-contact-requests-engagepreviewcontact.md)
+ [getAttribute()](3P-apps-contact-requests-getattribute.md)
+ [getAttributes()](3P-apps-contact-requests-getattributes.md)
+ [getChannelType()](3P-apps-contact-requests-getchanneltype.md)
+ [getContact()](3P-apps-contact-requests-getcontact.md)
+ [getInitialContactId()](3P-apps-contact-requests-getinitialcontactid.md)
+ [getParticipant()](3P-apps-contact-requests-getparticipant.md)
+ [getParticipantState()](3P-apps-contact-requests-getparticipantstate.md)
+ [getPreviewConfiguration()](3P-apps-contact-requests-getpreviewconfiguration.md)
+ [getQueue()](3P-apps-contact-requests-getqueue.md)
+ [getQueueTimestamp()](3P-apps-contact-requests-getqueuetimestamp.md)
+ [getStateDuration()](3P-apps-contact-requests-getstateduration.md)
+ [isPreviewMode()](3P-apps-contact-requests-ispreviewmode.md)
+ [listContacts()](3P-apps-contact-requests-listcontacts.md)
+ [listParticipants()](3P-apps-contact-requests-listparticipants.md)
+ [onMissed()](3P-apps-contact-events-missed-sub.md)
+ [offMissed()](3P-apps-contact-events-missed-unsub.md)
+ [offIncoming()](3P-apps-contact-requests-off-incoming.md)
+ [onIncoming()](3P-apps-contact-requests-on-incoming.md)
+ [onParticipantAdded()](3P-apps-contact-events-participantadded-sub.md)
+ [offParticipantAdded()](3P-apps-contact-events-participantadded-unsub.md)
+ [onParticipantDisconnected()](3P-apps-contact-events-participantdisconnected-sub.md)
+ [offParticipantDisconnected()](3P-apps-contact-events-participantdisconnected-unsub.md)
+ [onParticipantStateChanged()](3P-apps-contact-events-participantstatechanged-sub.md)
+ [onStartingAcw()](3P-apps-contact-events-startingacw-sub.md)
+ [offStartingAcw()](3P-apps-contact-events-startingacw-unsub.md)
+ [transfer()](3P-apps-contact-requests-transfer.md)
# Accept the incoming contact for the given contactId in Amazon Connect Agent Workspace
Accept the incoming contact for the given contactId.
**Signature**
```
accept(contactId: string): Promise
```
**Usage**
```
await contactClient.accept(contactId);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The id of the contact to which a participant needs to be added. |
**Permissions required:**
```
Contact.Details.Edit
```
# Add another participant to a contact in Amazon Connect Agent Workspace
Add another participant to the contact. Multi-party only works for Voice at this time. For Voice, the existing participants will be put on hold when a new participant is added.
**Signature**
```
addParticipant(
contactId: string,
quickConnect: QuickConnect,
): Promise
```
**Usage**
```
const routingProfile: AgentRoutingProfile = await agentClient.getRoutingProfile();
const quickConnectResult: ListQuickConnectsResult = await agentClient.listQuickConnects(routingProfile.queues[0].queueARN);
const quickConnect: QuickConnect = quickConnectResult.quickConnects[1];
const addParticipantResult: AddParticipantResult = await contactClient.addParticipant(contactId, quickConnect);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The id of the contact to which a participant needs to be added. |
| quickConnect Required | QuickConnect | Its either AgentQuickConnect or QueueQuickConnect or PhoneNumberQuickConnect which contains endpointARN and name. Additionally PhoneNumberQuickConnect contains phoneNumber |
**Output - AddParticipantResult**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| participantId | string | The id of the newly added participant |
**Permissions required:**
```
Contact.Details.Edit
```
# Clears the contact for the given contactId in Amazon Connect Agent Workspace
Clears the contact for the given contactId.
**Signature**
```
clear(contactId: string): Promise
```
**Usage**
```
await contactClient.clear(contactId);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The id of the contact to which a participant needs to be added. |
**Permissions required:**
```
Contact.Details.Edit
```
# Creates a subscription whenever a contact cleared event occurs in Amazon Connect Agent Workspace
It creates a subscription whenever a contact cleared event occurs in Amazon Connect agent workspace. If no contact ID is provided, then it uses the context of the current contact that the 3P app was opened on.
**Signature**
onCleared(handler: ContactClearedHandler, contactId?: string)
**Usage**
```
const handler: ContactClearedHandler = async (data: ContactCleared) => {
console.log("Contact cleared occurred! " + data);
};
contactClient.onCleared(handler);
// ContactCleared Structure
{
contactId: string;
}
```
**Permissions required:**
```
Contact.Details.View
```
# Unsubscribes the callback function from the contact cleared event in Amazon Connect Agent Workspace
Unsubscribes the callback function from the contact cleared event in Amazon Connect agent workspace.
**Signature**
```
offCleared(handler: ContactClearedHandler, contactId?: string)
```
**Usage**
```
contactClient.offCleared(handler);
```
# Subscribe a callback function when an Amazon Connect Agent Workspace contact is connected
Subscribes a callback function to-be-invoked whenever a contact Connected event occurs in the Amazon Connect agent workspace. If no contact ID is provided, then it uses the context of the current contact that the 3P app was opened on.
**Signature**
```
onConnected(handler: ContactConnectedHandler, contactId?: string)
```
**Usage**
```
const handler: ContactConnectedHandler = async (data: ContactConnected) => {
console.log("Contact Connected occurred! " + data);
};
contactClient.onConnected(handler);
// ContactConnected Structure
{
contactId: string;
}
```
**Permissions required:**
```
Contact.Details.View
```
# Unsubscribe a callback function when an Amazon Connect Agent Workspace contact is connected
Unsubscribes the callback function from Connected event in the Amazon Connect agent workspace.
**Signature**
```
offConnected(handler: ContactConnectedHandler)
```
**Usage**
```
contactClient.offConnected(handler);
```
# Disconnect a participant from a contact in Amazon Connect Agent Workspace
Disconnects a specific participant from the contact.
**Signature**
```
disconnectParticipant(participantId: string): Promise
```
**Usage**
```
await contactClient.disconnectParticipant("participant-456");
console.log("Participant disconnected");
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| participantId Required | string | The unique identifier for the participant to disconnect |
**Permissions required:**
```
*
```
# Engage the preview contact for the given contactId in Amazon Connect Agent Workspace
When an agent is previewing a preview contact, this API will actually initiate the outbound dial to the end customer, ending the preview experience.
**Signature**
```
engagePreviewContact(contactId: string): Promise
```
**Usage**
```
const addParticipantResult: AddParticipantResult = await contactClient.engagePreviewContact(contactId);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The id of the contact which is being previewed by the agent to which a participant needs to be added. |
**Output - AddParticipantResult**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| participantId | string | The id of the newly added participant |
**Permissions required:**
```
*
```
# Get specific attributes for a contact in Amazon Connect Agent Workspace
Returns the requested attribute associated with the contact in the Amazon Connect agent workspace.
```
async getAttribute(
contactId: string,
attribute: string,
): Promise
```
**Permissions required:**
```
Contact.Attributes.View
```
# Get the attributes of a contact in Amazon Connect Agent Workspace
Returns a map of the attributes associated with the contact in the Amazon Connect Agent Workspace. Each value in the map has the following shape: `{ name: string, value: string }`.
```
// example { "foo": { "name": "foo", "value": "bar" } }
```
```
getAttributes(
contactId: string,
attributes: ContactAttributeFilter,
): Promise>
```
```
ContactAttributeFilter is either string[] of attributes or '*'
```
**Permissions required:**
```
Contact.Attributes.View
```
# Get the type of contact in Amazon Connect Agent Workspace
Get the type of the contact in Amazon Connect agent workspace. This indicates what type of media is carried over the connections of the contact.
**Signature**
```
getChannelType(contactId: string): Promise
```
**Usage**
```
const contactType: ContactChannelType = await contactClient.getChannelType(contactId);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The id of the contact to which a participant needs to be added. |
**Output - ContactChannelType**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| type | string | The possible values are voice, queue\$1callback, chat, task, email |
| subtype | string | For the types `voice` & `queue_callback`, it will be `connect:Telephony` \$1 `connect:WebRTC` . For the type `chat`, it will be `connect:Chat` \$1 `connect:SMS` \$1 `connect:Apple` \$1 ` connect:Guide`. For the type `task`, it will be `connect:Task` . For the type `email`, it will be `connect:Email` . |
**Permissions required:**
```
Contact.Details.View
```
# Get detailed contact information in Amazon Connect Agent Workspace
Retrieves detailed information for a specific contact by its ID.
**Signature**
```
getContact(contactId: string): Promise
```
**Usage**
```
const contactData = await contactClient.getContact("contact-123");
console.log(`Contact type: ${contactData.type}`);
console.log(`Queue: ${contactData.queue.name}`);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The unique identifier for the contact |
**Output - ContactData**
The ContactData interface includes:
+ `contactId`: string - Unique identifier for the contact
+ `type`: ContactType - Type of contact (voice, chat, task)
+ `subtype`: string - Subtype providing additional classification
+ `initialContactId`?: string - Initial contact ID for transferred contacts
+ `queue`: Queue - Queue information
**Permissions required:**
```
*
```
# Get the initial ID of the contact in Amazon Connect Agent Workspace
Returns the original (initial) contact id from which this contact was transferred in the Amazon Connect agent workspace, or none if this is not an internal Connect transfer. This is typically a contact owned by another agent, thus this agent will not be able to manipulate it. It is for reference and association purposes only, and can be used to share data between transferred contacts externally if it is linked by originalContactId.
```
async getInitialContactId(contactId: string): Promise
```
**Permissions required:**
```
Contact.Details.View
```
# Get specific participant information in Amazon Connect Agent Workspace
Retrieves information for a specific participant.
**Signature**
```
getParticipant(participantId: string): Promise
```
**Usage**
```
const participant = await contactClient.getParticipant("participant-456");
console.log(`Participant type: ${participant.type.value}`);
console.log(`Is initial: ${participant.isInitial}`);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| participantId Required | string | The unique identifier for the participant |
**Output - ParticipantData**
Returns a ParticipantData object with participant details.
**Permissions required:**
```
*
```
# Get participant state in Amazon Connect Agent Workspace
Retrieves the current state of a specific participant.
**Signature**
```
getParticipantState(participantId: string): Promise
```
**Usage**
```
const state = await contactClient.getParticipantState("participant-456");
if (state.value === "connected") {
console.log("Participant is connected");
} else if (state.value === "hold") {
console.log("Participant is on hold");
}
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| participantId Required | string | The unique identifier for the participant |
**Output - ParticipantState**
The ParticipantState type can be:
+ \$1 value: ParticipantStateType \$1 where ParticipantStateType includes: connecting, connected, hold, disconnected, rejected, silent\$1monitor, barge
+ \$1 value: "other"; actual: string \$1 for unknown states
**Permissions required:**
```
*
```
# Get preview configuration for the given contactId in Amazon Connect Agent Workspace
This gets configuration information related to the preview experience.
**Signature**
```
getPreviewConfiguration(contactId: string): Promise
```
**Usage**
```
const isPreview = await contactClient.isPreviewMode(contactId);
if (isPreview) {
const {autoDialTimeout, canDiscardPreview} = await contactClient.getPreviewConfiguration(contactId);
}
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The id of the contact which is in preview. |
**Output - GetPreviewConfigurationResponse**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| autoDialTimeout | number | The number of seconds the agent has to preview the contact before the auto-dial triggers. |
| canDiscardPreview | boolean | Whether the agent has permission to discard the contact during preview. Use this to control whether the agent should be presented the option to discard the contact without dialing the end customer. |
**Permissions required:**
```
*
```
# Get the queue of the contact in Amazon Connect Agent Workspace
Returns the queue associated with the contact in the Amazon Connect agent workspace. The `Queue` object has the following fields:
+ `name`: The name of the queue.
+ `queueARN`: The ARN of the queue.
+ `queueId`: Alias for `queueARN`.
```
async getQueue(contactId: string): Promise
```
**Permissions required:**
```
Contact.Details.View
```
# Get the timestamp of the contact in Amazon Connect Agent Workspace
Returns a `Date` object with the timestamp associated with when the contact was placed in the queue in the Amazon Connect agent workspace.
```
async getQueueTimestamp(contactId: string): Promise
```
**Permissions required:**
```
Contact.Details.View
```
# Get the duration of the contact state in Amazon Connect Agent Workspace
Returns the duration of the contact state in milliseconds relative to local time, in the Amazon Connect agent workspace. This takes into account time skew between the JS client and the Amazon Connect backend servers.
```
async getStateDuration(contactId: string): Promise
```
**Permissions required:**
```
Contact.Details.View
```
# Check if contact is in preview mode in Amazon Connect Agent Workspace
Returns whether the contact is being previewed. During this time, calling engagePreviewContact will trigger the outbound dial to the end customer and end preview mode.
**Signature**
```
isPreviewMode(contactId: string): Promise
```
**Usage**
```
const isPreviewMode = await contactClient.isPreviewMode(currentContactId);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The id of the contact. |
**Permissions required:**
```
*
```
# List all contacts for the current agent in Amazon Connect Agent Workspace
Lists all contacts for the current agent.
**Signature**
```
listContacts(): Promise
```
**Usage**
```
const contacts = await contactClient.listContacts();
console.log(`Active contacts: ${contacts.length}`);
contacts.forEach((contact) => {
console.log(`Contact ${contact.contactId}: ${contact.type}`);
});
```
**Output - ListContactsResult**
Returns an array of contact data objects (currently typed as CoreContactData[]).
**Permissions required:**
```
*
```
# List all participants for a contact in Amazon Connect Agent Workspace
Retrieves all participants associated with a specific contact.
**Signature**
```
listParticipants(contactId: string): Promise
```
**Usage**
```
const participants = await contactClient.listParticipants("contact-123");
participants.forEach((p) => {
console.log(`Participant ${p.participantId}: ${p.type.value}`);
if (p.isSelf) {
console.log("This is the current user");
}
});
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The unique identifier for the contact |
**Output - ParticipantData[]**
The ParticipantData interface includes:
+ `participantId`: string - Unique identifier for the participant
+ `contactId`: string - Contact this participant belongs to
+ `type`: ParticipantType - Type of participant (agent, outbound, inbound, monitoring, other)
+ `isInitial`: boolean - Whether this is the initial participant
+ `isSelf`: boolean - Whether this participant is associated with the current user
**Permissions required:**
```
*
```
# Subscribe a callback function when an Amazon Connect Agent Workspace contact is missed
Subscribes a callback function to-be-invoked whenever a contact missed event occurs in the Amazon Connect agent workspace. If no contact ID is provided, then it uses the context of the current contact that the 3P app was opened on.
**Signature**
```
onMissed(handler: ContactMissedHandler, contactId?: string)
```
**Usage**
```
const handler: ContactMissedHandler = async (data: ContactMissed) => {
console.log("Contact missed occurred! " + data);
};
contactClient.onMissed(handler);
// ContactMissed Structure
{
contactId: string;
}
```
**Permissions required:**
```
Contact.Details.View
```
# Unsubscribe a callback function when an Amazon Connect Agent Workspace contact is missed
Unsubscribes the callback function from the contact missed event.
**Signature**
```
offMissed(handler: ContactMissedHandler, contactId?: string)
```
**Usage**
```
contactClient.offMissed(handler);
```
# Unsubscribe from incoming contact events in Amazon Connect Agent Workspace
Unsubscribes the callback function from the contact incoming event in Amazon Connect agent workspace.
**Signature**
```
offIncoming(handler: ContactIncomingHandler, contactId?: string): void
```
**Usage**
```
contactClient.offIncoming(handler);
```
# Subscribe to incoming contact events in Amazon Connect Agent Workspace
Creates a subscription whenever a new incoming event occurs in the Amazon Connect agent workspace.
**Signature**
```
onIncoming(handler: ContactIncomingHandler, contactId?: string): void
```
**Usage**
```
const handler: ContactIncomingHandler = async (data: ContactIncoming) => {
console.log("Contact incoming occurred! " + data);
};
contactClient.onIncoming(handler);
// ContactIncoming Structure
{
contactId: string;
initialContactId: string | undefined;
type: ContactChannelType["type"];
subtype: ContactChannelType["subtype"];
}
```
**Permissions required:**
```
*
```
# Subscribe to participant added events in Amazon Connect Agent Workspace
Subscribes to participant added events. This event fires when a new participant joins a contact.
**Signature**
```
onParticipantAdded(handler: ParticipantAddedHandler, contactId?: string): void
```
**Usage**
```
const handleParticipantAdded = (event) => {
console.log(`New participant added: ${event.participant.participantId}`);
console.log(`Type: ${event.participant.type.value}`);
};
// Subscribe to all contacts
contactClient.onParticipantAdded(handleParticipantAdded);
// Or subscribe to a specific contact
contactClient.onParticipantAdded(handleParticipantAdded, "contact-123");
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| handler Required | ParticipantAddedHandler | Event handler function to call when participants are added |
| contactId | string | Optional contact ID to filter events for a specific contact |
**Event Structure - ParticipantAdded**
The handler receives a ParticipantAdded event with:
+ `participant`: ParticipantData - The participant that was added
**Permissions required:**
```
*
```
# Unsubscribe from participant added events in Amazon Connect Agent Workspace
Unsubscribes from participant added events.
**Signature**
```
offParticipantAdded(handler: ParticipantAddedHandler, contactId?: string): void
```
**Usage**
```
contactClient.offParticipantAdded(handleParticipantAdded);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| handler Required | ParticipantAddedHandler | Event handler function to remove |
| contactId | string | Optional contact ID to unsubscribe from specific contact events |
# Subscribe to participant disconnected events in Amazon Connect Agent Workspace
Subscribes to participant disconnected events. This event fires when a participant leaves or is removed from a contact.
**Signature**
```
onParticipantDisconnected(handler: ParticipantDisconnectedHandler, contactId?: string): void
```
**Usage**
```
const handleParticipantDisconnected = (event) => {
console.log(`Participant disconnected: ${event.participant.participantId}`);
};
contactClient.onParticipantDisconnected(
handleParticipantDisconnected,
"contact-123"
);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| handler Required | ParticipantDisconnectedHandler | Event handler function to call when participants disconnect |
| contactId | string | Optional contact ID to filter events for a specific contact |
**Event Structure - ParticipantDisconnected**
The handler receives a ParticipantDisconnected event with:
+ `participant`: ParticipantData - The participant that was disconnected
**Permissions required:**
```
Contact.Details.View
```
# Unsubscribe from participant disconnected events in Amazon Connect Agent Workspace
Unsubscribes from participant disconnected events.
**Signature**
```
offParticipantDisconnected(handler: ParticipantDisconnectedHandler, contactId?: string): void
```
**Usage**
```
contactClient.offParticipantDisconnected(handleParticipantDisconnected);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| handler Required | ParticipantDisconnectedHandler | Event handler function to remove |
| contactId | string | Optional contact ID to unsubscribe from specific contact events |
# Subscribe to participant state change events in Amazon Connect Agent Workspace
Subscribes to participant state change events. This event fires when a participant's state changes (e.g., from connecting to connected, or to hold).
**Signature**
```
onParticipantStateChanged(handler: ParticipantStateChangedHandler, participantId?: string): void
```
**Usage**
```
const handleStateChanged = (event) => {
console.log(
`Participant ${event.participantId} state changed to: ${event.state.value}`
);
if (event.state.value === "connected") {
console.log("Participant is now connected");
} else if (event.state.value === "hold") {
console.log("Participant is now on hold");
}
};
// Subscribe to all participants
contactClient.onParticipantStateChanged(handleStateChanged);
// Or subscribe to a specific participant
contactClient.onParticipantStateChanged(handleStateChanged, "participant-456");
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| handler Required | ParticipantStateChangedHandler | Event handler function to call when participant states change |
| participantId | string | Optional participant ID to filter events for a specific participant |
**Event Structure - ParticipantStateChanged**
The handler receives a ParticipantStateChanged event with:
+ `participantId`: string - The ID of the participant whose state changed
+ `state`: ParticipantState - The new state of the participant
**Permissions required:**
```
Contact.Details.View
```
# Subscribe a callback function when an Amazon Connect Agent Workspace contact starts ACW
Subscribes a callback function to-be-invoked whenever a contact StartingAcw event occurs in the Amazon Connect agent workspace. If no contact ID is provided, then it uses the context of the current contact that the 3P app was opened on.
**Signature**
```
onStartingAcw(handler: ContactStartingAcwHandler, contactId?: string)
```
**Usage**
```
const handler: ContactStartingAcwHandler = async (data: ContactStartingAcw) => {
console.log("Contact StartingAcw occurred! " + data);
};
contactClient.onStartingAcw(handler);
// ContactStartingAcw Structure
{
contactId: string;
}
```
**Permissions required:**
```
Contact.Details.View
```
# Unsubscribe a callback function when an Amazon Connect Agent Workspace contact starts ACW
Unsubscribes the callback function from the contact StartingAcw event in the Amazon Connect agent workspace.
**Signature**
```
offStartingAcw(handler: ContactStartingAcwHandler, contactId?: string)
```
**Usage**
```
contactClient.offStartingAcw(handler);
```
# Transfer a contact to another agent in Amazon Connect Agent Workspace
Performs a cold transfer by transferring the given contact to another agent using a quick connect and disconnecting from the contact. The quick connect type has to be either `agent` or `queue`. Supports voice, chat, task, and email channels.
**Signature**
```
transfer(
contactId: string,
quickConnect: AgentQuickConnect | QueueQuickConnect,
): Promise
```
**Usage**
```
const routingProfile: AgentRoutingProfile = await agentClient.getRoutingProfile();
const quickConnectResult: ListQuickConnectsResult = await agentClient.listQuickConnects(routingProfile.queues[0].queueARN);
const quickConnect: QuickConnect = quickConnectResult.quickConnects[1];
await contactClient.transfer(contactId, quickConnect);
```
**Input**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId Required | string | The id of the contact to which a participant needs to be added. |
| quickConnect Required | QuickConnect | Its either AgentQuickConnect or QueueQuickConnect |
**Permissions required:**
```
Contact.Details.Edit
```
# Amazon Connect Agent Workspace Email API
The Amazon Connect SDK provides an `EmailClient` which serves as an interface that your app can use to subscribe to email contact events and make email contact requests.
The `EmailClient` 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 { EmailClient } from "@amazon-connect/email";
const emailClient = new EmailClient({ 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 { EmailClient } from "@amazon-connect/email";
const emailClient = new EmailClient({
context: sampleContext,
provider: sampleProvider
});
```
**Note**
Third-party applications must be configured with Cross Contact scope in order to utilize the EmailClient APIs, and \$1 permission is required.
The following sections describe API calls for working with the Email API.
**Topics**
+ [onAcceptedEmail()](3P-apps-email-requests-acceptedemail-subscribing.md)
+ [offAcceptedEmail()](3P-apps-email-requests-acceptedemail-unsubscribing.md)
+ [createDraftEmail()](3P-apps-email-requests-createdraftemail.md)
+ [onDraftEmailCreated()](3P-apps-email-requests-draftemailcreated-subscribing.md)
+ [offDraftEmailCreated()](3P-apps-email-requests-draftemailcreated-unsubscribing.md)
+ [getEmailData()](3P-apps-email-requests-getemaildata.md)
+ [getEmailThread()](3P-apps-email-requests-getemailthread.md)
+ [sendEmail()](3P-apps-email-requests-sendemail.md)
# Subscribe to accepted email notifications in Amazon Connect Agent Workspace
Subscribes a callback function to-be-invoked whenever an inbound email contact has been accepted.
**Signature**
```
onAcceptedEmail(handler: SubscriptionHandler contactId?: string): void
```
**Usage**
```
const handler: SubscriptionHandler = async (emailContact: EmailContactId) => {
const { contactId } = emailContact;
console.log(`Accepted Email Contact with Id: ${contactId}`);
}
emailClient.onAcceptedEmail(handler);
// EmailContactId Structure
{
contactId: string;
}
```
# Unsubscribe from accepted email notifications in Amazon Connect Agent Workspace
Unsubscribes a callback function from the event that is fired when an inbound email contact is accepted.
**Signature**
```
offAcceptedEmail(handler: SubscriptionHandler, contactId?: string): void
```
**Usage**
```
emailClient.offAcceptedEmail(handler);
```
# Create a draft email contact in Amazon Connect Agent Workspace
Creates a draft outbound email contact; can either be an agent initiated outbound draft email or an agent reply draft email. Upon successful draft creation, the email contact will be in connected state. Returns an object that includes:
+ `contactId: string`: The contact id of the newly created draft email contact
**Signature**
```
createDraftEmail(contactCreation: CreateDraftEmailContact): Promise
```
**CreateDraftEmailContact Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| initiationMethod | "AGENT\$1REPLY" \$1 "OUTBOUND" | "OUTBOUND" indicates that this draft email is the start of a new email conversation; "AGENT\$1REPLY" indicates that this draft email is being sent in response to an incoming email contact |
| relatedContactId | string | The id of the contact that is the reason for creating the new draft email; this is required when initiationMethod="AGENT\$1REPLY" and should be the contact id of the email that this email is being sent in response to. |
| expiryDurationInMinutes | number | Length of time before an unsent contact expires; Minimum is 1 minute, Maximum is 1 week; Default is 12 hours. |
| attributes | Record | A custom key-value pair using an attribute map. The attributes are standard Amazon Connect attributes, and can be accessed in flows just like any other contact attributes. |
| references | Record | Well-formed data on a contact, used by agents to complete a contact request. |
**Usage for Agent Initiated Outbound**
```
const contact: EmailContactId = await emailClient.createDraftEmail({
initiationMethod: "OUTBOUND",
});
const { contactId } = contact;
```
**Usage for Agent Reply**
```
const acceptedInboundEmailContactId = "exampleContactId";
const contact: EmailContactId = await emailClient.createDraftEmail({
initiationMethod: "AGENT_REPLY",
relatedContactId: acceptedInboundEmailContactId,
});
const { contactId } = contact;
```
# Subscribe to draft email creation notifications in Amazon Connect Agent Workspace
Subscribes a callback function to-be-invoked whenever a draft email contact has been created.
**Signature**
```
onDraftEmailCreated(handler: SubscriptionHandler, contactId?: string): void
```
**Usage**
```
const handler: SubscriptionHandler = async (emailContact: EmailContactId) => {
const { contactId } = emailContact;
console.log(`Draft Email Contact Created with Id: ${contactId}`);
}
emailClient.onDraftEmailCreated(handler);
// EmailContactId Structure
{
contactId: string;
}
```
# Unsubscribe from draft email creation notifications in Amazon Connect Agent Workspace
Unsubscribes a callback function from the event that is fired when a draft email contact is created.
**Signature**
```
offDraftEmailCreated(handler: SubscriptionHandler, contactId?: string): void
```
**Usage**
```
emailClient.offDraftEmailCreated(handler);
```
# Get the metadata for an email contact in Amazon Connect Agent Workspace
Returns the metadata for an email contact id while handling an active contact. The activeContactId is the id of the email contact the agent is actively viewing while contactId is the id of the email contact whose metadata should be retrieved.
**Signature**
```
getEmailData({ contactId, activeContactId }: { contactId: string; activeContactId: string; }): Promise
```
**Output - *EmailContact Properties***
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId | string | The id of the email contact |
| contactArn | string | The ARN of the email contact |
| contactAssociationId | string | The root contactId which is used as a unique identifier for all subsequent contacts in a contact tree. Use this value with the EmailClient.getEmailThread api. |
| relatedContactId | string | This contact is in response or related to the specified related contact. |
| initialContactId | string | If this contact is related to other contacts, this is the id of the initial contact. |
| subject | string | The subject of the email |
| from | EmailAddress | An object that includes the from email address; this value could be undefined when the email contact has not been sent. |
| to | EmailAddress[] | An array of objects, each including an email address the email contact was sent to |
| cc | EmailAddress[] | An array of objects, each including an email address that was carbon copied on the email contact |
| deliveredTo | EmailAddress | An object that includes the email address associated with Amazon Connect that received this message; this is only applicable when direction=INBOUND. |
| direction | "INBOUND" \$1 "OUTBOUND" | INBOUND means the email contact was delivered to Amazon Connect; OUTBOUND means the email contact is from Amazon Connect |
| bodyLocation | EmailArtifactLocation | An object that includes the id and associated resource ARN of the file that the email contact's body is stored in; this value could be undefined when the email contact has not been sent. |
| attachmentLocations | EmailArtifactLocation[] | An array of objects, each including the id and associated resource ARN, of files that have been attached to the email contact |
**EmailAddress Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| emailAddress | string | The email address |
| displayName | string | The name that is displayed inside the recipient's mailbox |
**EmailArtifactLocation Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| fileId | string | The id of the attached file |
| associatedResourceArn | string | The Amazon Connect resource to which the attached file is related to |
**Usage**
```
const activeContactId: string = "exampleActiveContactId"; // The contact the agent is actively handling
const contactId: string = "contactIdToDescribe"; // The email contact id whose metadata should be retrieved
const emailMetadata: EmailContact = await emailClient.getEmailData({ contactId, activeContactId });
// Get the body of the email through the File Client
const bodyLocation = emailMetadata.bodyLocation;
if (bodyLocation) {
const body: DownloadableAttachment = await fileClient.getAttachedFileUrl({
attachment: bodyLocation,
activeContactId,
});
const { downloadUrl } = body;
const response: Response = await fetch(downloadUrl, { method: "GET" });
const bodyContent: string = (await response.json()).messageContent;
}
```
**Note**
The EmailContact object will contain bodyLocation and attachmentLocations, both of which will require use of the FileClient's getAttachedFileUrl to get the relevant data for those objects.
# Get a list of email contacts in an email contact's tree in Amazon Connect Agent Workspace
Returns an array of EmailThreadContact objects (for the provided contactAssociationId) that represent that contact's email thread. The contactAssociationId is the root contact id which is used as a unique identifier for all subsequent contacts in a contact tree. Returns an object that includes:
+ `contacts: EmailThreadContact[]`: an array of EmailThreadContact objects, each an email contact in the thread
+ `nextToken?: string`: The token for the next set of results; use the value returned in the previous response in the next request to retrieve the next set of results
**Signature**
```
getEmailThread(getEmailThreadParams: GetEmailThreadParams): Promise<{ contacts: EmailThreadContact[]; nextToken?: string; }>
```
**EmailThreadContact Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactId | string | The id of the email contact |
| contactArn | string | The ARN of the email contact |
| previousContactId | string | If this contact is not the first contact, this is the ID of the previous contact. |
| initialContactId | string | If this contact is related to other contacts, this is the ID of the initial contact. |
| relatedContactId | string | The contactId that is related to this contact. |
| initiationMethod | string | Indicates how the contact was initiated; Supported values: "INBOUND" ,"OUTBOUND", "AGENT\$1REPLY", or "TRANSFER" |
| initiationTimestamp | Date | The date and time this contact was initiated, in UTC time. |
| disconnectTimestamp | Date \$1 undefined | The date and time that the customer endpoint disconnected from the current contact, in UTC time. In transfer scenarios, the DisconnectTimestamp of the previous contact indicates the date and time when that contact ended. |
**GetEmailThreadParams Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contactAssociationId | string | The contact association id to get the thread for. |
| maxResults | number | The max number of email threads to return; Default is 100. Minimum value of 1. Maximum value of 100. |
| nextToken | string | The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results. |
**Usage**
```
const inboundEmailData = await emailClient.getEmailData({
contactId: sampleContactId, // The inbound email contact you've accepted (or is still connecting)
activeContactId: sampleContactId, // The email contact you're actively working; in this example, its the same as the accepted inbound email
});
const emailThreadContacts = await emailClient.getEmailThread({
contactAssociationId: inboundEmailData.contactAssociationId,
});
// OPTIONAL: Filter out contacts that have been transferred to avoid displaying duplicated email content
const previousContactIdsSet = new Set(
emailThreadContacts
.map(emailThreadContact => emailThreadContact.previousContactId)
.filter(Boolean)
);
const filteredEmailContactsInEmailThread = emailThreadContacts.filter(emailContact =>
emailContact.contactId === sampleContactId ||
!previousContactIdsSet.includes(emailContact.contactId)
);
```
**Note**
Each time an email contact is transferred, a new contact ID is created with initiationMethod === 'TRANSFER' and its previousContactId is the contact id before the transfer. You may optionally filter out these transferred contacts to avoid duplicate content when rendering the email thread.
# Send a draft email contact in Amazon Connect Agent Workspace
Sends both agent initiated and agent reply draft email contacts. Upon successfully sending the email, the contact will transition to ENDED state.
**Signature**
```
sendEmail(emailContact: DraftEmailContact): Promise
```
**DraftEmailContact Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| to | EmailAddress[] | An array of destination email addresses; max length supported is 1 |
| emailContent | EmailContent | The content of the email |
| from | EmailAddress | The email contact will be sent from this email address; if no from address is provided in the request, the queue MUST have a default email address specified in the Outbound email configuration |
| cc | EmailAddress[] | Additional recipients to receive a carbon copy of the email; Max length supported is 10 |
| contactId | string | The id of the draft email contact |
**EmailAddress Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| emailAddress | string | The email address |
| displayName | string | The name that is displayed inside the recipient's mailbox |
**EmailContent Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| subject | string | The email contact's subject |
| body | string | The body/content of the email, either in plain text or HTML |
| bodyType | "text/plain" \$1 "text/html" | The body type of the email; can either be "text/plain" or "text/html" |
**Error Handling**
When sending draft emails, agents may encounter issues. The @amazon-connect/email library provides methods to handle common errors:
+ `isOutboundEmailAddressNotConfiguredError()`: Handle errors when the routing profile's default outbound queue does not have a default outbound email address and the sendEmail() request does not include a from address.
+ `isEmailBodySizeExceededError()`: Handle errors when the size of the email body exceeds the limit.
+ `isTotalEmailSizeExceededError()`: Handle errors when the total size of the email (email body and all attachments) exceeds the limit.
**Usage**
```
import {
isOutboundEmailAddressNotConfiguredError,
isEmailBodySizeExceededError,
isTotalEmailSizeExceededError,
} from "@amazon-connect/email";
/* ... */
const toEmailAddress = {
emailAddress: sampleRecipientAddress,
};
const emailContent = {
subject: "Hello!",
body: "Thank you!",
bodyType: "text/plain",
}
const draftContact = {
to: [toEmailAddress]
emailContent,
contactId: draftContactId, // This is the contact ID of the draft contact created via createDraftEmail()
};
try {
await emailClient.sendEmail(draftContact);
} catch (e) {
if (isOutboundEmailAddressNotConfiguredError(e)) {
// Handle error when the routing profile's default outbound queue does not have a default
// outbound email address and the request to `sendEmail` does not include a `from` address.
} else if (isEmailBodySizeExceededError(e)) {
// Handle error when the size of the email body exceeds the limit
} else if (isTotalEmailSizeExceededError(e)) {
// Handle error when total size of the email (email body and all attachments) exceeds the limit
}
}
```
# Amazon Connect Agent Workspace File API
The Amazon Connect SDK provides a `FileClient` which serves as an interface that you can use to make file requests to upload, retrieve, and delete attached files.
The `FileClient` 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 { FileClient } from "@amazon-connect/file";
const fileClient = new FileClient({ 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 { FileClient } from "@amazon-connect/file";
const fileClient = new FileClient({
context: sampleContext,
provider: sampleProvider
});
```
**Note**
Third-party applications must be configured with \$1 permission in order to utilize the FileClient APIs.
The following sections describe API calls for working with the File API.
**Topics**
+ [batchGetAttachedFileMetadata()](3P-apps-file-requests-batchgetattachedfilemetadata.md)
+ [completeAttachedFileUpload()](3P-apps-file-requests-completeattachedfileupload.md)
+ [deleteAttachedFile()](3P-apps-file-requests-deleteattachedfile.md)
+ [getAttachedFileUrl()](3P-apps-file-requests-getattachedfileurl.md)
+ [startAttachedFileUpload()](3P-apps-file-requests-startattachedfileupload.md)
# Get metadata about multiple attached files in Amazon Connect Agent Workspace
Get metadata about multiple attached files on an associated resource while handling an active contact. The activeContactId is the id of the contact the agent is actively viewing. Each attached file provided in the input list must be associated with the associatedResourceArn in the RelatedAttachments request object.
**Signature**
```
batchGetAttachedFileMetadata({ relatedAttachments, activeContactId }: { relatedAttachments: RelatedAttachments; activeContactId: string; }): Promise
```
**BatchGetAttachedFileMetadataResponse Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| files | AttachmentMetadata[] | Array of file metadata objects that were successfully retrieved |
| errors | AttachmentError[] | Array of errors of attached files that could not be retrieved |
**AttachmentMetadata Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN |
| fileId | string | The unique identifier of the attached file resource |
| fileArn | string | The unique identifier of the attached file resource (ARN). |
| fileName | string | A case-sensitive name of the attached file being uploaded. |
| fileStatus | FileStatus | The current status of the attached file. Supported values: "APPROVED", "REJECTED", "PROCESSING", "FAILED" |
| fileSizeInBytes | number | The size of the attached file in bytes. |
| creationTime | string | The time of Creation of the file resource as an ISO timestamp. It's specified in ISO 8601 format: yyyy-MM-ddThh:mm:ss.SSSZ. For example, 2024-05-03T02:41:28.172Z. |
**AttachmentError Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| errorCode | string | Status code describing the failure |
| errorMessage | string | Why the attached file couldn't be retrieved |
| fileId | string | The unique identifier of the attached file resource |
**RelatedAttachments Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN |
| fileIds | string[] | The unique identifiers of the attached file resources |
**Usage**
```
const relatedAttachments: RelatedAttachments = {
fileIds: [sampleFileId1, sampleFileId2],
associatedResourceArn: sampleAssociatedResourceArn,
};
const response: BatchGetAttachedFileMetadataResponse = await fileClient.batchGetAttachedFileMetadata({
relatedAttachments,
activeContactId: sampleActiveContactId, // The contact the agent is actively handling
});
const { files, errors } = response;
// Add logic to handle response
```
# Confirm that an attached file has been uploaded in Amazon Connect Agent Workspace
Allows you to confirm that the attachment has been uploaded using the pre-signed URL provided in the startAttachedFileUpload API. The request accepts an Attachment object, which has the following properties:
+ `associatedResourceArn: string`: Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN
+ `fileId: string`: ID in Connect's File record
**Signature**
```
completeAttachedFileUpload(attachment: Attachment): Promise
```
**Usage**
```
/* Logic with startAttachedFileUplaod and uploading attachment to pre-signed URL */
/* ... */
await fileClient.completeAttachedFileUpload({
associatedResourceArn: sampleAssociatedResourceArn, // Get this from the response from `startAttachedFileUpload`
fileId: sampleFileId // Get this from the response from `startAttachedFileUpload`
});
```
# Delete an attached file in Amazon Connect Agent Workspace
Deletes an attached file along with the underlying S3 Object. The attached file is permanently deleted if S3 bucket versioning is not enabled. The request accepts an Attachment object, which has the following properties:
+ `associatedResourceArn: string`: Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN
+ `fileId: string`: ID in Connect's File record
**Signature**
```
deleteAttachedFile(data: Attachment): Promise
```
**Usage**
```
await fileClient.deleteAttachedFile({
associatedResourceArn: sampleAssociatedResourceArn, // Get this from the response from `startAttachedFileUpload`
fileId: sampleFileId // Get this from the response from `startAttachedFileUpload`
});
```
# Get a pre-signed S3 URL to download an approved attached file in Amazon Connect Agent Workspace
Returns a pre-signed URL to download an approved attached file while handling an active contact. The activeContactId is the id of the contact the agent is actively viewing. This API also returns metadata about the attached file and it will only return a downloadUrl if the status of the attached file is APPROVED.
**Signature**
```
getAttachedFileUrl({ attachment, activeContactId }: { attachment: Attachment; activeContactId: string; }): Promise
```
**DownloadableAttachment Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN |
| fileId | string | The unique identifier of the attached file resource. |
| downloadUrl | string | A pre-signed URL that should be used to download the attached file. |
| fileArn | string | The unique identifier of the attached file resource (ARN). |
| fileName | string | A case-sensitive name of the attached file being uploaded. |
| fileStatus | FileStatus | The current status of the attached file. Supported values: "APPROVED", "REJECTED", "PROCESSING", "FAILED" |
| fileSizeInBytes | number | The size of the attached file in bytes. |
| creationTime | string | The time of Creation of the file resource as an ISO timestamp. It's specified in ISO 8601 format: yyyy-MM-ddThh:mm:ss.SSSZ. For example, 2024-05-03T02:41:28.172Z. |
**Attachment Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN |
| fileId | string | The unique identifier of the attached file resource. |
**Usage**
```
const downloadableAttachment = await fileClient.getAttachedFileUrl({
attachment: {
associatedResourceArn: sampleAssociatedResourceArn,
fileId: sampleFileId,
},
activeContactId: sampleActiveContactId, // The contact the agent is actively handling
});
const { downloadUrl } = downloadableAttachment;
const response: Response = await fetch(downloadUrl, { method: "GET" });
```
# Start uploading a file to Amazon Connect Agent Workspace
Provides a pre-signed Amazon S3 URL in response to upload a new attached file.
**Signature**
```
startAttachedFileUpload(data: NewAttachment): Promise
```
**UploadableAttachment Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN |
| fileId | string | ID in Connect's File record |
| uploadUrl | string | A pre-signed S3 URL that should be used for uploading the attached file. |
| uploadHeaders | Record | A map of headers that should be provided in the request when uploading the attached file. |
| uploadMethod | "PUT" | The upload request must be a PUT. |
| fileStatus | FileStatus | The current status of the attached file. Supported values: "APPROVED", "REJECTED", "PROCESSING", "FAILED" |
**NewAttachment Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. This could be a Connect Email Contact ARN or a Connect Case ARN |
| fileName | string | A case-sensitive name of the attached file being uploaded. Minimum length of 1; Maximum length of 256. Supported pattern: ^\$1P\$1C\$1\$1\$1 |
| fileSizeInBytes | number | The size of the attached file in bytes. Minimum value of 1. |
| fileUseCaseType | "ATTACHMENT" | The use case for the file. Must be "ATTACHMENT" |
**Error Handling**
When beginning the process to upload attached files, agents may encounter issues. The @amazon-connect/file library provides methods to handle common errors:
+ `isInvalidFileNameError()`: Handle errors when the name of the file is not valid
+ `isInvalidFileTypeError()`: Handle errors when the file type is not supported
+ `isInvalidFileSizeError()`: Handle errors when the size of the file is invalid
+ `isTotalFileSizeExceededError()`: Handle errors when the total size of all files (being uploaded) exceeds the limit.
+ `isTotalFileCountExceededError()`: Handle errors when the total number of files (being uploaded) exceeds the limit.
**Usage**
```
import {
isInvalidFileNameError,
isInvalidFileTypeError,
isInvalidFileSizeError,
isTotalFileSizeExceededError,
isTotalFileCountExceededError
} from "@amazon-connect/file";
/* ... */
const newAttachment: NewAttachment = {
associatedResourceArn: sampleAssociatedResourceArn, // This could be an email contact ARN or case ARN that you are uploading the attached file to
fileName: sampleFileName,
fileSizeInBytes: sampleFileSizeInBytes,
fileUseCaseType: "ATTACHMENT"
};
let uploadableAttachment: UploadableAttachment;
try {
uploadableAttachment = await fileClient.startAttachedFileUpload(newAttachment);
} catch (e) {
if (isInvalidFileNameError(e)) {
// Handle InvalidFileName error
} else if (isInvalidFileTypeError(e)) {
// Handle InvalidFileType error
} else if (isInvalidFileSizeError(e)) {
// Handle InvalidFileSize error
} else if (isTotalFileSizeExceededError(e)) {
// Handle TotalFileSizeExceeded error
} else if (isTotalFileCountExceededError(e)) {
// Handle TotalFileCountExceeded error
}
}
// Assuming startAttachedFileUpload succeeded, we upload the attached file to the pre-signed S3 URL
const { uploadUrl, uploadHeaders, uploadMethod } = uploadableAttachment;
await fetch(uploadUrl, {
method: uploadMethod,
headers: uploadHeaders,
body: file, // This is the file you're uploading
});
```
# Amazon Connect Agent Workspace Message Template API
The Amazon Connect SDK provides a `MessageTemplateClient` which serves as an interface that you can use to make requests to search and get content from your Amazon Connect Message Template Knowledge Base.
The `MessageTemplateClient` 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 { MessageTemplateClient } from "@amazon-connect/message-template";
const messageTemplateClient = new MessageTemplateClient({ 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 { MessageTemplateClient } from "@amazon-connect/message-template";
const messageTemplateClient = new MessageTemplateClient({
context: sampleContext,
provider: sampleProvider
});
```
**Note**
Third-party applications must be configured with \$1 permission in order to utilize the MessageTemplateClient APIs.
The following sections describe API calls for working with the MessageTemplate API.
**Topics**
+ [getContent()](3P-apps-message-template-requests-getcontent.md)
+ [isEnabled()](3P-apps-message-template-requests-isenabled.md)
+ [searchMessageTemplates()](3P-apps-message-template-requests-searchmessagetemplates.md)
# Get content of a message template in Amazon Connect Agent Workspace
Gets the content of a message template. This includes plaintext or html content of the body of the message template as a string, the subject of the message template, and attachments if they are configured on the message template. Attributes in the message template will be filled if they are system attributes, agent attributes, or custom attributes set up in the contact flow. More information on the attributes can be found here: [ https://docs.aws.amazon.com/connect/latest/adminguide/personalize-templates.html](https://docs.aws.amazon.com/connect/latest/adminguide/personalize-templates.html)
**Signature**
```
getContent(messageTemplateId: string, contactId: string): Promise
```
**messageTemplateId**
The messageTemplateId can be either the ID or the ARN of a message template
+ Passing in the ARN returned by searchMessageTemplates is recommended here, since this will get the content of the active version of the message template.
+ Passing in the ID will return the content of the latest version of the message template. A qualifier can be appended to the messageTemplateId to get the content of a different version of the message template.
More information on qualifiers can be found here:
[ https://docs.aws.amazon.com/connect/latest/APIReference/API\$1amazon-q-connect\$1GetMessageTemplate.html](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_GetMessageTemplate.html)
More information on versioning can be found here:
[ https://docs.aws.amazon.com/connect/latest/adminguide/about-version-message-templates.html](https://docs.aws.amazon.com/connect/latest/adminguide/about-version-message-templates.html)
**contactId**
The current contact to add the message template to. This is used to populate attributes in the message template
**MessageTemplateContent Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| subject | string | Message subject populated in the template |
| body | MessageTemplateBody | Message body content populated in the template. This can include plainText or html or both |
| attachments | MessageTemplateAttachment[] | Attachments populated in the template |
| attributesNotInterpolated | string[] | List of attributes that were not automatically populated in the message template. If all attributes were automatically populated, this list will be empty |
**MessageTemplateBody Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| plainText | string | Plain text content of the message template as a string. It is possible for both the plain text and html to be populated, or for only the plain text or html content to be populated |
| html | string | HTML content of the message template as a string |
**MessageTemplateAttachment Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| fileName | string | Name of the attachment |
| fileId | string | ID of the attachment |
| downloadUrl | string | URL to download the attachment from |
# Determine if the Message Template feature is enabled in Amazon Connect Agent Workspace
Returns the MessageTemplateEnabledState object, which indicates if the message template feature is enabled for the Connect instance. The Message Template feature is considered enabled if there is a knowledge base for message templates configured for the instance. The object contains the following fields:
+ `isEnabled`: A boolean indicating if the feature is enabled
+ `knowledgeBaseId`: The id of the Message Template Knowledge Base (if the feature is enabled)
**Signature**
```
isEnabled(): Promise
```
# Retrieve message templates that match a search query in Amazon Connect Agent Workspace
Returns the SearchMessageTemplatesResponse object, which contains the matching message templates and a token to retrieve the next page of results, if available. The SearchMessageTemplatesParams object is used to configure the search, allowing you to filter by various criteria, as well as specify the channels and pagination options. If no filter text is provided, all active message templates for the agent's routing profile and the channel(s) specified are returned.
**Signature**
```
searchMessageTemplates(request: SearchMessageTemplatesParams): Promise
```
**SearchMessageTemplatesResponse Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| messageTemplate | MessageTemplate[] | List of message templates matching the search criteria specified in the request |
| nextToken | string | The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results. |
**MessageTemplate Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| messageTemplateArn | string | The ARN of the message template. This contains the active version qualifier at the end of the ARN |
| messageTemplateId | string | The ID of the message template. This does NOT contain a qualifier with the version of the message template. |
| name | string | Name of the message template |
| description | string | Description of the message template |
**SearchMessageTemplatesParams Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| channels | MessageTemplateChannel[] | The channel(s) to return message templates for. If the list is empty, no message templates will be returned. Supported values: "EMAIL" |
| queries | MessageTemplateQueryField[] | Queries are used to filter the returned message templates by name or description. Leaving the queries empty will return all message templates associated with the agent's routing profile |
| maxResults | number | Maximum number of message templates to return |
| nextToken | string | The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results. |
**MessageTemplateQueryField Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| name | "name" \$1 "description" | The message templates will be filtered by the values matching the text in the name field provided |
| values | string[] | The values of the attribute to query the message templates by |
| priority | "HIGH" \$1 "MEDIUM" \$1 "LOW" | The importance of the attribute field when calculating query result relevancy scores. The value set for this parameter affects the ordering of search results. |
| allowFuzziness | boolean | Whether the query expects only exact matches on the attribute field values. The results of the query will only include exact matches if this parameter is set to false. |
| operator | "CONTAINS" \$1 "CONTAINS\$1AND\$1PREFIX" | Include all templates that contain the values or only templates that contain the values as the prefix. |
# Amazon Connect Agent Workspace Quick Responses API
The Amazon Connect SDK provides a `QuickResponsesClient` which serves as an interface that you can use to make requests to search your Amazon Connect Quick Responses Knowledge Base.
The `QuickResponsesClient` 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 { QuickResponsesClient } from "@amazon-connect/quick-responses";
const quickResponsesClient = new QuickResponsesClient({ 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 { QuickResponsesClient } from "@amazon-connect/quick-responses";
const quickResponsesClient = new QuickResponsesClient({
context: sampleContext,
provider: sampleProvider
});
```
**Note**
Third-party applications must be configured with \$1 permission in order to utilize the QuickResponsesClient APIs.
The following sections describe API calls for working with the QuickResponses API.
**Topics**
+ [isEnabled()](3P-apps-quick-responses-requests-isenabled.md)
+ [searchQuickResponses()](3P-apps-quick-responses-requests-searchquickresponses.md)
# Determine if the Quick Responses feature is enabled in Amazon Connect Agent Workspace
Returns the QuickResponsesEnabledState object, which indicates if the quick responses feature is enabled for the Connect instance. Quick responses is considered enabled if there is a knowledge base for quick responses configured for the instance. The object contains the following fields:
+ `isEnabled`: A boolean indicating if the feature is enabled
+ `knowledgeBaseId`: The id of the Quick Responses Knowledge Base (if the feature is enabled)
**Signature**
```
isEnabled(): Promise
```
# Retrieve quick responses that match a search query in Amazon Connect Agent Workspace
Returns the SearchQuickResponsesResult object, which contains the matching quick response results and a token to retrieve the next page of results, if available. The SearchQuickResponsesRequest object is used to configure the search, allowing you to filter by various criteria, as well as specify the channels, user-defined contact attributes, and pagination options. If no queries are provided, the method will return all quick responses associated with the agent's routing profile.
**Signature**
```
searchQuickResponses(queryRequest: SearchQuickResponsesRequest): Promise
```
**SearchQuickResponsesResult Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| results | QuickResponsesSearchResultData[] | The results of the quick responses search |
| nextToken | string | The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results. |
**QuickResponsesSearchResultData Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| contents | QuickResponseContents | The contents of the quick response. |
| knowledgeBaseId | string | The identifier of the knowledge base. |
| name | string | The name of the quick response. |
| quickResponseArn | string | The Amazon Resource Name (ARN) of the quick response. |
| quickResponseId | string | The identifier of the quick response. |
| description | string | The description of the quick response. |
| shortcutKey | string | The shortcut key of the quick response. The value should be unique across the knowledge base. |
| attributesNotInterpolated | string[] | The user defined contact attributes that are not resolved when the search result is returned. |
**QuickResponseContents Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| markdown | string | The content of the quick response stored in markdown |
| plainText | string | The content of the quick response stored in plain text |
**SearchQuickResponsesRequest Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| queries | QuickResponsesQuery[] | Query used to filter quick responses; if no queries are provided, the client will return all quick responses associated with the agent's routing profile. |
| channels | QuickResponseChannel[] | The channels to filter the request by. Supported values: "Chat" or "Email" |
| attributes | Record | The user-defined Amazon Connect contact attributes to be resolved when search results are returned. |
| debounceMS | number | The default value is set to 250ms; set it to 0 to disable debounced input change |
| maxResults | number | The number of results to be returned. Minimum value of 1. Maximum value of 100. |
| nextToken | string | The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results. |
**QuickResponsesQuery Properties**
| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| name | QuickResponsesQueryFieldName | The name of the attribute to query the quick responses by. Supported values: "content", "name", "description", or "shortcutKey" |
| values | string[] | The values of the attribute to query the quick responses by. |
| operator | QuickResponsesQueryOperator | The operator to use for matching attribute field values in the query. Supported values: "CONTAINS" or "CONTAINS\$1AND\$1PREFIX" |
| priority | QuickResponsesQueryPriority | The importance of the attribute field when calculating query result relevancy scores. The value set for this parameter affects the ordering of search results. Supported values: "HIGH", "MEDIUM", or "LOW" |
| allowFuzziness | boolean | Whether the query expects only exact matches on the attribute field values. The results of the query will only include exact matches if this parameter is set to false. |
# Amazon Connect Agent Workspace User API
The Amazon Connect SDK provides an `SettingsClient` which serves as an interface that your app in Amazon Connect Agent Workspace can use to make data requests on user settings.
The `SettingsClient` 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 { SettingsClient } from "@amazon-connect/user";
const settingsClient = new SettingsClient({ 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 { SettingsClient } from "@amazon-connect/user";
const settingsClient = new SettingsClient({
context: sampleContext,
provider: sampleProvider
});
```
The following sections describe API calls for working with the User API.
**Topics**
+ [getLanguage()](3P-apps-user-requests-getlanguage.md)
+ [onLanguageChanged()](3P-apps-user-events-languagechanged-sub.md)
+ [offLanguageChanged()](3P-apps-user-events-languagechanged-unsub.md)
# Get the language of a user in Amazon Connect Agent Workspace
Returns the language setting for the current user in the Amazon Connect Agent Workspace.
```
async getLanguage(): Promise
```
**Permissions required:**
```
User.Configuration.View
```
# Subscribe a callback function when an Amazon Connect Agent Workspace user changes languages
Subscribes a callback function to-be-invoked whenever a user LanguageChanged event occurs in the Amazon Connect Agent Workspace.
**Signature**
```
onLanguageChanged(handler: UserLanguageChangedHandler)
```
**Usage**
```
const handler: UserLanguageChangedHandler = async (data: UserLanguageChanged) => {
console.log("User LanguageChange occurred! " + data);
};
settingsClient.onLanguageChanged(handler);
// UserLanguageChanged Structure
{
language: string;
previous: {
language: string;
};
}
```
**Permissions required:**
```
User.Configuration.View
```
# Unsubscribe a callback function when an Amazon Connect Agent Workspace user changes languages
Unsubscribes the callback function from LanguageChanged event in the Amazon Connect Agent Workspace.
**Signature**
```
offLanguageChanged(handler: UserLanguageChangedHandler)
```
**Usage**
```
settingsClient.offLanguageChanged(handler);
```
# Amazon Connect Agent Workspace Voice API
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
Checks whether a specific participant can be resumed from hold.
**Signature**
```
canResumeParticipant(participantId: string): Promise
```
**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
Checks whether the current user's participant can be resumed from hold for a specific contact.
**Signature**
```
canResumeSelf(contactId: string): Promise
```
**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
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
```
**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
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
```
**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
Gets the phone number of the initial customer connection. Applicable only for voice contacts.
**Signature**
```
getInitialCustomerPhoneNumber(contactId: string): Promise
```
**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
Gets true if the agent has the security profile permission for making outbound calls, false otherwise.
**Signature**
```
getOutboundCallPermission(): Promise
```
**Usage**
```
const outboundCallPermission: boolean = await voiceClient.getOutboundCallPermission();
```
**Permissions required:**
```
User.Configuration.View
```
# Place a participant on hold in Amazon Connect Agent Workspace
Places a specific participant on hold.
**Signature**
```
holdParticipant(participantId: string): Promise
```
**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
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
```
**Usage**
```
const voiceEnhancementMode: VoiceEnhancementMode = await voiceClient.getVoiceEnhancementMode();
```
**Permissions required:**
```
*
```
# Get voice enhancement model paths in Amazon Connect Agent Workspace
Returns the voice enhancements models static assets URL paths.
**Signature**
```
async getVoiceEnhancementPaths(): Promise
```
**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
Checks whether a specific participant is currently on hold.
**Signature**
```
isParticipantOnHold(participantId: string): Promise
```
**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
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
```
**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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Resumes a specific participant from hold.
**Signature**
```
resumeParticipant(participantId: string): Promise
```
**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
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
```
**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:**
```
*
```