# Set up your contact center in Amazon Connect
Set up your contact center
To get started, you [create an Amazon Connect instance](amazon-connect-instances.md), which is your a virtual contact center.
After you create an Amazon Connect instance, you can:
+ [Test](chat-testing.md) the voice and chat experiences to learn how they work.
+ [Set up your channels](set-channels.md). How do you want customers to reach your contact center?
+ [Claim a phone number](ag-overview-numbers.md) for your contact center or [port](about-porting.md) your own phone number from another carrier.
+ [Set up the customer's chat experience](enable-chat-in-app.md). Developer skills are required.
+ [Set up SMS (text) messaging](setup-sms-messaging.md).
+ [Set up in-app, web, and video calling](inapp-calling.md) capabilities.
+ [Set up tasks](concepts-getting-started-tasks.md).
+ [Enable outbound calling](enable-outbound-calls.md), and set your [outbound caller ID](queues-callerid.md).
+ [Add](user-management.md) agents and other users.
+ Review this [list](security-profile-list.md) of security profile permissions, and then [assign](assign-security-profile.md) security profile permissions to users so they can access those parts of Amazon Connect that are appropriate to their roles.
+ [Set up routing](connect-queues.md). You can create a single queue for incoming contacts, or set up multiple queues so that you can route contacts to agents with specific skills.
+ Use the [default flows](contact-flow-default.md) that come with Amazon Connect or [create](create-contact-flow.md#create-inbound-contact-flow) your own flows to define how your customers experience your contact center.
+ Provide your agents with [access](amazon-connect-contact-control-panel.md) to the Contact Control Panel (CCP), which they will use to interact with contacts.
The topics in this section explain how to do these steps.
**Topics**
+ [Amazon Connect pricing](enable-nextgeneration-amazonconnect.md)
+ [Create an Amazon Connect instance](amazon-connect-instances.md)
+ [
# Test voice, chat, and task experiences in Amazon Connect
](chat-testing.md)
+ [Set up your channels](set-channels.md)
+ [Set up outbound calling](outbound-communications.md)
+ [Add users](manage-users.md)
+ [Set up routing](connect-queues.md)
+ [Set up agents](connect-agents.md)
+ [Provide access to the CCP](amazon-connect-contact-control-panel.md)
# Amazon Connect pricing
Amazon Connect pricing
Amazon Connect is an AI-powered contact center solution that turns every customer touchpoint into a deeper relationship and better outcome.
When you create an Amazon Connect instance, unlimited AI pricing is enabled.
Amazon Connect unlimited AI pricing provides unlimited use of Amazon Connect AI capabilities that power customer self-service, agent assistance, and supervisor experiences. It allows you to optimize every step of your customer journey without cost-driven compromises.
For more information, visit [Amazon Connect Pricing](https://aws.amazon.com/connect/pricing/).
**Topics**
+ [
## How Amazon Connect billing works
](#how-ac-billing-works)
+ [
## Amazon Connect pricing options
](#bestpractices-ac-billing)
+ [
## How to disable unlimited AI pricing
](#how-to-disable-ac)
+ [
## How to enable unlimited AI pricing
](#how-to-enable-ac)
## How Amazon Connect billing works
How Amazon Connect billing works
Amazon Connect is a pay-as-you-go customer experience solution that makes it simple to leverage native AI in every touchpoint across all channels. There are no required minimum monthly fees, long-term commitments, or upfront license charges, and pricing is not based on peak capacity, agent seats, or maintenance; you only pay for what you use. This flexible pricing model enables you to scale up and down depending on seasonality and the needs of your business, without worrying about capacity constraints or licensing costs.
For global resiliency pricing, contact your AWS Technical Account Manager or Solutions Architect.
## Amazon Connect pricing options
Amazon Connect pricing options
There are two pricing models available: unlimited AI pricing and per feature pricing. You can select a different pricing model for each Amazon Connect instance and change that selection at any time, giving you the flexibility to choose the option that best suits your needs.
**Unlimited AI pricing** is the default option. It enables you to use an all-inclusive channel pricing model that covers all optimization features, including:
+ Conversational analytics
+ Performance evaluations
+ Screen recording
+ Agent scheduling tools
+ AI-powered voice and chat through Amazon Lex and Connect AI agents
+ AI-powered generative voice for text-to-speech (TTS) in Amazon Connect
**Note**
We recommend reviewing [Service Improvement and how to opt out from using your data for service improvement](data-opt-out.md) to learn which Amazon Connect services use your customer's data to train machine learning models, and how you can opt out.
- OR -
**Per feature pricing** where you pay separately for channels and any optimization features you choose to use.
## How to disable unlimited AI pricing
How to disable unlimited AI pricing
Complete the following steps to disable unlimited AI pricing and instead use per feature pricing for a given Amazon Connect instance.
1. Log in to the AWS Management Console using your AWS account.
1. In the AWS Management Console, in the search box, type **Amazon Connect**. Choose **Amazon Connect**.
1. On the **Amazon Connect virtual contact center instances** page, choose the **instance alias** where you want to disable unlimited AI pricing.
1. In the navigation pane, choose **Amazon Connect**.
1. In the **Enable unlimited AI pricing across your entire contact center** section, confirm the status is **enabled**.
1. Choose **Disable**.
A dialog box appears prompting you to confirm that you want to disable unlimited AI pricing and instead use the per feature pricing model. Choose **Disable** to confirm.
**Warning**
Disabling unlimited AI pricing will not disable the individual features used. If those features continue to be used after unlimited AI pricing is disabled, you will be charged based on each individual feature's price.
Exception: If you are using the [customer first callback](setup-queued-cb.md) feature, it is disabled when you choose to disable unlimited AI pricing.
## How to enable unlimited AI pricing
How to enable unlimited AI pricing
If you have disabled unlimited AI pricing and want to enable again, or you created your Amazon Connect before this option was released, here's how you can enable it now. Also use these steps if you want to verify if unlimited AI pricing is enabled.
Complete the following steps to enable unlimited AI pricing for a given Amazon Connect instance.
1. Log in to the AWS Management Console using your AWS account.
1. In the AWS Management Console, in the search box, type **Amazon Connect**. Choose **Amazon Connect**.
1. On the **Amazon Connect virtual contact center instances** page, choose the **instance alias** where you want to enable unlimited AI pricing.
1. In the navigation pane, choose **Amazon Connect**.
1. In the **Enable unlimited AI pricing across your entire contact center** section, confirm the status is **Not enabled**.
1. Choose **Enable**.
**Warning**
When you enable unlimited AI, any active free trials of Amazon Connect features end, such as free trials of conversational analytics, performance evaluation, and agent scheduling.
# Create an Amazon Connect instance
Create an Amazon Connect instance
The first step in setting up your Amazon Connect contact center is to create a virtual contact center instance. Each instance contains all the resources and settings related to your contact center.
## Things to know before you begin
+ When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS, including Amazon Connect. You are charged only for the services that you use. To create an AWS account, see [How/ do I create and activate an AWS account?](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/)
+ To allow a user to create an instance, ensure that they have the permissions granted by the **AmazonConnect\$1FullAccess** policy.
+ For a list of the minimum IAM permissions required to create an instance, see [Required permissions for using custom IAM policies to manage access to the Amazon Connect console](security-iam-amazon-connect-permissions.md).
+ By default when you create an Amazon Connect instance, Next Generation Amazon Connect is enabled. It's pricing model includes unlimited AI features in Amazon Connect. It's an all-inclusive channel pricing model that covers all optimization features for usage on your platform.
After you initially create your Amazon Connect instance, you can choose to disable this option and instead pay separately for channels and any optimization features you choose to use. For more information, see [Amazon Connect pricing](enable-nextgeneration-amazonconnect.md).
+ Amazon Connect is not available to customers in India using Amazon Web Services through Amazon Web Services India Private Limited (AWS India). You will receive an error message if you try to create an instance in Amazon Connect.
+ When you create an instance, you must decide how you want to manage users. **You can't change the identity management option after you create the instance**. For more information, see [Plan your identity management in Amazon Connect](connect-identity-management.md).
## Step 1: Set identity
Permissions to access Amazon Connect features and resource are assigned to user accounts within Amazon Connect. When you create an instance, you must decide how you want to manage users. You can't change the identity management option after you create the instance. For more information, see [Plan your identity management in Amazon Connect](connect-identity-management.md).
**To configure identity management for your instance**
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. Choose **Get started**. If you have previously created an instance, choose **Add an instance** instead.
1. Choose one of the following options:
+ **Store users in Amazon Connect** - Use Amazon Connect to create and manage user accounts. You cannot share users with other applications.
+ **Link to an existing directory** - Use an Directory Service directory to manage your users. You can use each directory with one Amazon Connect instance at a time.
+ **SAML 2.0-based authentication** - Use an existing identity provider (IdP) to federate users with Amazon Connect.
1. If you chose **Store users within Amazon Connect** or **SAML 2.0-based authentication**, provide the left-most label for **Access URL**. This label must be unique across all Amazon Connect instances in all Regions. You can't change the access URL after you create your instance.
1. If you chose **Link to an existing directory**, select the Directory Service directory for **Directory**. The directory name is used as the left-most label for **Access URL**.
1. Choose **Next**.
## Step 2: Add administrator
After you specify the user name of the administrator for the Amazon Connect instance, a user account is created in Amazon Connect and the user is assigned the **Admin** security profile.
**To specify the administrator for your instance (Optional)**
1. Do one of the following, based on the option that you chose in the previous step:
+ If you chose **Store users within Amazon Connect**, select **Specify an administrator**, and provide a name, password, and email address for the user account in Amazon Connect.
+ If you chose **Link to an existing directory**, for **Username**, type the name of an existing user in the Directory Service directory. The password for this user is managed through the directory.
+ If you chose **SAML 2.0-based authentication**, select **Add a new admin** and provide a name for the user account in Amazon Connect. The password for this user is managed through the IdP.
1. You can also select **No administrator** if an administrator is not needed for your instance.
1. (Optional) Add tags to your instance. For more information see [Tagging an Amazon Connect instance](tagging-connect-instance.md).
1. Choose **Next**.
## Step 3: Set telephony
Use the options in this section to choose whether you want your agents to receive calls from customers, make outbound calls, and hear early media audio.
### Early media
When early media audio is enabled, for outbound calls your agents can hear pre-connection audio such as busy signals, failure-to-connect errors, or other informational messages provided by telephony providers.
**Note**
The early media feature is not supported for transfers that are dialed through the [Transfer to phone number](transfer-to-phone-number.md) block in flows.
**By default, early media is enabled for you. Note the following exception:**
+ Your instance was created before April 17, 2020, and you weren't enrolled in the preview program. You need to enable early media audio. For instructions, see [Update telephony and chat options](update-instance-settings.md#update-telephony-options).
**To configure telephony options for your instance**
1. To allow inbound calls to your contact center, choose **Receive inbound calls with Amazon Connect**.
1. To enable outbound calling from your contact center, choose **Make outbound calls with Amazon Connect**.
1. To enable agents to hear pre-connection audio, choose **Enable early media**.
1. To enable up to six participants on a call, choose **Enable Multi-Party Calls and Enhanced Monitoring for Voice**.
1. To enable up to six participants on a chat, choose **Enable Multi-Party Chats and Enhanced Monitoring for Chat**.
1. Choose **Next**.
## Step 4: Data storage
**Note**
Amazon Connect does not support Amazon S3 Object Lock in compliance mode to store objects using a write-once-read-many (WORM) model.
When you create an instance, by default we create an Amazon S3 bucket. Data, such as reports and recordings of conversations, is encrypted using AWS Key Management Service, and then stored in the Amazon S3 bucket.
This bucket and key are used for both recordings of conversations and exported reports. Alternatively, you can specify separate buckets and keys for recordings of conversations and exported reports. For instructions, see [Update settings for your Amazon Connect instance](update-instance-settings.md).
**Note**
For voice artifacts (analysis files and redacted audio), Contact Lens uses the recording key. For chat artifacts (analysis files), it uses the chat recording key.
**By default, Amazon Connect creates buckets for storing call recordings, chat transcripts, exported reports, flow logs, and email messages. **
+ When a bucket is created to store call recordings, call recording is enabled at the instance level. The next step for setting up this functionality is to [enable contact recording](set-up-recordings.md) in a flow.
+ When a bucket is created to store chat transcripts, chat transcription is enabled at the instance level. Now all chat transcripts will be stored.
+ When a bucket is created to store email messages, a default Amazon Connect email domain is created for your instance. This email domain cannot be customized. After your Amazon Connect instance is created, you can add up to five custom email domains that have been onboarded to Amazon SES. For more information, see [Enable email for your Amazon Connect instance](enable-email1.md).
**Important**
If you choose **Enable Attachments sharing** for your instance, you must configure a CORS policy on your attachments bucket. If you don't do this, the email channel will not work for your instance. For instructions, see [Step 5: Configure a CORS policy on your attachments bucket](enable-email1.md#config-email-attachments-cors1).
+ Live media streaming is not enabled by default.
+ Screen recording is not enabled by default. For more information, see [Enable screen recording for your Amazon Connect instance](enable-sr.md).
**By default, Amazon Connect creates a Customer Profiles domain**, which stores profiles that combine customer contact history with customer information such as account number, address, billing address, and birth date. Data is encrypted using AWS Key Management Service. You can configure Customer Profiles to use your own customer managed key after your instance is set up. For more information, see [Create a KMS key to be used by Customer Profiles to encrypt data (required)](enable-customer-profiles.md#enable-customer-profiles-awsmanagedkey).
**Review and copy the location of the S3 bucket, flow logs, and whether you want to enable Customer Profiles.**
1. If desired, copy the location of the S3 bucket where your data encryption is stored, and the location of the flow logs in CloudWatch.
1. Choose **Next**.
## Step 5: Review and create
**To create your instance**
1. Review the configuration choices. Remember that you cannot change the identity management options after you create the instance.
1. (Optional) To change any of the configuration options, choose **Edit**.
1. (Optional) Add tags to your instance. For more information see [Tagging an Amazon Connect instance](tagging-connect-instance.md).
1. Choose **Create instance**.
1. (Optional) To continue configuring your instance, choose **Get started** and then choose **Let's go**. If you prefer, you can access your instance and configure it later on. For more information, see [Next steps](#get-started-next-steps).
If you chose to manage your users directly within Amazon Connect or through an Directory Service directory, you can access the instance using its access URL. If you chose to manage your users through SAML-based authentication, you can access the instance using the IdP.
**Important**
Next Generation Amazon Connect is now enabled. It provides Amazon Connect with unlimited AI features in an all-inclusive pricing model. To switch to paying separately for channels and any optimization features you choose, [disable Next Generation Amazon Connect](enable-nextgeneration-amazonconnect.md#how-to-disable-ac).
## Next steps
After you create an instance, you can assign your contact center a phone number or import your own phone number. For more information, see [Set up contact center phone numbers for your Amazon Connect instance](ag-overview-numbers.md).
# Create a development or test instance for your Amazon Connect contact center
Create a test instance
You might want to create multiple contact center instances, for example, one as a Sandbox for development, another for QA, and a third for Production.
Each instance functions only within the AWS Region in which you create it.
**Important**
Most entities in Amazon Connect can be (re)created and replicated among instances using the Amazon Connect API. While doing that keep the following limitations in mind:
Service quotas are specific to each instance.
Some supporting services, such as User Directory, can be linked to only one Amazon Connect instance at a time.
Any additional external and Region-specific limitations.
For more information, see [Can I migrate my Amazon Connect instance from a test environment to a production environment?](https://aws.amazon.com/premiumsupport/knowledge-center/connect-migrate-instance-resources/)
**To create another instance**
1. In the AWS Management Console, choose **Amazon Connect**.
1. Choose **Add an instance**.
1. Complete the steps on the Amazon Connect resource configuration page. For instructions see [Create an Amazon Connect instance](amazon-connect-instances.md).
# Find your Amazon Connect instance ID or ARN
Find your instance ID
When you open a support ticket, you may be asked to provide your Amazon Connect instance ID (also called the ARN). Use the following steps to find it.
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
On the **Account overview** page, in the **Distribution settings** section, you can see the full instance ARN.
![\[The Distribution settings section, the full ARN.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/find-instance-arn.png)
The information after **instance/** is the instance ID.
![\[The characters after the last /.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/find-instance-id.png)
If you don't see your instance listed, double-check that you're looking in the correct Region, as shown in the following image. For a list of supported Regions, see [Amazon Connect availability by Region](regions.md#amazonconnect_region).
![\[The Region dropdown list.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/supported-regions.png)
# Find your Amazon Connect instance name
Find your instance name/alias
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, the instance name appears in the **Instance Alias** column. This instance name appears in the URL you use to access Amazon Connect.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
# Update settings for your Amazon Connect instance
To update the instance settings:
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. Complete the following procedures.
## Update telephony and chat options
1. In the navigation pane, choose **Telephony**. This opens the **Telephony and chat** options page.
1. To enable customers to call into your contact center, choose **Receive inbound calls with Amazon Connect**.
1. To enable outbound calling from your contact center, choose **Make outbound calls with Amazon Connect**.
1. To enable outbound campaigns, choose **Enable outbound campaigns**.
1. By enabling early media audio, your agents can hear pre-connection audio such as busy signals, failure-to-connect errors, or other informational messages from telephony providers, when making outbound calls. Choose **Enable early media**.
**Note**
The early media feature is not supported for transfers that are dialed through the [Transfer to phone number](transfer-to-phone-number.md) block in flows.
1. By default, you can have three participants on a voice call (for example, two agents and a customer, or an agent, a customer, and an external party). You [enable this default three-party](enable-three-party-monitoring.md) capability by adding and configuring a **Set recording and analytics behavior** block to your flow.
However, instead of adding the block, you can choose the following options to allow more participants on a voice or chat contact, provide your agents with an enhanced conferencing experience, and allow supervisors to barge in:
+ **Enable Multi-Party Calls and Enhanced Monitoring for Voice**. Choose this option to enable the barge capabilities. This feature is only available in CCPv2. For more information about this capability, see [Enable enhanced multi-party contact monitoring](monitor-conversations.md).
+ **Enable Multi-Party Chats and Enhanced Monitoring for Chat**. Choose this option to enable up to six participants on chats, and to barge chats.
For a comparison of how the agents' experience differs between the default three-party and the enhanced multi-party capabilities, see [Comparison of multi-party and three-party functionality](three-party-multi-party-comparison.md).
**Important**
If you enabled chat barge-in before the release of multi-party chats in December 2024, you need to toggle this setting off and then on to enable multi-party chats.
For more information, see [Barge into live voice and chat conversations between contact center agents and customers](monitor-barge.md).
1. Choose **Save**.
## Update data storage
+ In the navigation pane, choose **Data storage**. Choose the following:
+ **Call recordings**: Choose **Edit**, specify the bucket and KMS key for recordings of voice conversations, and then choose **Save**.
When this bucket is created, call recording is enabled at the instance level. The next step for setting up this functionality is to [set up recording behavior in a flow](set-up-recordings.md).
+ **Chat transcripts**: Choose **Edit**, specify the bucket and KMS key for recordings (transcripts) of chat conversations, and then choose **Save**.
When this bucket is created, chat transcripts are enabled at the instance level. Now all chat transcripts will be stored here.
+ **Live media streaming**: Choose **Edit** to enable live media streaming, choose **Edit**. For more information, see [Set up live media streaming of customer audio in Amazon Connect](customer-voice-streams.md).
+ **Exported reports**: Choose **Edit**, specify the bucket and KMS key for exported reports, and then choose **Save**.
+ **Attachments**: Choose **Edit**, then **Enable Attachments sharing** to enable file sharing for both agents and customers. For more information about this option and additional steps, see [Enable attachments in your CCP so customers and agents can share and upload files](enable-attachments.md).
**Important**
If you choose **Enable Attachments sharing** for your instance, you must configure a CORS policy on your attachments bucket. If you don't do this, the email channel will not work for your instance. For instructions, see [Step 5: Configure a CORS policy on your attachments bucket](enable-email1.md#config-email-attachments-cors1).
+ **Contact evaluations**: Choose **Edit**, specify the bucket and KMS key for performance evaluations, and then choose **Save**.
When this bucket is created, evaluations are enabled at the instance level. The next step for setting up this feature is to [create an evaluation form](create-evaluation-forms.md).
+ **Screen recordings**: Choose **Edit**, specify the bucket and KMS key for recordings of agent screens, and then choose **Save**.
When this bucket is created, screen recording is enabled at the instance level. The next step for setting up this functionality is to download and install the agent app, and then enable screen recording in the Set recording and analytics behavior block. For more information, see [Enable screen recording for your Amazon Connect instance](enable-sr.md).
+ **Email messages**: Choose **Edit**, specify the bucket and KMS key for email messages, and then choose **Save**.
When this bucket is created, the email channel is enabled at the instance level.
**Important**
If you choose **Enable Attachments sharing** for your instance, you must configure a CORS policy on your attachments bucket. If you don't do this, the email channel will not work for your instance. For instructions, see [Step 5: Configure a CORS policy on your attachments bucket](enable-email1.md#config-email-attachments-cors1).
## Update data streaming options
1. In the navigation pane, choose **Data streaming**.
1. Choose **Enable data streaming**. For more information, see [Enable data streaming for your Amazon Connect instance](data-streaming.md).
1. For **Contact records**, do one of the following:
+ Choose **Kinesis Firehose** and select an existing delivery stream, or choose **Create a new Kinesis Firehose** to open the Kinesis Firehose console and create the delivery stream.
+ Choose **Kinesis Stream** and select an existing stream, or choose **Create a new Kinesis Firehose** to open the Kinesis console and create the stream.
1. For **Agent Events**, select an existing Kinesis stream or choose **Create a new Kinesis Stream** to open the Kinesis console and create the stream.
1. Choose **Save**.
## Update analytics tools options
1. In the navigation pane, choose **Analytics tools**.
1. Choose **Enable Contact Lens**. For more information, see [Analyze conversations using conversational analytics in Amazon Connect Contact Lens](analyze-conversations.md).
1. Choose **Save**.
## Update flow settings
1. In the navigation pane, choose **Flows**.
1. (Optional) To add a signing key for use in flows, choose **Add key**. For more information, see [Encrypt sensitive customer input in Amazon Connect](encrypt-data.md).
1. (Optional) To integrate with Amazon Lex, select a Lex bot. For more information, see [Create conversational AI bots in Amazon Connect](connect-conversational-ai-bots.md).
1. (Optional) To integrate with AWS Lambda, select a Lambda function. For more information, see [Grant Amazon Connect access to your AWS Lambda functions](connect-lambda-functions.md).
1. (Optional) To enable flow logs, choose **Enable flow logs**. For more information, see [Use flow logs to track events in Amazon Connect flows](about-contact-flow-logs.md).
1. (Optional) To use the best available voice from Amazon Polly, choose **Use the best available voice**. For more information, see [Amazon Polly best sounding voice](text-to-speech.md#amazon-polly-best-sounding-voice).
1. (Optional) Use the voices available in Amazon Polly.
1. (Optional) To enables logs of automated interactions using IVR and Lex bot transcripts and analytics as a part of your Contact details page and Connect analytics dashboards, you need to select **Enable Bot Analytics and Transcripts in Amazon Connect**.
# Enable attachments in your CCP so customers and agents can share and upload files
Enable attachments to share files
You can allow customers and agents to share files using chat and email, and allow agents to upload files to cases. After you complete the steps in this topic, an attachment icon automatically appears in your agent's Contact Control Panel so they can share attachments on chats and emails.
**Important**
You must complete steps 1 and 2 in this topic (create an Amazon S3 bucket and configure a CORS policy) for email attachments. If you don't do this, yet have selected **Enable Attachments sharing** for your instance, the email channel will not work for your instance.
For a list of supported file types, see [Amazon Connect feature specifications](feature-limits.md).
If you are not using the hosted communications widget, you need to update your customer-facing chat interfaces to support attachment sharing.
**Using a custom chat application?** Check out the APIs we've added to support attachment sharing: [StartAttachmentUpload](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_StartAttachmentUpload.html), [CompleteAttachmentUpload](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CompleteAttachmentUpload.html), and [GetAttachment](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetAttachment.html).
**Using a custom agent application?** Check out the attached file APIs: [StartAttachedFileUpload](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartAttachedFileUpload.html), [CompleteAttachedFileUpload](https://docs.aws.amazon.com/connect/latest/APIReference/API_CompleteAttachedFileUpload.html), and [GetAttachedFile](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetAttachedFile.html), [BatchGetAttachedFileMetadata](https://docs.aws.amazon.com/connect/latest/APIReference/API_BatchGetAttachedFileMetadata.html), and [DeleteAttachedFile](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeleteAttachedFile.html).
## Step 1: Enable attachments
Step 1: Enable attachments
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. On the **Data storage** page, under the **Attachments**, choose **Edit**, select **Enable Attachments sharing**, and then choose **Save**.
Storage options appear, similar to the following image.
![\[The attachment section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/attachments-enable.png)
1. You can change the Amazon S3 bucket location where attachments are stored. By default, your existing Amazon Connect bucket is used, with a new prefix for attachments.
**Note**
Currently, Amazon Connect doesn’t support S3 buckets with [Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) enabled.
The attachments feature leverages two Amazon S3 locations: a staging location and a final location.
Note the following about the staging location:
+ The staging location is used as part of a business validation flow. Amazon Connect uses it to validate the file size and type before it is available for download by using the `GetAttachedFile` or `GetAttachment` APIs.
+ The staging prefix is created by Amazon Connect based on the bucket path you have selected. Specifically, it includes the S3 prefix for where you are saving files, with **staging** appended to it.
+ We recommend that you change the data retention policy for the staging prefix to one day. This way you won't be charged for storing the staging files. For instructions, see [How do I create a lifecycle rule for an S3 bucket?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-lifecycle.html) in the *Amazon S3 User Guide*.
**Warning**
Only change the lifecycle for the **file staging location**. If you accidentally change the lifecycle for the entire Amazon S3 bucket, all transcripts and attachments will be deleted.
S3 objects are **permanently deleted** if S3 bucket versioning is not enabled.
## Step 2: Configure a CORS policy on your attachments bucket
Step 2: Configure a CORS policy
To allow customers and agents to upload and download files, update your cross-origin resource sharing (CORS) policy to allow `PUT` and `GET` requests for the Amazon S3 bucket you are using for attachments. This is more secure than enabling public read/write on your Amazon S3 bucket, which we don't recommend.
**To configure CORS on the attachments bucket**
1. Find the name of the Amazon S3 bucket for storing attachments:
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. In the Amazon Connect console, choose **Data storage**, and locate the Amazon S3 bucket name.
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. In the Amazon S3 console, select your Amazon S3 bucket.
1. Choose the **Permissions** tab, and then scroll down to the **Cross-origin resource sharing (CORS)** section.
1. Add a CORS policy that has one of the following rules on your attachments bucket. For example CORS policies, see [Cross-origin resource sharing: Use-case scenarios](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html#example-scenarios-cors) in the *Amazon S3 Developer Guide*.
+ Option 1: List the endpoints from where attachments will be sent and received, such as the name of your business web site. This rule allows cross-origin PUT and GET requests from your website (for example, http://www.example1.com).
Your CORS policy may look similar to the following example:
```
[
{
"AllowedMethods": [
"PUT",
"GET"
],
"AllowedOrigins": [
"http://www.example1.com",
"http://www.example2.com"
],
"AllowedHeaders": [
"*"
]
}
]
```
+ Option 2: Add the `*` wildcard to `AllowedOrigin`. This rule allows cross-origin PUT and GET requests from all origins, so you don't have to list your endpoints.
Your CORS policy may look similar to the following example:
```
[
{
"AllowedMethods": [
"PUT",
"GET"
],
"AllowedOrigins": [
"*"
],
"AllowedHeaders": [
"*"
]
}
]
```
## Step 3 (Optional): Integrate with the APIs to enhance your custom UIs
Step 3 (Optional): Integrate with the APIs to enhance your custom UIs
If you are skipping the out-of-the-box Chat UI or Agent workspace, you can use the Amazon Connect Participant attachments APIs, or Amazon Connect attached files APIs to build your own UIs and provide attachments support for Cases and Chats. For the general steps in working with both sets of APIs, see [Working with attachments](https://docs.aws.amazon.com/connect/latest/APIReference/working-with-acps-api).
## Next step
Next step
We recommend enabling attachment scanning to meet compliance requirements or security policies that your organization may have in place for file sharing. For more information, see [Set up attachment scanning in Amazon Connect](setup-attachment-scanning.md).
## Attachments not appearing?
Attachments not appearing?
If your agents report problems receiving and sending attachments in chat messages, see [Internal firewall or missing CORS policy prevents access to chat, email, or case attachments](ts-agent-attachments.md).
# Set up attachment scanning in Amazon Connect
Set up attachment scanning
**Note**
This topic is for developers who are familiar with Lambda. If you're new to Lambda, see [Getting started with Lambda](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) in the AWS *Lambda Developer's Guide*.
You can configure Amazon Connect to scan attachments that are sent in email, during a chat, or uploaded to a case. You can scan attachments by using your preferred scanning application. For example, you can scan attachments for malware before they are approved to be shared between participants of a chat.
To enable attachment scanning you perform two steps:
+ [Configure a Lambda function that calls your preferred scanning application](#lambda-scanning).
+ [Add the scanner to your Amazon Connect instance](#add-attachment-scanner).
## Step 1: Create a Lambda function that handles scanning
Step 1: Create a Lambda function that handles scanning
Create a Lambda function, using any runtime, and configure it. This function must be in the same AWS Region and account as your Amazon Connect instance.
For every attachment uploaded through Amazon Connect a request is sent with information about the attachment.
Following is an example JSON request for scanning:
```
{
"Version": "1.0",
"InstanceId": "your instance ID",
"File": {
"FileId": "your file ID",
"FileCreationTime": 1689291663582,
"FileName": "example.txt",
"FileSizeInBytes": 10,
"FileLocation": {
"S3Location": {
"Key": "connect/your-instance/Attachments/chat/2023/07/13/your file ID_20230713T23:41_UTC.txt",
"Bucket": "connect-example",
"Arn": "arn:aws:s3:::connect-example/connect/your-instance/Attachments/chat/2023/07/13/your file ID_20230713T23:41_UTC.txt"
}
}
}
}
```
### Required response
```
{
"Status": "APPROVED" | "REJECTED"
}
```
### Invocation retry policy
If your Lambda invocation gets throttled, the request is retried. It is also retried if a general service failure (500 error) happens. When a synchronous invocation returns an error, Amazon Connect retries up to 3 times, for a maximum of 60 seconds. At that point, the attachment is marked rejected.
For more information about how Lambda retries, see [Error handling and automatic retries in AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/invocation-retries.html).
### Rejection behavior
Amazon Connect marks the attachment `REJECTED` and automatically deletes attachment files in S3 from both staging and final locations when one of the following occurs:
+ Your Lambda scanner returns a status of `REJECTED`.
+ Amazon Connect is unable to parse the response from the Lambda scanner.
+ Amazon Connect is unable to invoke the Lambda function.
## Step 2: Add an attachment scanner to your Amazon Connect instance
Step 2: Add an attachment scanner to your Amazon Connect instance
After you create a Lambda for attachment scanning, you need to add the Lambda to your Amazon Connect instance. Perform the following steps to add the Lambda.
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. In the navigation pane, choose **Data storage**.
1. On the **Data storage** page, in the **Attachments** section, choose **Edit**, and then select **Enable attachments scanning**, as shown in the following image.
![\[The attachments page, the enable attachments scanning option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/scanner.png)
1. Use the **Lambda Functions** drop-down box to select the Lambda function that you added in [Step 1: Create a Lambda function that handles scanning](#lambda-scanning).
1. Choose **Save**. Attachment scanning is now enabled for your Amazon Connect instance.
# Enable data streaming for your Amazon Connect instance
Enable data streaming
You can export contact records and agent events from Amazon Connect and perform real-time analysis on contacts. Data streaming sends data to Amazon Kinesis.
**To enable data streaming for your instance**
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. In the navigation pane, choose **Data streaming**.
1. Choose **Enable data streaming**.
1. For **Contact records**, do one of the following:
+ Choose **Kinesis Firehose** and select an existing delivery stream, or choose **Create a new Kinesis firehose** to open the Kinesis Firehose console and create the delivery stream. For more information, see [Creating an Amazon Data Firehose Delivery Stream](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html).
+ Choose **Kinesis Stream** and select an existing stream, or choose **Create a Kinesis stream** to open the Kinesis console and create the stream. For more information, see [Creating and Managing Streams](https://docs.aws.amazon.com/streams/latest/dev/working-with-streams.html).
1. For **Agent Events**, select an existing Kinesis stream or choose **Create a new Kinesis stream** to open the Kinesis console and create the stream.
1. Choose **Save**.
## Use server-side encryption for the Kinesis stream
Amazon Connect supports streaming to Amazon Kinesis Data Streams and Firehose streams that have server-side encryption with a [customer managed key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-mgmt) enabled. For a general overview of this feature, see [What Is Server-Side Encryption for Kinesis Data Streams?](https://docs.aws.amazon.com/streams/latest/dev/what-is-sse.html)
To stream to Kinesis Data Streams, you need to grant your Amazon Connect instance permission to use a customer managed key. For details on the permissions needed for KMS keys, see [Permissions to Use User-Generated KMS Master Keys](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html). (Amazon Connect acts as the Kinesis stream producer that is described in that topic.)
When Amazon Connect puts records into your Kinesis Data Streams, it uses the service-linked role of the instance for authorization. This role needs permission to use the KMS key that encrypts the data stream. To assign permissions to the role, perform the following steps to update the [key policy ](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) of that KMS key.
**Note**
To avoid missing data, update the permission of the KMS key before using a KMS key with Amazon Connect streaming.
### Step 1: Obtain the ARN for the service-linked role of your Amazon Connect instance
You can use the Amazon Connect console or the AWS CLI to obtain the ARN.
**Use the Amazon Connect console to obtain the ARN**
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance name, as shown in the following image.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. On the **Account overview** page, in the **Distribution settings** section, the service-linked role is displayed.
![\[The account overview page, the service-linked role ARN.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/service-linked-role.png)
1. Choose the copy icon to copy the role ARN to your clipboard, and save that ARN. You're going to use it in [Step 2: Construct a policy statement](#step2-sse).
**Use the AWS CLI to obtain the ARN**
1. Run the following command:
`aws connect describe-instance --instance-id your_instance_id`
1. Save the ServiceRole value from the CLI output.
### Step 2: Construct a policy statement
Construct a policy statement that gives permission to the ARN of the Amazon Connect service-link role to generate data keys. The following code shows a sample policy.
```
{
"Sid": "Allow use of the key for Amazon Connect streaming",
"Effect": "Allow",
"Principal": {
"AWS": "the ARN of the Amazon Connect service-linked role"
},
"Action": "kms:GenerateDataKey",
"Resource": "*"
}
```
Add this statement to the KMS key policy by using your preferred mechanism, such as the AWS Key Management Service console, the AWS CLI, or the AWS CDK.
# Emergency login to the Amazon Connect admin website
As a best practice, users assigned to the Amazon Connect **Admin** security profile should always use their Amazon Connect instance URL to login:
+ Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/.
This method ensures the appropriate levels security.
However, if there's an emergency, you can log in from the Amazon Connect console using your AWS account credentials. For example, you may need to login in this way in the following situations:
+ You forgot your Amazon Connect administrator password and no other Amazon Connect administrators are around to reset it.
+ Someone deleted the Amazon Connect **Admin** security profile by mistake.
**To login for emergency access**
1. Make sure you have your AWS account credentials at hand and that you have the [required permissions](security-iam-amazon-connect-permissions.md#federations).
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. If prompted to login, enter your AWS account credentials.
1. Choose the name of the instance from the **Instance alias** column.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. In the navigation pane, choose **Overview**.
1. Choose **Log in for emergency access**.
You aren't prompted for your credentials because you are federated in from the AWS console.
**Important**
For daily usage, we strongly recommend always using your instance URL to login. The procedure provided in this article should only be used for emergency access when using the instance URL is not an option.
**To log out**
To log out of your instance, go to the title bar at the top of the screen and select the icon with the arrow (**Log out**) that appears next to your user name.
# Delete your Amazon Connect instance
Delete your instance
If you no longer need your Amazon Connect instance, you can delete it. Here's what happens when you delete it:
+ Its claimed phone number is released back to inventory.
+ When customers call the phone number that you've released, they'll get a message that it's not a working phone number.
## Important things to know
Important things to know
+ You can't restore a deleted Amazon Connect instance or access its settings, data, metrics, and reports.
+ Due to GDPR compliance, scheduling data is retained for 30 days and you are be billed for usage during this time. For information about GDPR compliance and Amazon Connect forecasting, capacity planning, and scheduling, see this [FAQ](https://aws.amazon.com/connect/optimization/#topic-0).
+ If you have [enabled Amazon Connect flow logging](contact-flow-logs.md), you need to delete the CloudWatch log groups manually if they are no longer needed. You can do this by using the CloudWatch console. For programmatic instructions, see [Use DeleteLogGroup with an AWS SDK or CLI](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/example_cloudwatch-logs_DeleteLogGroup_section.html).
## Delete your instance
You must have the appropriate AWS permissions to delete an Amazon Connect. If your organization is using IAM, see [Required permissions for using custom IAM policies to manage access to the Amazon Connect console](security-iam-amazon-connect-permissions.md).
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. Select the radio button for the instance.
1. Choose **Delete**. If you don't see the **Delete** button, you don't have permissions to delete instances. Contact your AWS administrator for help.
![\[The Amazon Connect virtual contact center instances page, the delete button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance-delete.png)
1. When prompted, enter the name of the instance and then choose **Delete**.
## Error message: "Region Unsupported. Amazon Connect is not available in [Region]"
Error message: Region Unsupported
If you get this error message, it means that you selected a Region in the AWS Management Console that is not the Region in which you created the Amazon Connect instance, and Amazon Connect isn't available in that Region.
**To switch Regions and delete your Amazon Connect instance**
1. From the navigation bar, open the Region selector. Select the Region in which you created the Amazon Connect instance.
![\[The list of Regions in the Region selector.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/aws-management-console-region.png)
1. From the navigation bar, choose **Amazon Connect** from the list of services to open the Amazon Connect console. If you don't see the instance, keep selecting from the supported Regions until you find your instance.
1. Select the radio button for the instance.
1. Choose **Delete**. If you don't see the **Delete** button, you don't have permissions to delete instances. Contact your AWS administrator for help.
1. When prompted, enter the name of the instance and then choose **Delete**.
# Tagging an Amazon Connect instance
Tagging an instance
Instance Tagging provides the ability for you to tag Amazon Connect instances and build tailored authorization through tag-based access control (TBAC). To help you manage your Amazon Connect instances, you can assign your own metadata in the form of tags to the instance. If you have multiple Amazon Connect instances in a single AWS account, each serving different functions or catering to specific lines of business, using tags can help you better organize and apply tag-based access control (TBAC) policies to these instances for improved management and control.
[AWS Tags](tagging.md) serve as a useful tool for organizing your AWS resources. They consist of key-value pairs that help you categorize resources based on criteria like purpose, owner, or environment. This enables you to identify and manage your resources. Amazon Connect, allows you to add tags to your instances directly from the AWS console, or by utilizing public APIs.
## Tagging Amazon Connect instances at creation
Tagging Amazon Connect instances at creation
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. Choose **Add an instance**.
![\[Add an instance that you would like to tag.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-instance-at-creation-1.png)
1. Under **Set identity**, select the type of **Identity management** that you would like to use, enter a customer **Access URL**, and choose **Next**.
![\[Set identity management options and enter a customer access URL.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-instance-at-creation-2.png)
1. Under the **Add administrator** section, you can choose the **Add new tag** option if you would like to add tags to your instance.
![\[You can chose to add tags on this step of instance creation.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-instance-at-creation-3.png)
1. Enter a `Key` and `Value` pair and choose **Next**.
1. Once you have made your desired configurations under the **Set telephony** and **Data storage** steps, review your configurations and choose **Create instance**.
![\[Create you instance after reviewing your desired configurations.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-instance-at-creation-4.png)
1. Once the instance has been created, navigate to the **Account overview** page of the instance and the tags that you added will appear in the **Tags** section.
![\[The characters after the last /.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-instance-at-creation-5.png)
## Tagging an existing Amazon Connect instance
Tagging an existing Amazon Connect instance
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. Select an existing instance that you would like to add tags too.
![\[Select an instance that you would like to tag.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-existing-instance-1.png)
1. On the **Account overview**, choose **Add new tag**.
![\[Choose the add tag button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-existing-instance-2.png)
1. Enter a `Key` and `Value` pair and choose **Next**. You can add up to 50 tags on a single instance.
![\[Add key and value pairs for your tags.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-existing-instance-3.png)
1. Choose **Save** to add your tags to your instance.
![\[Choose save to add your tags to your instance.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-existing-instance-4.png)
## Tagging an Amazon Connect instance using the API
Tagging an Amazon Connect instance using the API
To tag Amazon Connect instances using the public APIs, see [TagResource](https://docs.aws.amazon.com/connect/latest/APIReference/API_TagResource.html) and [UntagResource](https://docs.aws.amazon.com/connect/latest/APIReference/API_UntagResource.html).
## Sample IAM policies for scenarios with and without instance tags
Sample IAM policies for scenarios with and without instance tags
For TBAC on instances, you can define IAM policies based on instance tags and assign them to IAM roles to control access to specific instances. The following are sample scenarios and sample IAM policies for how to use conditions on tags or conditions on resource IDs.
**Scenario 1**: Controlling access to a specific Amazon Connect instance through an IAM role using tags associated with the instance. The following policy allows access only to instances which are tagged with key:`Environment` and value:`Dev`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "connect:*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/Environment": "Dev"
}
}
}
]
}
```
------
**Scenario 2**: Controlling access to a specific instance and all resources within the instance without using tags.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "connect:*",
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"connect:InstanceId": [
"AllowedInstanceID-1",
"AllowedInstanceID-2"
]
}
}
},
{
"Sid": "VisualEditor1",
"Effect": "Deny",
"Action": "connect:*",
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"connect:InstanceId": "DeniedInstanceID-1"
}
}
}
]
}
```
------
## Additional information about instance tagging
Additional information about instance tagging
**Replicating instances:** When you create a [replica of your existing Amazon Connect instance](create-replica-connect-instance.md) to another region using the [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API, tags from the source instance will not be automatically tagged to the newly replicated instance. You will have to tag the replicated instance manually.
**Tag inheritance:** When you tag an Amazon Connect instance, all underlying resources in Amazon Connect, such as routing profiles, queues, will not inherit the instance tags. To learn how to control granular access to specific resources in Amazon Connect, see how to configure more granular access by using [ tag-based access control](tag-based-access-control.md).
# Set up granular billing for a detailed view of your Amazon Connect usage
Set up granular billing
By default bills for Amazon Connect channels (voice calls, chat, tasks, and emails) are summarized at the AWS account level by usage type. For example:
+ Voice calls - by outbound (telephony) / inbound (telephony) / service minutes
+ Chat – by messages
+ Task - by units
+ Email - by messages
To obtain a more detailed view of your bill and usage, you can add cost allocation tags (key:value pairs) to contacts, and then use the tags to aggregate and analyze the data in the AWS Billing and Cost Management console.
+ Amazon Connect automatically adds the following system-defined tags to each contact:
+ **aws:connect:instanceId**: This represents the ID of the Amazon Connectinstance. If you have multiple instances under multiple AWS accounts for each line-of-business, you can view usage bills aggregated against different instances.
+ (**aws:connect:systemEndpoint**): This represents the your contact center number (the endpoint) that the customer reaches (inbound) or is reached from (outbound).
This AWS generated tag helps if you have multiple phone numbers used within your contact center. It enables you to group the costs associated against different phone numbers. For example, group inbound phone numbers for incoming calls, and group outbound numbers that are used for making outbound calls.
+ **aws:connect:transferredFromEndpoint**: This represents the outbound caller ID that the call was transferred from. You can see the third-party transfer call's usage bills aggregated against the telephone numbers that the calls were transferred from. Currently, this AWS generated tag is only added to contacts for third-party external transfer calls.
+ You can add up to 6 user-defined tags. For example, department, cost center, or business unit. Use these tags to organize your AWS bill to reflect your own cost structure.
The following image shows two user-defined tags on the **Contact details** page: CostCenter and Department. It also shows two system-defined tags: instance ID and the contact center phone number (aws:connect:systemEndpoint).
![\[Contact tags on a Contact details page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-contactdetails.png)
This topic explains how to add tags to contacts, activate the cost allocation tags, and view them in the AWS Billing dashboard.
**Topics**
+ [Things to know about user-defined tags](#about-user-defined-tags)
+ [Step 1: Add user-defined tags to contacts](#step1-tagcontacts)
+ [Step 2: Activate cost allocation tags](#step2-activate-tags)
+ [Step 3: View cost and usage trends using cost allocation tags](#step3-view-billingapp)
+ [(Optional) Step 4: Enable Cost and Usage reports in the AWS Billing and Cost Management console](#step4-cost-and-usage-reports)
+ [More reporting options](#step5-contactlevel-cost-and-usage-reports)
## Things to know about user-defined tags
Things to know about user-defined tags
+ Amazon Connect automatically applies user-defined tags to new contact segments for scenarios like transfers or contact re-hydration (for example, persistent chat, and tasks related to contacts).
+ Use the [DescribeContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeContact.html) API to list the tags on a contact.
+ You can remove and/or overwrite the tags by using the [Contact tags](contact-tags-block.md) block or the [TagContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_TagContact.html) and [UntagContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_UntagContact.html)APIs.
+ By using the [TagContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_TagContact.html) and [UntagContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_UntagContact.html) APIs, you can update user-defined tags for a contact up to 3 hours after the contact was disconnected. However, any future updates on the contact tags are not reflected in the billing system. For example, you make a change to the value of a tag within 3 hours after the contact was disconnected. The AWS Billing console will show the old value of the tag, but the S3 bucket and contact record have the new value.
+ After you add tags to Amazon Connect, they are available across all contact interfaces: contact records, contact events, and the **Contact details** page. You can also access them by using the `$.Tags` JSONPath Reference, and by using [Amazon Connect Streams](https://github.com/aws/amazon-connect-streams).
+ You cannot use tags as filters on the **Contact search** page. In addition, they cannot be included in any of the analytics or reporting pages.
+ Contact tags only function as cost allocations tags. You cannot use them for tag-based access controls on contacts.
+ Tags are available in the Amazon Connect data lake [Contact record table](data-type-definitions.md#data-lake-contacts-record) under tags\$1references\$1items.
## Step 1: Add user-defined tags to contacts
Step 1: Add user-defined tags to contacts
To add user-defined tags like Department and Cost Center to contacts, you have two options:
+ Use the [TagContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_TagContact.html) API.
+ Add a [Contact tags](contact-tags-block.md) block to your flow.
The following image shows an example of a **Properties** page of a **Contact tags** block that is configured with a tag named **Department**. Its value is set manually to **Finance**.
![\[The properties page of a Contact tags block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-contacttags-properties.png)
**Important**
Do not store personally identifiable information (PII) or other confidential or sensitive information in tags. We use contact tags to provide you with billing services. Tags are not intended to be used for private or sensitive data.
## Step 2: Activate cost allocation tags in the AWS Billing console
Step 2: Activate cost allocation tags
**Tip**
It takes up to 24 hours for the tags to activate.
To enable AWS billing applications to organize your billing information according to resources with the same tag key values (either for system-defined and user-defined contact tags), you must activate the tags. Perform the following steps.
1. Open the AWS Billing and Cost Management console at [https://console.aws.amazon.com/costmanagement/](https://console.aws.amazon.com/costmanagement/).
1. In the left navigation menu, choose **Cost Allocation Tags**.
1. Select the system-defined and user-defined tags, and then choose **Activate**. It can take up to 24 hours for tags to activate.
The following image shows an example tag on the **Cost allocation tags** page.
![\[Contact tags on the cost allocation tags page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-costallocationtags.png)
## Step 3: View cost and usage trends using cost allocation tags
Step 3: View cost and usage trends using cost allocation tags
You can view the month-over-month trends at the granular level by using cost allocation tags.
1. Open the AWS Billing and Cost Management console at [https://console.aws.amazon.com/costmanagement/](https://console.aws.amazon.com/costmanagement/).
1. In the left navigation, choose **AWS Cost Explorer**.
1. On the **Cost Explorer** page, choose **Tags**, and then select the tags you want to view, for example, department or inbound telephone number.
The following image of AWS Cost Explorer shows a sample report where **department** is a filtered cost allocation tag.
![\[The AWS Cost Explorer, Amazon Connect cost and usage trends.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-awscostmanagement.png)
If you use the AWS account level bill summary to view the service level cost breakdown in the AWS Billing dashboard, you won't see any changes on the dashboard after implementing contact tags. The following image shows an example AWS Billing dashboard.
![\[The AWS billing dashboard, a sample Amazon Connect bill.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-billingdashboard.png)
For more information about using AWS Cost Explorer, see [Analyzing your costs with AWS Cost Explorer](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html) in the *AWS Cost Management User Guide*.
## (Optional) Step 4: Enable Cost and Usage reports in the AWS Billing and Cost Management console
(Optional) Step 4: Enable Cost and Usage reports in the AWS Billing and Cost Management console
You can enable AWS Cost and Usage reports on the AWS Billing and Cost Management console, and configure your S3 bucket to export data to along with time granularity for reports (hourly, daily, monthly). After you set this up, you will receive reports with tags in additional columns. By default reports are aggregated by usage-type and tags.
For instructions, see [Creating Cost and Usage Reports](https://docs.aws.amazon.com/cur/latest/userguide/creating-cur.html) in the *AWS Data Exports User Guide*.
The following image shows what a Cost and Usage report looks like with columns for system and user-defined tags.
![\[An Amazon Connect cost and usage report with tags.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-after-cur.png)
The following image shows what a cost and usage report looks likes without system or user-defined tags.
![\[An Amazon Connect cost and usage report without granular billing.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-before-cur.png)
## More reporting options
More reporting options
Another option is to view usage data for each contact. You can enable contact resource IDs to appear on your cost and usage reports in the AWS Billing and Cost Management console. After choosing this option, you will receive detailed reports in your S3 buckets, and the data will be categorized by each contact resource ID. You can use the reports for analysis by third-party applications.
**Note**
Including resource IDs creates individual line items for each of your resources. This might increase the size of your Cost and Usage Reports files significantly, based on your AWS usage.
The following image shows where you enable **Include resource IDs** on the AWS Billing console.
![\[The AWS Billing console.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-contactlevel-usagedata.png)
The following image shows a sample cost and usage report when **Include resource IDs** is enabled.
![\[A sample cost and usage report with resource IDs.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/granularbilling-includeresourceids.png)
For instructions for this option, see [Creating Cost and Usage Reports](https://docs.aws.amazon.com/cur/latest/userguide/cur-create.html) in the *AWS Data Exports User Guide*.
# Test voice, chat, and task experiences in Amazon Connect
To learn what the voice, chat, and task experiences are like for your agents and customers, you can test them without doing any development.
## Test voice
At the basic level, after you claim a number you can immediately call it to hear what the experience will be like for your customers. Amazon Connect uses the [default flows](contact-flow-default.md) to power your initial experience.
To test a customized flow, [assign a phone number](associate-claimed-ported-phone-number-to-flow.md) to it and then call that number.
**Tip**
Call latency significantly impacts the quality of your customer's experience. For guidance about designing your contact center for optimal call quality and then testing latency, see [Design your Amazon Connect contact center for low latency to help ensure call quality](low-latency-design.md).
## Test chat
Amazon Connect includes a simulated web page that shows how your customers can interact with you, and a Contact Control Panel (CCP) that shows the agent experience. Here's how to test chat:
1. On the navigation menu, choose **Dashboard**, as shown in the following image.
![\[The dashboard icon on the Amazon Connect navigation menu.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tutorial1-dashboard-menu.png)
1. Choose **Test chat**.
If you don't see the option to test chat, click [here](https://github.com/amazon-connect/amazon-connect-chat-ui-examples#enabling-chat-in-an-existing-amazon-connect-contact-center).
1. On the **Test Chat** page, choose **Test Settings**.
1. Under **System Settings**, choose the flow you want to test with chat, and then click **Apply**. By default, it runs the [Sample inbound flow](sample-inbound-flow.md).
**Tip**
If you want to test a chat and use contact attributes, note that the key and value pair must be enclosed in quotes, as shown in the following image:
![\[The test settings section, with a name in Contact attributes surrounded by quotes and brackets.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-chat-contact-attributes.png)
1. In the chat window, click the icon as shown in the following image.
![\[The Amazon Connect chat icon on the test page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-chat-icon.png)
1. Type a message similar to what one of your customers might type. In the agent window, type a reply.
1. To see what it's like for an agent to handle multiple chat conversations, copy the dashboard URL into another browser window, and start another chat. The chat goes to the same instance of the CCP that you already have open.
**Tip**
The test environment uses the BasicQueue and Basic Routing Profile. The Basic Routing Profile is set up for 2 chats. If you want to test what it's like to have more than two chats, change the Basic Routing Profile to 5 chats. For instructions, see [Create a routing profile in Amazon Connect to link queues to agents](routing-profiles.md).
To learn more about what the agent experiences when managing chat conversations, see [Use the Contact Control Panel (CCP) in Amazon Connect to chat with contacts](chat-with-connect-contacts.md).
## Test tasks
The first step in testing the task experience is to create a quick connect for the queue you want to assign the example tasks to.
**Step 1: Create a quick connect**
1. On the navigation menu, choose **Routing**, **Quick connects**, **Add a new**.
1. Enter a name for the quick connect. For example, if you want to assign the test task to yourself, enter your name (for example, **Jane Doe**).
1. Under **Type**, use the dropdown list to choose **Queue**.
1. Under **Destination**, use the dropdown list to choose a queue you set up for yourself (assuming you want to assign the test task to yourself).
1. Under **flow**, choose **Default queue transfer**.
1. Under **Description**, enter something like **Test quick connect**.
1. Choose **Save**. The completed quick connect looks similar to the quick connect in the following image.
![\[A quick connect for Jane Doe.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-tasks-quick-connect-setup.png)
**Step 2: Make the quick connect visible in the CCP by assigning it to a queue**
1. After you create the quick connect, go to **Routing**, **Queues** and then choose the appropriate queue for the contact to be routed to.
1. On the **Edit queue** page, in the **Quick connects** box, search for the quick connect you created. For example, it might have your name. The following image shows the quick connect for Jane Doe.
![\[The edit queue page, the Quick connects dropdown menu, Jane Doe's quick connect.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-tasks-janedoe-queue.png)
1. Select the quick connect and then choose **Save**.
**Step 3: Assign the queue to the agent's routing profile**
1. Go to **Users**, **Routing profiles** and choose the agent's routing profile.
1. Under **Set channels and concurrency** choose **Tasks**.
1. Add the agent's queue to the routing profile, and choose **Task** for the channel.
If the agent can receive transfers through other channels, select them as well.
1. Choose **Save**.
**Step 4: Test tasks**
1. Open the CCP. Select the **Task** tab, and then choose **Create task**. The following image shows there are two ways to choose **Create task**: choose the task icon in the top right corner, or choose the **Create task** button at the bottom of the CCP page.
![\[The task icon and the create task button on the CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-create-task-ccp.png)
Or, if you're testing the chat experience, for example, you can choose the **Task** icon, as shown in the following image.
![\[The CCP page, a chat conversation, the task icon at the bottom of the page .\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-chat-task-window.png)
1. Complete the **Create task** page. When you choose **Assign to**, you can assign only a task to someone or a queue that has quick connect.
To create a scheduled task for the future, use the **Scheduled date/time** box to choose a future date and time. You can schedule a task up to six days in future.
Choose **Create**.
![\[The Create task page in the CCP, the scheduled date time option, the create button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-create-task-ccp-2.png)
1. If you chose yourself, the task will be routed to you. The following image of the CCP shows what it looks like when a task arrives. Choose **Accept task**.
![\[The CCP, an incoming task.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-tasks-incoming.png)
1. Review the task. When you're done with the task, choose **End task** when done.
![\[The CCP, a connected task, the End task button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-task-end-task.png)
## View metrics for the test experiences
When you're testing the voice, chat, and task experiences, you may also want to explore metrics.
1. On the left navigation menu, choose **Analytics and optimization**, **Real-time metrics**, **Queues**.
1. You can review the real-time metrics as you test the different channels.
1. To view metrics by channel in a real-time metrics report, go to **Settings**, **Groupings**, **Queues grouped by channels**, **Apply**. Your report will look similar to the following image.
![\[The real-time metrics report page, the Channels column.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-rtm-grouping-by-channel.png)
# Set up your channels
Set up your channels
Amazon Connect is a unified omnichannel solution built to empower personalized, efficient and proactive experiences across customers' preferred channels. You can tailor seamless experiences for your customers, whether it's over the phone, through in-app and web calling, video, chat, Short Message Service (SMS), or email. Customers can keep working with the same agent across channels, but if it's a different agent their interaction history is preserved, so they don't have to repeat themselves. The omnichannel contact center improves customer experiences while reducing resolution time.
![\[The Amazon Connect customer experience, seamless, personalized, and proactive across channels.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/omnichannel-diagram.png)
**Topics**
+ [Set up your phone numbers](ag-overview-numbers.md)
+ [Set up your customer's chat experience](enable-chat-in-app.md)
+ [Set up SMS messaging](setup-sms-messaging.md)
+ [Add the Amazon Connect widget to your website](connect-widget-on-website.md)
+ [Enable Apple Messages for Business](apple-messages-for-business.md)
+ [
# Set up WhatsApp Business messaging
](whatsapp-integration.md)
+ [Set up in-app, web, video calling, and screen sharing capabilities](inapp-calling.md)
+ [Set up tasks](concepts-getting-started-tasks.md)
+ [Set up email](setup-email-channel.md)
+ [Create quick responses](create-quick-responses.md)
# Set up contact center phone numbers for your Amazon Connect instance
Set up your phone numbers
After you create an Amazon Connect instance, you can get a phone number to use for your contact center. You can use this phone number to place a test call in to your contact center to confirm that it is working correctly. You can also use it in your production environment.
+ For pricing information about claimed phone numbers, see [Amazon Connect pricing](https://aws.amazon.com/connect/pricing/).
+ For a list of the telephony capabilities that Amazon Connect provides, see the [Amazon Connect Telecoms Country Coverage Guide](https://d1v2gagwb6hfe1.cloudfront.net/Amazon_Connect_Telecoms_Coverage.pdf).
If you want to keep a phone number you already have, you can port the phone number and use it with Amazon Connect. After a phone number is ported to Amazon Connect, it appears in the list of available phone numbers for you to assign to flows.
**Topics**
+ [Voice channel](concepts-telephony.md)
+ [Stir/Shaken attestation](stirshaken.md)
+ [Design for low latency](low-latency-design.md)
+ [Port your current phone number](port-phone-number.md)
+ [Claim and manage your phone numbers](claim-and-manage-phonenumbers.md)
+ [Use caller identification to personalize customer interaction](caller-id-personalizing-customer-interaction.md)
+ [Third-party numbers](third-party-numbers.md)
+ [UIFN service support - Inbound only](uifn-service.md)
+ [Region requirements for ordering and porting phone numbers](phone-number-requirements.md)
# The voice channel in Amazon Connect
Voice channel
**Important**
Trying to contact Amazon for support? See [Amazon Customer Service](https://www.amazon.com/gp/help/customer/display.html) (Amazon orders and deliveries) or [AWS Support](https://aws.amazon.com/premiumsupport/) (Amazon Web Services).
Amazon Connect provides a variety of choices to enable your company to make and receive telephone calls. One of the great advantages of Amazon Connect is AWS manages the telephony infrastructure for you: carrier connections, redundancy, and routing. And, it's designed to scale.
This topic explains the options that Amazon Connect provides for telephony, which helps you build a solution to meet your business requirements.
**Topics**
+ [
## Telephony architecture
](#concepts-telephony-architecture)
+ [
## Use cases for different configurations
](#concepts-use-cases)
## Telephony architecture
Amazon Connect provides capabilities to host both toll-free and direct dial numbers (DID) in all AWS Regions supported by Amazon Connect. You can use both types of numbers in a single instance. A complete list of supported countries/regions and costs is located on the [Amazon Connect pricing](https://aws.amazon.com/connect/pricing/) page.
AWS manages the connectivity to our network of carriers providing diverse connections to multiple carriers in each region supported by Amazon Connect. When Amazon Connect is deployed in a Region, we take advantage of the built-in redundancy of the AWS Availability Zone design to provide multiple carrier interfaces into multiple data centers. You can see how AWS manages the design of a Region [here](https://infrastructure.aws/).
In addition to the Amazon Connect service being spread across multiple Availability Zones, AWS also has multiple telephony providers. These providers have multiple links into the data centers in those Availability Zones. This ensures that if a single or even multiple links fail from a carrier, there are alternate routes available to ensure the service remains available.
To learn more about Amazon Connect architecture, see [Architectural guidance for Amazon Connect](architecture-guidance.md).
+ **AWS manages toll-free numbers as a Responsible Organization**
These numbers are phone numbers with distinct prefix codes that can be dialed with no charge to the person placing the call. Such numbers allow callers to reach businesses and/or individuals out of the area without being charged a long-distance fee for the call.
In the United States, the [Federal Communications Commission](https://www.fcc.gov/consumers/guides/what-toll-free-number-and-how-does-it-work) provides rules for obtaining and using toll-free numbers. In other countries, similar governing bodies ensure that such numbers are managed and distributed in accordance with local laws.
When you claim or port a US toll-free number into Amazon Connect, we register that number with [SOMOS](https://www.somos.com/). After the number is registered, we are able to select multiple carriers to provide BOTH route and carrier redundancy. This provides the highest level of availability, ensuring the number will remain available even in the event of a complete carrier outage. This level of service does come at an additional cost, as these numbers are a higher price than direct dial, but the service reliability and customer experience make this the most attractive option.
+ **Locally formatted numbers**
Direct inward dialing (DID), also called direct dial-in (DDI) in Europe, is a telecommunication service offered by telephone companies to subscribers. DID numbers provide a locally formatted telephone number that can match the dialing pattern of a local subscriber. For example, in Seattle, Washington, USA, the local dialing pattern is \$11(206)-NXX-XXXX. The provider of the DID number would provide numbers with the \$11(206) pattern to match local dialing.
In the United States, DID numbers are regulated by State Public Utilities commissions. DID numbers are managed by a single carrier. While they are portable, they can't be load balanced/managed across multiple carriers. This makes them less reliable than toll-free numbers.
DID numbers offer you the ability to present a local calling line identification when placing outbound calls, and a local presence to inbound callers. This can be very useful to increase the likelihood outbound and queued callback calls get answered by your customers. It can also show a customer that you are local to their area, and provide a cheaper inbound route than a long-distance call if you don't publish a toll-free number.
Because DID numbers are threaded to single carrier, Amazon Connect doesn't offer carrier redundancy for DID numbers. We do offer link redundancy across multiple Availability Zones, so in the event of a link failure that carrier still has facilities available in another location to deliver calls. DID numbers also have a capacity limitation on how many calls a single number can accommodate, and this number does vary by Region. It is important to work with your AWS account team to ensure you are properly enabled with the right type of DID numbers if you plan on using DID numbers as your primary inbound channel, and have an expectation of over 100 concurrent calls per number.
DID numbers are less expensive than toll-free numbers, but don't have the redundancy and broad geographical coverage of them. The ability to localize numbers may be an attractive option for your business.
## Use cases for different configurations
### Starting fresh with Amazon Connect
In this case, simply select new numbers using the claim a number process. For instructions, see [Get a local toll-free or DID Amazon Connect phone number](get-connect-number.md).
### Migrating to Amazon Connect from another provider/platform
If you're migrating to Amazon Connect from other platform, we recommend starting with a proof of concept, and migrating to Amazon Connect over time.
+ A best practice is to forward your existing numbers to a new number (or numbers) claimed in Amazon Connect until you are fully converted.
+ After fully converting, use the [porting process](port-phone-number.md) to bring your numbers into Amazon Connect.
+ This gives you a fallback in case you have migration issues.
### Maintaining two separate platforms
In some cases, you may have more than one Contact Center platform requiring telephony. Here's an overview of how to configure this:
+ Choose which platform is the initial call-handling service, and forward to the other platform.
+ If Amazon Connect is the primary call handling platform, you can port or claim numbers. You will design your flows to transfer calls to the other platform on a telephone number you will provide in the flow.
+ If the external platform is the primary call handler, you will need to configure that platform to forward calls to a number you claim in Amazon Connect. Choose either a toll-free number, which will give you better redundancy and capacity at an increased cost, or a bank of DID numbers to terminate the call into Amazon Connect.
+ For the use case, we recommend that you engage AWS Solution Architecture support to ensure your contact center is well-architected to achieve the best possible outcomes.
# Stir/Shaken attestation in Amazon Connect
Stir/Shaken attestation
Amazon Connect supports STIR/SHAKEN attestation for outbound calls to help prevent caller ID spoofing.
When originating calls from United States direct-inward-dial (DID) or toll-free numbers to North American Numbering Plan (NANP) destinations (\$11 prefix), Amazon Connect signs calls with STIR/SHAKEN headers indicating the level of attestation.
**Topics**
+ [What is STIR/SHAKEN?](#what-is-stirshaken)
+ [Amazon Connect attestation levels](#attestation-levels)
+ [Requirements for A-level attestation](#attestation-level-a)
+ [Requirements for B-level attestation](#attestation-level-b)
+ [Examples of C-level attestation](#examples-c-attestation)
+ [Important things to know](#important-attestation)
## What is STIR/SHAKEN?
What is STIR/SHAKEN?
The STIR/SHAKEN framework is designed to combat fraudulent caller ID spoofing in telephony networks. It consists of two components:
+ STIR (Secure Telephone Identity Revisited): The underlying protocol suite that enables cryptographic signing and verification of calling numbers.
+ SHAKEN (Signature-based Handling of Asserted Information Using toKENs): Guidelines for implementing these protocols across networks.
For more information about STIR/SHAKEN, see [Combating Spoofed Robocalls with Caller ID Authentication](https://www.fcc.gov/call-authentication) on the Federal Communications Commission (FCC) website.
## Amazon Connect attestation levels
Amazon Connect attestation levels
Amazon Connect assigns one of three attestation levels when signing outbound calls:
+ A-level (Full) - Amazon Connect has:
+ Authenticated the calling party
+ Confirmed their authorization to use the calling number
+ B-level (Partial) - Amazon Connect has:
+ Authenticated the calling party
+ Cannot verify their authorization to use the number
+ C-level (Gateway) - Amazon Connect has:
+ Originated the call
+ Cannot verify the calling party's identity
+ Cannot verify legitimate use of the number
## Requirements for A-level attestation
Requirements for A-level attestation
Your calls receive A-level attestation if you are subject to AWS Service Terms or are a customer of an authorized AWS Solution Provider/Distribution Seller AND any of these conditions are met:
+ Number claimed through Amazon Connect portal/API.
+ Number ported into Amazon Connect.
+ Third-party number mapped to your account with validated documentation.
## Requirements for B-level attestation
Requirements for B-level attestation
Your calls receive B-level attestation if:
+ You have been notified that additional information is needed to maintain A-level attestation.
+ We have NOT notified you that we have successfully validated the information you provided.
## Examples of calls that receive C-level attestation
Examples of C-level attestation
All calls that don't receive A- or B-level attestation receive C-level attestation.
Following are examples of calls that receive C-level attestation:
+ Calls made by customers using unauthorized solution providers.
+ Calls made in violation of AWS Services Terms (for example, call deflection).
+ Cases where we have notified you that additional information is required and we have not received the requested attestation documentation by the specified date.
## Important things to know
Important things to know
+ While Amazon Connect provides STIR/SHAKEN headers to carriers, attestation may not be preserved end-to-end due to legacy equipment in some carrier networks that cannot transmit these headers.
+ Carriers may use attestation levels as part of their process of determining whether they deliver calls in their network.
+ To maintain the highest levels of attestation for your calls, Amazon Connect may ask you for additional information. In the notification email we send to you, we will state when you need to reply with the requested information. Any delays in providing us the information may impact the attestation level of your calls and as a result, may impact the success of your call delivery.
# Design your Amazon Connect contact center for low latency to help ensure call quality
Design for low latency
**Note**
As of July 2023 we have simplified requirements to claim phone numbers that are located in countries outside of the AWS Region where your Amazon Connect instance is located. The process has been simplified to remove the need for the opt-in approval. Instead we provide best practice design guidance. This makes it easier for you to use an Amazon Connect instance that is created in the US-East Region, for example, and then request numbers in Japan. Or, if your instance is created in Asia Pacific (Singapore), you don't need to contact AWS Support to claim phone numbers based in Europe or US Regions.
We continue to extend the support of Amazon Connect so you can claim phone numbers in the countries you need, wherever you need them.
If you are configuring your Amazon Connect instance to support phone numbers outside of your country's home AWS Region, we recommend the following best practices.
1. Anchor either your phone numbers or agents in the same AWS Region where they are geographically located. For example, if your agents are located in a US Region, your Amazon Connect instance should be created in an AWS Region in the US, too. Or, if your phone numbers are in an EU country, your Amazon Connect instance should be created in an EU AWS Region, too.
1. If both your phone numbers **and** agents are located in an AWS Region that is different from the one where your Amazon Connect instance is created, call latency is extended above 500ms for network latency (WebRTC RTT). This latency may result in call quality issues.
1. Calculate your latency before setting up your Amazon Connect contact center in production. Perform the following steps on a test environment:
1. Use the [Amazon Connect Endpoint Test Utility](check-connectivity-tool.md) to check latency.
1. Calculate the latency for routing telephony from the country to the AWS Region using internet-based, external tools, such as [WonderNetwork](https://wondernetwork.com/).
1. For calls with the best call quality, we recommend configurations with less than 500ms of latency end-to-end.
1. You may determine that call quality is acceptable at up to 900ms of latency for both network and telephony latency. (900ms is a sum of 500ms network latency and 400ms carrier latency.) However, if you note a call-quality issue that can be due to latency, and other potential causes are ruled out (for example, neither packet loss nor jitter are detected), we recommend configuring your Amazon Connect instance or telephony for a lower latency. For example, create your Amazon Connect instance in the same Region as your telephony or agents.
**Important**
When call latency is greater than 900ms for both network and telephony latency, it leads to a significant delay between agents and customers.
1. Check that latency matches your design.
After you claim a number you can immediately call it to hear what the experience will be like for your customers. Amazon Connect uses the [default flows](contact-flow-default.md) to power your initial experience.
To test a customized flow, [assign a phone number](associate-claimed-ported-phone-number-to-flow.md) to it and then call that number.
# Port a current phone number to Amazon Connect
Port your current phone number
You can port your existing phone numbers to your Amazon Connect contact center.
**Topics**
+ [Things to know before porting](things-to-know-before-porting.md)
+ [South Korean porting regulations for your Amazon Connect instance](porting-numbers-sk.md)
+ [Things to know about Thailand number porting](porting-numbers-th.md)
+ [Porting your phone numbers](porting-your-phone-numbers.md)
+ [After the porting process completes](porting-troubleshoot.md)
# Things to know before porting a phone number to Amazon Connect
Things to know before porting
The topics in this section explain which numbers can be ported, how long it takes, and what fees you might incur.
The following terminology is used in these topics:
**Letter of Authorization**
Letter of Authorization (LOA) is a legal document in which you assert to the carrier for Amazon Connect that you have the authority to port phone numbers from your current carrier to the carrier for Amazon Connect. Traditionally, this is a paper document requiring an actual signature.
**Losing carrier**
Also known as your current carrier. This is the carrier that currently owns your telephone number. The losing carrier reviews all information presented on the Letter of Authorization (LOA) and validates if it matches the information that they have on file for you.
**Mutually agreed date and time**
After the LOA has been approved by the losing carrier, the losing and winning carriers agree upon a date and time to perform the porting activity.
**Phone number portability**
Number portability allows you to transfer your telelphone numbers to other carriers. Carriers and countries may have unique processes and procedures required.
**Winning carrier**
Also the carrier for Amazon Connect. This is the carrier that the phone number is being ported to, and will own the phone number after the porting is completed.
**Topics**
+ [What is phone number porting?](what-is-phone-number-porting.md)
+ [How much does it cost?](fees-for-number-porting.md)
+ [Can my number be ported?](what-numbers-can-be-ported.md)
+ [How long does it take to port numbers?](how-long-for-number-porting.md)
+ [Can I cancel a scheduled porting?](cancel-port-request.md)
+ [When do I cancel my current telecom service?](cancel-current-service.md)
# What does it mean to port phone numbers to Amazon Connect?
What is phone number porting?
Porting a phone number is the process of moving a phone number from one telephony service provider, or carrier, to another. Many businesses and organizations already have a phone number that is advertised to their customers, so changing this number would be disruptive.
If you port a phone number from your current carrier to Amazon Connect, you can keep using the same phone number for your contact center. This helps to eliminate the need to update your business contact information.
## Downtime and service disruption during the porting process
The porting process requires the losing carrier to remove your number from their systems, the winning carrier to add your number to their systems, and for number routing to be updated. Most porting activities complete within 15-30 minutes, with possible call disruptions. To ensure that they have engineers available to troubleshoot issues, most losing carriers complete porting actions only during normal business hours. Carriers typically communicate a two-hour porting window to resolve any issues that could arise.
For detailed information about available porting dates and times, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md) for your country or region.
## What happens to a number after it is ported
What happens to a number after it is ported
As long as you continue to pay for the phone number, and do not release it from your Amazon Connect instance, it stays assigned to your account, and you are billed accordingly.
To release a phone number, follow the steps in [Release a phone number from Amazon Connect back to inventory](release-phone-number.md).
When a phone number is released from your Amazon Connect instance:
+ You will no longer be charged for it.
+ You cannot reclaim the phone number.
+ Amazon Connect reserves the right to allow it to be claimed by another customer.
If you move your contact center away from Amazon Connect, and want to port your phone number away from Amazon Connect, see [Port phone numbers away from Amazon Connect](port-away.md).
# How much does porting a number to Amazon Connect cost?
How much does it cost?
Amazon Connect does not charge fees for porting numbers. Your existing carrier may have fees associated with the disconnection and early termination of your service.
After a phone number is ported to Amazon Connect, standard pricing applies for [Amazon Connect service usage and associated telephony rates](https://aws.amazon.com/connect/pricing/).
# Phone numbers that you can port to Amazon Connect
Can my number be ported?
Not all phone numbers can be ported. The ability to port a specific phone number depends on several factors. For example:
+ The regulations in the country or region of the phone number.
+ Agreements between the losing and winning carriers.
+ The type of phone number being ported.
+ Your service contract with your current service provider.
To find out if a phone number that you currently own—whether local, mobile, or toll-free—can be ported to Amazon Connect:
1. See if your country or region supports number porting: [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
1. Then get started by [submitting an Amazon Connect support ticket for number verification](about-porting.md#step1-porting).
## Porting numbers purchased from other contact center providers
Port numbers purchased from other contact center providers
In most cases, you can port numbers that were purchased from other contact center providers. Confirm with your current contact center provider who holds the assignment to the number, and work with them to ensure the correct information is provided in the Letter of Authorization (LOA).
## Port short phone numbers
Port short phone numbers
Because of Telecom regulations in various countries or regions, the short phone number will need to be evaluated on a case-by-case basis. To verify if your phone number can be ported to Amazon Connect, [submit an Amazon Connect support ticket](about-porting.md#step1-porting).
## Port a number to one EU Region only
Port a number to one EU Region only
The Amazon Connect Regions of EU-CENTRAL-1 and EU-WEST-2 are symmetrical European Regions that offer the same carrier coverage for telephony. If a phone number cannot be ported to an instance in one of these Regions, then it cannot be ported to an instance in the other.
If you had a phone number ported into the EU-CENTRAL-1 or EU-WEST-2 Regions, and want to move it to the other Region, [submit an Amazon Connect support ticket](about-porting.md#step1-porting) for assistance.
The same is true for the North America Regions of US-EAST-1 and US-WEST-2.
## Port a subset of numbers from a block
Port a subset of numbers from a block
If you have a block of numbers, in some instances Amazon Connect can port a subset or portion of your phone numbers. In other cases, it is required by the carrier to port full block of phone numbers.
If you want to port only a subset of the phone numbers you currently own to Amazon Connect, [submit an Amazon Connect support ticket](about-porting.md#step1-porting) to verify whether the phone numbers can be ported. We will verify the actions that can be completed and assist you with next steps.
**Note**
If you port only a subset of the phone numbers, you will still be liable for the remaining phone numbers with the original carrier and any associated fees.
If your intent to is release the remaining phone numbers not being ported to Amazon Connect, we recommend waiting until the requested porting has been completed to avoid any disruptions to service.
## Letter of compromise
Letter of compromise
Before porting phone numbers, some customers ask for a letter of compromise stating that they will be allowed to move their phone numbers from Amazon Connect to another service, if their contact center moves. Because of Telecom regulations in various countries, the phone number will need to be evaluated on a case-by-case basis. To verify that your phone number can be ported to Amazon Connect, [submit a ticket to Amazon Connect support](about-porting.md#step1-porting) .
# How long does it take to port phone numbers to Amazon Connect?
How long does it take to port numbers?
**Important**
Porting requests for USA DID and toll-free numbers cannot be submitted more than 30 days in advance of porting date.
For other countries, we recommend opening a porting request as far in advance of your pending go-live date as possible.
The amount of time that it takes to port numbers depends on the country, complexity of the request, the type and quantity of numbers being ported, and your current carrier. Telecom carriers also may implement porting block days because of holidays and network maintenance. Because of this, Amazon Connect requires porting requests to be open several months before pending go-live dates.
For a list of countries and their portability windows, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
## Inside the US and Canada
Phone numbers in the US or Canada typically take between two to four weeks to port, after phone number portability has been verified, and all required documents are correctly submitted to the carrier.
## Outside the US and Canada
Phone numbers outside the US and Canada require between two to six months to complete the full porting process. This includes:
+ Time for you to submit all the documents to AWS Support.
+ Time for the Amazon Connect service provider to verify whether they can port all of the phone numbers that you have requested.
+ Time for the losing provider to verify the provided documents.
After all documents are verified by the losing provider, the losing provider and the Amazon Connect service provider will schedule a mutually agreed date to port the numbers to Amazon Connect.
## What affects porting timelines?
Porting timelines can be negatively impacted when incorrect information is provided on the required Letter of Authorization (LOA). This causes the LOA to be rejected and resets the porting timelines.
## Port many numbers over multiple countries or carriers
Complex porting requests have their own timelines. The timelines discussed elsewhere in this topic do not apply to complex porting requests.
Complex porting requests for more than 10 distinct number ranges or 10 distinct locations are considered a project and require advanced coordination with your AWS Account team. If you are a Business or Enterprise customer, engage your Amazon Connect Solutions Architect (SA) or Technical Account Manager (TAM) for assistance in planning your number porting.
To help make the process as smooth as possible, gather the following information before submitting a porting request:
+ Your most recent telephony bill from the carriers that currently service the numbers to be ported.
+ The country specific documentation required; see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
+ The contact information for a central point of contact who can act on behalf of your organization in support of the porting requests.
## Can I choose the port date?
**Important**
The Amazon Connect service team supports porting phone numbers FROM 9am Monday in Sydney NSW, Australia Time, TO 5pm Friday in Seattle, WA, USA time.
Depending on the country and carriers involved, you may be able to choose the porting date and time. In most cases, however, the losing carrier picks the date and time and communicates it to Amazon Connect based on their schedule.
If you have a specific date and time you want to request, provide the information in your support case. We will work with our carrier to determine if they can support the requested date and time.
**Note**
Most carriers only support porting activity during their normal business hours. For detailed information about available porting dates and times for your country, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
# Can I cancel a scheduled phone number porting in Amazon Connect?
Can I cancel a scheduled porting?
**Important**
If you need to cancel or reschedule your porting, let us know immediately.
Depending on the country of service, after a mutually agreed date and time has been provided it can be difficult to cancel.
Because of the coordination required between carriers, Amazon Connect support requires a minimum of 5 business days notice to cancel or reschedule a porting request, if the number has not already been ported. If you need to cancel or reschedule your porting, let us know immediately.
You cannot cancel a port after it has been moved to the RespOrg (Responsible Organization). The port is complete. For this situation, see [Revert phone numbers to your original carrier after porting to Amazon Connect](revert-porting-to-original-carrier.md).
If a porting is successfully cancelled, timelines for the port schedule are reset and the carriers will need to identify another mutually agreed date and time. This will impact the overall timeline for porting your numbers.
**Note**
Please be advised that sometimes a porting request cannot be cancelled because of process automation, but Amazon Connect support will make every attempt possible to stop the request.
# When do I cancel my current telecom service when porting numbers to Amazon Connect?
When do I cancel my current telecom service?
Do not cancel your existing telecom service until your phone numbers have been ported and confirmed working in Amazon Connect.
Canceling your existing telecom service before your number is ported releases your phone number assignment, and may result in you losing the number.
# Guidelines for porting phone numbers to your Amazon Connect project in South Korea
South Korean porting regulations for your Amazon Connect instance
Rules for South Korea differ from those in other countries. To help with requirements in South Korea, here are some helpful hints.
+ When planning your Amazon Connect project in South Korea one of the most important things you will need to do is plan and request information up front. To port numbers in South Korea, you may need to complete and submit more than 5 forms and you may need to engage with the local regulatory authority before approvals are granted to port numbers.
+ All geographic numbers (that is, other than toll-free, national, representative, or 070 VOIP) must be in place on a physical termination for a minimum of 6 months before they can be ported into Amazon Connect. However, if a number has been in place for a minimum of 3 months, you can port it by filing a special request with the Korean Ministry of Telecommunications; upon approval, the porting process can begin. Amazon Connect can provide you with the forms, but you must complete and submit them to the regulator directly.
+ All geographic, representative, or toll-free numbers (GRTFN) are assigned a 070 VOIP number to which the GRTFN terminates and which are associated with the GRTFN at the carrier. Do not remove this 070 number from your Amazon Connect instance until the related GFTN number is removed. If you do, all inbound and outbound calls will fail.
+ Representative numbers (RN) have minimum session billing requirements based on the "attractiveness" of the RN, as determined by the carrier. Representative numbers have different costs depending on the scale of the number. Based on the size of the representative number you order, the service will have from 2 channels to 500 channels minimum to be charged for. This is managed by adding a minimum number of numbers to the account, equal to the number of channels needed. These are shown on the [ Amazon Connect pricing](https://aws.amazon.com/connect/pricing/) page as the shared cost service at \$10.5433 per day of usage for the system. These additional shared cost number DIDs do not have the ability to be assigned call flows, and outbound calls from them will fail. If you disconnect RNs, be sure to also remove their associated Special Numbers to avoid future billing. Removal or reduction of Special Number DIDs without removal of the underlying RN is a violation of Amazon Connect Terms of Service.
# Things to know about Thailand number porting
Things to know about Thailand number porting
Porting in Thailand differs from other countries. Instead of the number being able to directly moved to Amazon Connect, it’s necessary to route the calls from your current provider to Amazon Connect. To help plan for the process here are some helpful hints.
+ Numbers being ported in to Amazon Connect must be from E1 or SIP services only.
+ The E1 or SIP service, along with all associated numbers, must be routed to Amazon Connect's provider's network first. Amazon Connect will help coordinate this. Based on your configuration this may involve additional charges to your current provider or Amazon Connect's provider to support the re-routing.
+ Once the E1 or SIP service has ported to Amazon Connect's provider selected numbers from the service can be activated for use on Amazon Connect. Once activated the numbers will use Amazon Connect for both inbound and outbound calling.
# Porting your phone numbers from your carrier to Amazon Connect
Porting your phone numbers
Porting phone numbers from your existing carrier to Amazon Connect is a multi-step process. It's important to get started several months in advance of your scheduled go-live date, and have all of your documentation in order.
**Topics**
+ [How to port your numbers to Amazon Connect](about-porting.md)
+ [
# Documentation requirements for porting numbers to Amazon Connect
](porting-documentation-requirements.md)
+ [How to verify flows before numbers are ported](verify-flows-before-porting.md)
# How to port your numbers to Amazon Connect
How to port your numbers to Amazon Connect
The following steps are for a typical porting request. This process requires timely communication to make progress. If you take longer than 30 days to respond to requests for information, your porting request may be cancelled, rescheduled, or restarted from the beginning.
**Documentation requirements**: For a list of country-specific requirements for porting numbers, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
## Step 1: Create an Amazon Connect support case
**Important**
If you are porting multiple numbers from different carriers and countries, submit separate tickets for each set of phone numbers to be ported from different carriers and different countries. This streamlines communications, tracking, and the LOA process.
1. Choose [Account and billing](https://console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=service-connect-number-management) to access a pre-populated form in the AWS Support console. You must be signed in to your AWS account to access the form.
1. For **Service**, **Connect (Number Management)** should be selected, as shown in the following image.
![\[The create case page completed for a porting request.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/porting-support1.png)
1. For **Category**, choose **Number Porting North America (US/Canada/Mexico)** or **Number Porting Non-North America**.
1. Select the required severity.
1. Choose **Next step: Additional information**
1. On the **Additional information** page:
1. Enter the subject.
1. Under **Description**, include the following:
+ Amazon Connect instance ARN. For instructions about how to find it, see [Find your Amazon Connect instance ID or ARN](find-instance-arn.md).
If you provide the ARN for a development instance instead of a production instance, you can self-move the phone numbers across instances only if the instances are in the same Region and same AWS account. For limitations and instructions, see [Move an Amazon Connect phone number across instances](move-phone-number-across-instances.md).
+ Phone number. Use E.164 format for example: [\$1][country code][phone number including area code].
If you are porting more than one phone number, provide at least one of the phone numbers you are porting.
+ Exact name of the [flow](connect-contact-flows.md) where the numbers must be [mapped](associate-claimed-ported-phone-number-to-flow.md) after receiving porting approval.
+ Porting Date (yyyy-mm-dd).
**Important**
Porting requests for USA DID and toll-free numbers cannot be submitted with more than 30 days notification.
+ Porting time (hh:mm AM/PM Timezone - 12 hour clock)
+ Your current carrier
+ The contact information for the person authorized to make changes to your current phone service.
**Important**
Do not attach any documents that contain personal information. After we review your case, we'll send you a link to our secured storage (Amazon S3) so you can submit required documents. This is described in [Step 3: Submit the required documents by using a link we provide to you](#step3-porting).
1. Choose **Next step: Solve now or contact us**.
1. On the **Solve now or contact us** page:
1. Choose the **Contact us** tab and select your **Preferred contact language** and your preferred contact method.
1. Choose **Submit**.
1. The Amazon Connect team will review your ticket and get back to you.
## Step 2: Complete Letter of Authorization (LOA)
If the phone number qualifies for porting, the Amazon Connect team will provide you a Letter of Authorization (LOA) to be completed by you. Complete all mandatory fields and sign the LOA.
Along with the LOA, Telecom regulations in many countries require additional documents to register a number, such as proof of business, proof of address, and proof of ID. For a list of country-specific requirements for porting numbers, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
### How to complete an LOA
All portings require the completion of a Letter of Authorization (LOA). The LOA authorizes your current carrier to release your number and allow it to be ported.
+ A separate LOA is required for numbers from each losing carrier.
To complete an LOA, provide the following information:
+ The numbers to port.
+ Information about your current carrier, such as their business name and contact information.
+ Contact information for the person authorized to make changes to your phone service. The name, address, and information you provide on the LOA must match the information on file with your current carrier exactly. To help ensure the porting process goes smoothly, include a copy of the Customer Service Record (CSR) or latest phone bill from your carrier. This will have your name, address, and related telephone numbers on it. Check that the information on your LOA matches your CSR **exactly**.
+ If you have any questions regarding specific details about your current service, consult with your current carrier to ensure the data is accurate. This will minimize the risk that the LOA is rejected.
**Important**
Your LOA form must meet the following criteria:
It must be legible: clearly written or typed.
It must list your company name, the company address, and contact name. This information must match what is on the current carrier's CSR.
It must include a traditional handwritten signature: a physical paper documented signed with pen and ink, also known as a wet signature. Most carriers will reject an electronic or printed signature.
It must be dated within the last 15 days.
If you also want to port toll-free numbers, it must include them as well. Up to 10 toll-free numbers can be listed on the LOA. If you are requesting more than 10 phone numbers be ported, a spreadsheet is required to be attached. Specify "See Attached" on the LOA where the phone numbers would be listed.
It must include only those telephony numbers that belong to the same current carrier and in the same country. If you have multiple current carriers and countries, you will need to submit multiple LOAs.
To further minimize the risk of having your LOA rejected, see [Common reasons why carriers reject an LOA](porting-documentation-requirements.md#why-port-request-rejected).
## Step 3: Submit the required documents by using a link we provide to you
After the Amazon Connect team says you can port phone numbers, you need to submit any required documents. The following steps explain how.
**Note**
AWS Support provides a secure Amazon S3 link for uploading all requested documents. Do not proceed until you receive the link.
**To submit required documents**
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. Sign in to your AWS account, then open the Amazon S3 upload link generated specifically for your account.
**Note**
The link expires after ten days. It is generated specifically for the account that created the case. The link requires an authorized user from the account to perform the upload.
1. Choose **Add Files**, then select the documents required for your request.
1. Expand the Permissions section, and choose **Specify individual ACL permissions**.
1. At the end of the **Access control list (ACL)** section, choose **Add grantee**, then paste the key provided by AWS Support into the **Grantee** box.
1. Under **Objects**, choose the **Read** checkbox, then choose Upload.
After you provide the Letter of Authorization (LOA) and any other required documents, Amazon Connect team confirms with your existing phone carrier that the information on the LOA is correct. If the information provided on the LOA does not match the information that your phone carrier has on file, Amazon Connect team contacts you to update the information provided on the LOA.
## Step 4: The porting request goes to the Amazon Connect carrier
After you have submitted all required documentation, the Amazon Connect team submits the porting request on your behalf to the winning carrier.
+ The losing and winning carrier follow an industry standard process to validate the contents of the LOA and submitted documentation.
+ If the LOA contains discrepancies, it will be rejected and you will need to fix the discrepancies and submit a new LOA.
+ After the carriers successfully validate the LOA, they will either confirm your requested date or provide an available date for the actual porting. This is known as the "mutually agreed date and time."
+ You should validate that the "mutually agreed date and time" is correct.
**Important**
If your LOA contains multiple phone numbers, some numbers may be given different "mutually agreed dates." Check the status and dates/times for each one.
Most carriers require that portings are completed during normal business hours. For country-specific business hours, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
## Step 5: Validate number(s) in the instance, assign the phone number to the flow, request service quota increases
About 3-4 days before the mutually agreed date and time, the Amazon Connect support team loads the phone number that will be ported into the instance ARN you have provided, and then notifies you. Now it's time for you to perform the following steps:
1. Log into your Amazon Connect admin website and validate that your phone number(s) are listed. For instructions, see [List or export to a CSV the phone numbers claimed to your Amazon Connect instance](list-claimed-phone-numbers.md).
1. [Associate the phone number to the desired flow](associate-claimed-ported-phone-number-to-flow.md) so the phone number will be ready to receive phone calls after the porting is completed. If you require assistance assigning multiple phone numbers to flows, let us know in your support request.
**Important**
It is expected that you or your partner associate your phone number to the flow.
If you want AWS Support to do this on your behalf, note this in your support ticket. You must specify the flow name/ARN to be matched to each phone number.
You or your partner must validate that the correct flow has been associated with each phone number.
1. [Submit a service quota request](amazon-connect-service-limits.md) at least five days in advance of the mutually agreed date for any changes to your service quotas required to support your use case. For example, you may need to increase the number of concurrent calls per instance, or enable countries for outbound calling.
## Step 6: Checklist of activities on your porting date
The action of porting a number can be disruptive: the process involves updating the routing of phone numbers between carriers across a country or Region, including carriers not involved in the actual porting. In rare cases it can take several hours before all routes across all Telecom carriers are fully updated.
### Steps you perform to minimize disruption to your phone services
On the mutually agreed port date and time, perform the following steps:
+ Double-check that the activities listed in [Step 5](#step4-porting) have been completed:
1. Verify that the number(s) you had ported are in the requested Amazon Connect instance, and they have been assigned to the appropriate flow.
1. Verify that any required service quota increases or changes for your Amazon Connect instance were implemented. For example, increase the number of concurrent calls per instance, or enable countries for outbound calling.
+ Monitor call traffic from your existing contact center to confirm that incoming traffic has stopped.
+ Place test calls to your Amazon Connect instance to verify calls are being routed to the correct flows.
+ Ensure agents are logged in to the Contact Control Panel (CCP) and can answer calls as they are received.
+ Monitor call traffic to your Amazon Connect instance to confirm that you are receiving the expected levels of traffic.
### Steps the Amazon Connect team performs to ensure a smooth transition
1. After the Amazon Connect team receives confirmation that the porting has been completed, we will perform final testing to confirm that the porting was successful and the phone number is receiving calls to Amazon Connect.
1. After we have completed our testing, we will notify you and ask you to verify the successful completion of the porting.
# Documentation requirements for porting numbers to Amazon Connect
The Letter of Authorization (LOA) is an industry standard document type used by carriers to authorize the transfer of a phone number from one carrier to another. In many cases, the LOA is specific to the country or region, carrier, or porting relationship between the losing and winning carriers.
If your number can be ported, the Amazon Connect team will provide you with the following:
+ An LOA form appropriate for the situation.
+ A link to a secure Amazon S3 storage so you can upload the LOA and any other required documents.
For more information, see [How to complete an LOA](about-porting.md#how-to-complete-loa).
Additionally, regulations in some countries require a local business address and specific documentation to use a phone number. For country specific requirements, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md). If this is required, we will ask for this information to be submitted with the completed LOA.
## Common reasons why carriers reject an LOA
Common reasons why carriers reject an LOA
There are four common reasons that an LOA may be initially rejected by the losing carrier:
+ Unsatisfactory business relationship
This usually means that you have an unpaid balance or the carrier charges a port away fee. After you pay the bill or fee to your carrier, we will resubmit the port request.
+ Name or address mismatch
The information you submitted on your Letter of Authorization (LOA) is different from what's on file with your carrier in their Customer Service Record (CSR). To fix this, contact your existing carrier to update your CSR information, obtain the correct CSR information, or both. Let us know when they update your information and we will resubmit the port request. Or, send us a new LOA with the correct information as provided by your existing carrier.
+ Number cannot be ported
We will work with all Amazon Connect carriers in a Region to support the porting of your numbers. In some cases, however, specific numbers may not be portable because of regulatory restrictions or carrier limitations. In these situations, consider claiming a new number from Amazon Connect.
+ Missing information
One or more fields have been left blank on the LOA. This may include a missing signature, phone number, address information, or other requested information. Review all LOAs before submitting them to ensure that you have filled out all requested data. After the LOA is updated with all the required information, we will resubmit the port request.
# Verify flows before porting numbers to Amazon Connect
How to verify flows before numbers are ported
We recommend that you test your call flows before the mutually agreed date and time of porting. If you would like to test your call flows, we recommend that you claim a direct inward dial (DID) or toll-free phone number available within Amazon Connect and assign it to the call flow for testing.
When you are done testing, you can release the number from your instance so you will no longer be charged for it. For instructions, see [Release a phone number from Amazon Connect back to inventory](release-phone-number.md).
Until you release the number, you are charged the daily rate associated with claiming a phone number and the per minute rate for telephony minutes used. For more information see the standard pricing for [Amazon Connect service usage and associated telephony rates](https://aws.amazon.com/connect/pricing/).
# Troubleshoot issues after porting phone numbers to Amazon Connect
After the porting process completes
After you have ported your numbers to Amazon Connect, use the topics in this section to troubleshoot issues, or to release numbers you no longer need after porting.
**Topics**
+ [What to do if the ported number isn't receiving calls](not-receiving-calls-after-porting.md)
+ [Release ported numbers you no longer need](release-ported-numbers-you-do-not-need.md)
+ [Revert to original carrier after porting](revert-porting-to-original-carrier.md)
+ [Port numbers away](port-away.md)
# Not receiving calls on the phone number ported to Amazon Connect
What to do if the ported number isn't receiving calls
After the scheduled porting window has completed, if you are not receiving phone calls on the ported phone number, update your support ticket. We will troubleshoot with our carrier to verify the porting status and identify the next steps to resolve issue.
Amazon Connect and our carriers make every effort to ensure number porting occurs with minimal downtime and without issues. In most cases, the losing carrier is responsible for initiating the number porting and releasing your number to the winning carrier.
In rare situations, a number routing issue can occur, resulting in calls not arriving to Amazon Connect from the carrier.
# Release numbers that you ported to Amazon Connect that you no longer need
Release ported numbers you no longer need
You do not have to keep phone numbers assigned to your Amazon Connect instance.
When a phone number is released from your Amazon Connect instance:
+ You will no longer be charged for it.
+ You cannot reclaim the phone number.
+ Amazon Connect reserves the right to allow it to be claimed by another customer.
**To release a phone number**
1. Log in to Amazon Connect admin website with an Admin account or a user account that has **Phone numbers - Release** security profile permission.
1. On the navigation menu, choose **Channels**, **Phone numbers**. This option appears only if you have the **Phone numbers - View** permission in your security profile.
1. Choose the phone number you want to release, and then choose **Release**. This option appears only if you have the **Phone numbers - Release** permission in your security profile.
If the phone number is associated with a flow, that flow will be deactivated until another number is associated with it.
When customers call the phone number you have released, they will get a message that it is not a working phone number.
# Revert phone numbers to your original carrier after porting to Amazon Connect
Revert to original carrier after porting
To complete the porting, the losing and gaining carriers both make configuration changes to pass the phone number ownership. After the porting is complete, the gaining carrier has sole control of the phone number.
To move the phone number again, you must complete a new LOA and any required documentation.
# Port phone numbers away from Amazon Connect
Port numbers away
1. Choose [Account and billing](https://console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=service-connect-number-management&categoryCode=phone-number-port-out) to go to the pre-populated form in the AWS Support console. You must be signed in to your AWS account to access the form.
1. For **Service**, *Connect (Number Management)* should be selected.
1. For **Category**, *Phone Number Port Out* should be selected.
1. Select the required severity.
1. Choose **Next step: Additional information**
1. On the **Additional information** page:
1. Enter the subject.
1. Under **Description**:
1. Let us know you're porting away.
1. The name of your Amazon Connect instance and the numbers you are porting away.
1. The name of your new carrier.
1. Choose **Next step: Solve now or contact us**.
1. On the **Solve now or contact us** page:
1. Choose the **Contact us** tab and select your **Preferred contact language** and your preferred contact method.
1. Choose **Submit**.
1. The Amazon Connect team will review your ticket and get back to you.
Here's what happens next:
1. AWS Support contacts you, indicating that you should begin the process with the winning carrier.
1. The winning carrier will request that you provide them with following information:
+ Proof of ownership of the numbers you want to port away. Provide them with screenshots of the Amazon Connect instance with the phone numbers you want to port away, and screenshots of your AWS bill.
+ Usually the winning carrier will require a LOA (Letter of Authorization) that you need to complete. It's important that you provide the correct contact details from your AWS bill.
1. The winning carrier will send the request to AWS Support.
1. AWS Support will verify that the request from the winning carrier matches the information we have about who owns those numbers. If all details match **exactly**, we will approve the request.
**Important**
Verifying the authenticity of the winning carrier's port-out request is critical for the security of your phone number. If the contact details are not correct (for example, there's a name mismatch), your port-out request may be rejected, causing delays and requiring you to resubmit your request.
1. The winning carrier will complete the port-out request on the date and time that you establish with them. Work with the winning carrier to complete the remainder of the port-out process to ensure a seamless transition.
# Claim and manage your phone numbers in Amazon Connect
Claim and manage your phone numbers
The topics in this section explain how to claim an Amazon Connect phone number, list phone numbers claimed to your instance, move a phone number across Amazon Connect instances, and release a phone number.
**Topics**
+ [Claim a phone number in your country](get-connect-number.md)
+ [Request an SMS-enabled phone number through AWS End User Messaging SMS](sms-number.md)
+ [Claim a phone number you already own in another country](another-country.md)
+ [List phone numbers claimed to your instance](list-claimed-phone-numbers.md)
+ [Claim phone numbers for Asia Pacific (Tokyo)](connect-tokyo-region.md)
+ [Request numbers or international numbers](number-request.md)
+ [Move a phone number across instances](move-phone-number-across-instances.md)
+ [Release a phone number](release-phone-number.md)
# Get a local toll-free or DID Amazon Connect phone number
Claim a phone number in your country
To place or receive calls in your Amazon Connect instance, you need to claim a DID or toll-free phone number. If you did not claim a phone number when you created your Amazon Connect instance, follow these steps to claim one now.
## Claim a number for your contact center
Claim a number for your contact center
1. Log in to the Amazon Connect admin website with an Admin account, or an account assigned to a security profile that has **Phone numbers - Claim** permissions.
1. On the navigation menu, choose **Channels**, **Phone numbers**.
1. Choose **Claim a number**. You can choose a toll-free number or a Direct Inward Dialing (DID) number. If you're in the US, you can specify the area code you want for your number, and only available numbers with that area code will be displayed. When numbers are returned, choose one.
![\[The Claim phone number page, DID (Direct Inward Dialing) tab.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tutorial1-claim-number.png)
**Note**
Create a case by choosing the [Account and billing](https://support.console.aws.amazon.com/support/home#/case/create) option for these situations:
If you select a country or region, but no numbers display, you can request additional numbers for the country or region.
If you want to request a specific area code or prefix that you don't see listed, we'll try to accommodate your request.
The following image shows the **Account and billing** option on the **Create a case** page of the **Support Center** console.
![\[The Account and billing option on the Create a case page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-case-support.png)
1. Enter a description for the number and, if required, attach it to a contact flow in **Flow / IVR**.
1. Choose **Save**.
1. Repeat this process until you have claimed all your required phone numbers.
1. After you claim your numbers, [associate them with your flow(s)](associate-claimed-ported-phone-number-to-flow.md). A flow defines the customer experience with your contact center from start to finish.
## How many phone numbers you can claim
How many phone numbers you can claim
There is a service quota for how many phone numbers you can have in each instance. For the default service quota, see [Amazon Connect service quotas](amazon-connect-service-limits.md). If you reach your quota, but want a different phone number, you can release one of your previously claimed numbers. You cannot claim the same phone number after releasing it.
If you need more phone numbers, you can request a service quota increase using the [Amazon Connect service quota increase form](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase&limitType=service-code-connect).
## Avoid being blocked from claiming or releasing too many numbers
Avoid being blocked from claiming or releasing too many numbers
If you plan to claim and release numbers frequently, contact us for a service quota exception. Otherwise, it's possible you will be blocked from claiming and releasing any more numbers until up to 180 days past the oldest number released has expired.
By default you can claim and release up to 200% of your maximum number of active phone numbers. If you claim and release phone numbers using the UI or API during a rolling 180 day cycle that exceeds 200% of your phone number service level quota, you will be blocked from claiming any more numbers until 180 days past the oldest number released has expired.
For example, if you already have 99 claimed numbers and a service level quota of 99 phone numbers, and in any 180 day period you release 99, claim 99, and then release 99, you will have exceeded the 200% limit. At that point you are blocked from claiming any more numbers until you open an AWS support ticket.
## API instructions for claiming phone numbers
API instructions
To claim a phone number programmatically:
1. Use the [SearchAvailablePhoneNumbers](https://docs.aws.amazon.com/connect/latest/APIReference/API_SearchAvailablePhoneNumbers.html) API to search for available phone numbers that you can claim to your Amazon Connect instance.
1. Use [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) API to claim the phone number.
Claiming a number by using the [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) API puts the number in one of the following three states: `CLAIMED`, `IN_PROGRESS`, `FAILED`.
1. Run the [DescribePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribePhoneNumber.html) API to determine the status of your number claiming process.
+ `CLAIMED` means the previous [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) or [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) operation succeeded.
+ `IN_PROGRESS` means a [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) or [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) operation is still in progress and has not yet completed. You can call [DescribePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribePhoneNumber.html) at a later time to verify if the previous operation has completed.
+ `FAILED` indicates that the previous [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) or [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) operation has failed. It will include a message indicating the failure reason. A common reason for a failure may be that the `TargetArn` value you are claiming or updating a phone number to has reached its limit of total claimed numbers. If you received a `FAILED` status from a `ClaimPhoneNumber` API call, you have one day to retry claiming the phone number before the number is released back to the inventory for other customers to claim.
**Note**
You will not be billed for the phone number during the 1-day period if number claiming fails.
## "We couldn't claim your number"
"We couldn't claim your number"
Even if it's the first time you've claimed a phone number, it's possible to get this error message when you attempt to claim a number. All the issues that cause this error message require help from AWS Support to resolve.
Contact AWS Support and they will provide assistance. For instructions, see [Get administrative support for Amazon Connect](get-admin-support.md).
# Request an SMS-enabled phone number through AWS End User Messaging SMS
Request an SMS-enabled phone number through AWS End User Messaging SMS
**Important**
Some countries require phone numbers and sender IDs to be registered for use in the country. It can take up to 15 business days to process a registration request after it is submitted. We strongly recommend you begin this process early. For more information about registering, see [Registrations](https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations.html).
Using AWS End User Messaging SMS, you can request new SMS-enabled phone numbers or reuse existing SMS-enabled phone numbers for use in Amazon Connect. You can request short codes, 10-digit long codes (10DLC), and toll-free numbers. These are also known as Origination Identities (OIDs).
For instructions about procuring a number for SMS messaging, see [Requesting a phone number](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-request.html) in the *AWS End User Messaging SMS User Guide*.
## Best practices for requesting SMS numbers
Best practices
+ Each type of OID has a different registration process and the leasing costs vary. Review the pricing here: [AWS End User Messaging SMS pricing](https://aws.amazon.com/pinpoint/pricing/#Numbers).
+ When deciding what type of phone number to request, we recommend considering your throughput needs. SMS messages are delivered in 140-byte sections known as [message parts](https://docs.aws.amazon.com/sms-voice/latest/userguide/sms-limitations-mps.html). Your throughput rate is the number of message parts that you can send each second.
+ **1–3 message parts per second**: Use a toll-free number. We recommend using a 10DLC number or short code if your throughput needs will exceed these limits as you expand your use cases. These number types provide plenty of room for growth, but also cost more and currently take longer to obtain than a toll-free number. For more information about requesting a toll-free number in Amazon Pinpoint, see [Requesting a phone number](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-request.html).
+ **10–75 message parts per second**: Use a 10DLC number. You can also use a short code, which would provide additional room for growth, but would also cost more. For more information, see [Requesting dedicated long codes for SMS messaging with Amazon Pinpoint SMS](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-long-code.html).
+ **100 message parts per second or more**: Use a short code. When you create your request in the AWS Support Center Console, specify the throughput rate that you want your short code to support.
By default US short codes support 100 message parts per second, but the throughput rate can be increased beyond that rate for an additional monthly fee. For more information, see [Requesting short codes for SMS messaging with Amazon Pinpoint SMS](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-request-short-code.html).
+ Request at least one of the above OIDs as a `TRANSACTIONAL` number from Amazon Pinpoint.
+ Be sure to provide all of the information requested during the registration process. There are no exceptions to the questions being asked.
**Important**
Providing incomplete or inaccurate information will increase the registration time. Your registration will need to be edited and returned to be reviewed again.
Registration for all types of OIDs in the US are managed by a third-party registrar. Amazon does not review applications.
+ Toll-free phone number registration requires the least amount of time to procure.
+ Review the [10DLC registration process](https://docs.aws.amazon.com/sms-voice/latest/userguide/registration-10dlc.html) explained in the *AWS End User Messaging SMS User Guide*.
# Claim for Amazon Connect a phone number you already own in another country
Claim a phone number you already own in another country
Let's say your business is located in Germany. You also have agents in Japan to serve customers who live there, and you need a Japanese phone number for that contact center. To claim a phone number that you already own in another country, use the following steps to create a support case.
To claim a number that you don't already own in another country or Region, see [Request numbers or international numbers for Amazon Connect](number-request.md).
1. Go to [Create case](https://console.aws.amazon.com/support/cases#/create).
1. Choose **Service quota increase**.
1. In **Limit type** select **Amazon Connect**.
1. In **Use case description**, provide the address of your business that's located in the other country.
1. In **Contact options**, choose whether we should contact you by email or phone.
1. Choose **Submit**.
We'll contact you to help with your request.
# List or export to a CSV the phone numbers claimed to your Amazon Connect instance
List phone numbers claimed to your instance
You can list the phone numbers claimed to your Amazon Connect instance by using the Amazon Connect admin website, or by using the [ListPhoneNumbersV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListPhoneNumbersV2.html) API.
**To list phone numbers by using the Amazon Connect admin website**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/.
1. On the navigation menu, choose **Channels**, **Phone numbers**.
The list of phone numbers claimed to your Amazon Connect instance is displayed.
**To download phone numbers to a CSV file**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/.
1. On the navigation menu, choose **Channels**, **Phone numbers**, **Download CSV**.
+ ALL of the phone numbers listed on that page are downloaded to the CSV file, regardless of which ones are selected.
+ It does not download all of the phone numbers claimed by your Amazon Connect instance.
+ To download numbers listed on a page 2 of results, you need to paginate to page 2 and then choose **Download CSV** again.
![\[The Phone numbers page, the Download CSV button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/download-phonenumbers-csv.png)
# Claim phone numbers for Amazon Connect in the Asia Pacific (Tokyo) Region
Claim phone numbers for Asia Pacific (Tokyo)
To claim a phone number for an Amazon Connect instance you create in the Asia Pacific (Tokyo) Region, open an AWS support case and provide documentation that your business is located in Japan.
**Important**
You must provide three pieces of required documentation. For a list of acceptable identification, see [Japan (JP)](phone-number-requirements.md#japan-requirements), in the [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md) topic.
You cannot claim numbers for personal use, only for business use.
Amazon Connect supports claiming the following phone numbers for instances created in the Asia Pacific (Tokyo) Region.
+ **Direct Inward Dialing (DID) numbers**—DID numbers are also referred to as local numbers.
+ 050 prefix numbers.
+ 03 prefix for numbers in Tokyo.
+ 06 prefix for numbers in Osaka.
+ **Toll Free numbers**
+ 0120 prefix numbers.
+ 0800 prefix numbers.
Amazon Connect does not offer phone numbers for other cities in Japan at this time.
**Note**
When you claim a toll free phone number for Amazon Connect, there is no corresponding DID number with a 03 prefix also assigned, as with other toll free numbers in Japan. If you need to use a DID number, you can claim one in Amazon Connect.
# Request numbers or international numbers for Amazon Connect
Request numbers or international numbers
**Important**
To purchase and own a phone number, country or region regulations often require:
A local office address.
Specific identification documents.
For identification requirements by country, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
In most countries it takes 2-6 weeks for us to fulfill your request. In some cases it can take up to 60 days. If you need a number by a certain date, let us know in your AWS Support case.
**Note**
Amazon does not provide the following:
Premium rate or higher cost services
Vanity numbers such as 1-888-555-0000 or an exact number
If you want these services we recommend you contract with specialist providers. For premium rate services you can route calls into Amazon Connect DIDs following local country regulations. For vanity numbers, after you've purchased them you can move these numbers across to Amazon Connect by porting them.
To request international phone numbers that require documentation, or numbers not available within a specific region, create an AWS Support case. In the support case, you must specify exactly how many numbers you want for each country.
Submit an Amazon Connect support ticket to verify if your phone number can be ported to Amazon Connect.
1. Choose [Account and billing](https://console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=service-connect-number-management) to access a pre-populated form in the AWS Support console. You must be signed in to your AWS account to access the form.
1. For **Service**, **Connect (Number Management)** should be selected.
1. For **Category**, **Special Phone Number Request** should be selected.
1. Select the required severity.
1. Choose **Next step: Additional information**
1. On the **Additional information** page:
1. Enter the subject.
1. Under **Description**, include as much information as possible about your request. If you don't know all of these details, you can leave information out.
**Important**
Do not attach any documents that contain personal information. After we review your case, we'll send you a link to our secured storage (Amazon S3) so you can submit the required documents. This is described in step 10 below.
1. Choose **Next step: Solve now or contact us**.
1. On the **Solve now or contact us** page:
1. Choose the **Contact us** tab and select your **Preferred contact language** and your preferred contact method.
1. Choose **Submit**.
1. The Amazon Connect team will review your ticket and get back to you. They will provide a link to our secured storage (Amazon S3) so you can submit the required documents.
After your request is approved, the exact number of requested phone numbers appear in your Amazon Connect console for you to claim. You won't have access to all available numbers in that country.
# Move an Amazon Connect phone number across instances
Move a phone number across instances
You can move a phone number from one Amazon Connect instance or traffic distribution group to another Amazon Connect instance or traffic distribution group in the same AWS account and Region, different AWS accounts, or different Regions.
Amazon Connect supports the following scenarios for migrating phone numbers:
+ Both Amazon Connect instances are in the same AWS Region and AWS account. In this scenario, you can move the numbers yourself.
+ The old and new Amazon Connect instances are in different Regions, but same account. AWS Support must migrate the numbers for you.
+ The old and new Amazon Connect instances are in same AWS Regions but different AWS accounts. AWS Support must migrate the numbers for you.
**Topics**
+ [
## Important things to know
](#move-number-important)
+ [
## Self-move: same Region and AWS account
](#move-number-same-region-account)
+ [
## Different Regions and/or AWS account
](#move-number-different-region-account)
## Important things to know
Important things to know
The following information applies to phone number migrations that are performed by AWS Support.
+ If your new instance ARN belongs to traffic distribution group, you need to provide AWS Support with the instance and traffic distribution group ARNs. To obtain the traffic distribution group ARN, run a [list-traffic-distribution-groups](https://docs.aws.amazon.com/cli/latest/reference/connect/list-traffic-distribution-groups.html) CLI command.
+ AWS Support can schedule migrations anytime between Monday and Friday. Exceptions to this are local National Holidays when no phone number migrations can be scheduled.
+ When the migration date and time arrives, you must make sure the phone number is no longer configured as the outbound callback number on any of your queues. Otherwise, this will prevent AWS Support from migrating the number and it may delay the process.
+ The migration of each phone number takes between 20-30 minutes. During a phone number migration, **calls may be blocked and may fail for the number being migrated**.
+ To eliminate additional downtime, if you're associating a flow to a migrated phone number in the new Amazon Connect instance, make sure the flow exists and is published in the new Amazon Connect instance. Provide AWS Support with the flow ARN so they can associate it with the phone number when they do the migration.
+ Depending on the phone number, migration might not be possible. You'll be contacted through your AWS Support case if this applies to your request. Refer to the [Amazon Connect Telecoms Country Coverage Guide](https://d1v2gagwb6hfe1.cloudfront.net/Amazon_Connect_Telecoms_Coverage.pdf) for regional availability of phone numbers in certain countries.
+ After your phone number is migrated, you must set the outbound number on your queues. This cannot be done by AWS Support.
AWS Support will request that you acknowledge and understand the above information before they schedule your phone number migration.
## Self-move: same Region and AWS account
Self-move: same Region and AWS account
When both Amazon Connect instances are in the same Region and AWS account, you can move the phone number yourself by using the [ListPhoneNumbersV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListPhoneNumbersV2.html) and [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) APIs.
**Note**
If you receive errors when running AWS CLI commands, make sure that you're using the [most recent AWS CLI version](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-troubleshooting.html).
For instructions and sample CLI commands, see [How do I migrate phone numbers from one Amazon Connect instance to another?](https://repost.aws/knowledge-center/connect-migrate-phone-number)
## Different Regions and/or AWS account
Different Regions and/or AWS account
When the old and new Amazon Connect instances are located in different Regions, but the same AWS account, complete the following steps to create a single AWS Support case.
When the old and new Amazon Connect instances belong to different AWS accounts, create two AWS Support cases, one from each account, following the same steps.
1. Sign in to your AWS account and then click [here](https://console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=service-connect-number-management) to access a pre-populated form in the AWS Support console.
1. In the form, for **Service**, select **Connect (Number Management)**.
1. For **Category**, select **Phone Number Migration**.
1. Choose the appropriate severity.
1. Choose **Next step: Additional information**.
1. On the **Additional information** page:
1. Enter the subject.
1. Under **Description**, include as much information as possible about your request, including the phone numbers (in E164 format) and a flow, if you want Support to assign your numbers after the migration completes.
1. Under **Help us resolve your case faster**, provide all of the required information such as the source and destination instance ARNs and your desired migration date and time, including timezone.
1. Choose **Next step: Solve now or contact us**.
1. On the **Solve now or contact us** page:
1. Choose the **Contact us** tab and select your **Preferred contact language** and your preferred contact method.
1. Choose **Submit**.
1. The Amazon Connect team will review your ticket and get back to you.
# Release a phone number from Amazon Connect back to inventory
Release a phone number
If you want a different phone number, or have extra numbers that you aren't using, you can release them back to inventory. You can do this using the Amazon Connect console, or programmatically by using the [ReleasePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReleasePhoneNumber.html) API.
When a phone number is released from your Amazon Connect instance:
+ You will no longer be charged for it.
+ You cannot reclaim the phone number.
+ Amazon Connect reserves the right to allow it to be claimed by another customer.
**Tip**
If you want to close your Amazon Connect account, do these steps for all of your phone numbers. This will ensure you aren't billed if people erroneously call numbers that you've claimed, and initiate your flows. You may also want to [delete your instances.](delete-connect-instance.md)
**To release a phone number**
1. Log in to Amazon Connect admin website with an Admin account or a user account that has **Phone numbers - Release** security profile permission.
1. On the navigation menu, choose **Channels**, **Phone numbers**. This option appears only if you have the **Phone numbers - View** permission in your security profile.
1. Choose the phone number you want to release, and then choose **Release**. This option appears only if you have the **Phone numbers - Release** permission in your security profile.
If the phone number is associated with a flow, that flow will be deactivated until another number is associated with it.
When customers call the phone number you have released, they will get a message that it is not a working phone number.
**To use the ReleasePhoneNumber API**
+ Releasing a number by using the [ReleasePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReleasePhoneNumber.html) API puts the number in a cool down period for up to 180 days. The phone number cannot be searched for or claimed until after the cool down period ends.
**Note**
You will not be billed for the phone number during the 180-day cool down period.
## Avoid being blocked from claiming or releasing too many numbers
Avoid being blocked from claiming or releasing too many numbers
If you plan to claim and release numbers frequently, contact us for a service quota exception. Otherwise, it's possible you will be blocked from claiming and releasing any more numbers until up to 180 days past the oldest number released has expired.
By default you can claim and release up to 200% of your maximum number of active phone numbers. If you claim and release phone numbers using the UI or API during a rolling 180 day cycle that exceeds 200% of your phone number service level quota, you will be blocked from claiming any more numbers until 180 days past the oldest number released has expired.
For example, if you already have 99 claimed numbers and a service level quota of 99 phone numbers, and in any 180 day period you release 99, claim 99, and then release 99, you will have exceeded the 200% limit. At that point you are blocked from claiming any more numbers until you open an AWS support ticket.
# Use caller identification to personalize customer interaction
Use caller identification to personalize customer interaction
You can provide a personalized experience for your customers by using metadata attributes that provide information related to call origination. For example, you can look up a customer's contact ID, and welcome them with a personalized greeting.
**Important**
Features that are provided by Amazon Connect or third parties may rely on call data for identifying inbound callers for personalizing customer interaction or detecting fraud and may be subject to additional terms and conditions. Network-related call data that is not displayed to call recipients may not be used for any purpose other than fraud detection.
## Use telephony call metadata attributes
Use telephony call metadata attributes
The following table lists the available telephony call metadata attributes. For information about using attributes, see [Use Amazon Connect contact attributes](connect-contact-attributes.md).
| Attribute | Description | Type | JSONPath Reference |
| --- | --- | --- | --- |
| P-Charge-Info | The party responsible for the charges associated with the call. | System | \$1.Media.Sip.Headers.P-Charge-Info |
| From | The identity of the end user associated with the request. | System | \$1.Media.Sip.Headers.From |
| To | Information about the called party or the recipient of the request. | System | \$1.Media.Sip.Headers.To |
| ISUP-OLI | Originating Line Indicator (OLI). Shows the type of line placing call (for example, PSTN, 800 service call, wireless/cellular PCS, payphone). | System | \$1.Media.Sip.Headers.ISUP-OLI |
| JIP | Jurisdiction Indication Parameter (JIP). Indicates geographic location of caller/switch. Example value: 212555 | System | \$1.Media.Sip.Headers.JIP |
| Hop-Counter | Hop Counter. Example value: 0 | System | \$1.Media.Sip.Headers.Hop-Counter |
| Originating-Switch | Originating Switch. Example value: 710 | System | \$1.Media.Sip.Headers.Originating-Switch |
| Originating-Trunk | Originating Trunk. Example value: 0235 | System | \$1.Media.Sip.Headers.Originating-Trunk |
| Call-Forwarding-Indicator | Call Forwarding Indicators (for example, Diversion header). Indicates domestic or international origin of call. Example value: sip:\$115555555555@public-vip.us2.telphony-provider.com;reason=unconditional | System | \$1.Media.Sip.Headers.Call-Forwarding-Indicator |
| Calling-Party-Address | Calling Party Address (number). NPAC dip shows true line type and native geographic switch. Example value: 15555555555;noa=4 | System | \$1.Media.Sip.Headers.Calling-Party-Address |
| Called-Party-Address | Called Party Address (number). Example value: 15555555555;noa=4 | System | \$1.Media.Sip.Headers.Called-Party-Address |
| SIPREC metadata | SIPREC metadata XML received by Amazon Contact Lens connector | System | \$1.Media.Sip.SiprecMetadata |
## Troubleshoot issues
Troubleshoot issues
The availability of telephony metadata is not consistent across all telephony providers and may not be available in all cases.
Before opening an AWS Support case:
+ If you are missing data on all calls required by a third-party Amazon Connect Ready service, check that you followed the service configuration guide provided by the third party.
If you need to open a AWS Support case, provide the following information:
+ **Service** = **Amazon Connect**
+ **Quota** = **3rd-Party Number Mapping**
+ **Case description** box:
+ State that you have confirmed you have a phone number with the required setup.
+ Enter the name of your Amazon Connect Ready service provider
+ Describe the telecoms metadata issue you are encountering.
The following images show an example case and where you enter this information.
![\[The AWS Support case for requesting third-party number mapping.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/3rd-party-mapping.png)
![\[The case description box for requesting help with third-party number mapping.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/case-description.png)
+ If you're getting partial data on a percent of calls as part of normal service calls: Note that data is not available on all calls.
Certain fields, such as ISUP-OLI, are only present based on specific routes through networks. It's not possible to guarantee data will be available for all calls.
# Map third-party numbers to your Amazon Connect account
Third-party numbers
In some countries you may need to obtain a third-party phone number that is hosted directly by a carrier in that country instead of being hosted by Amazon Connect. The carrier is interconnected with Amazon Connect and provides billing services. In these situations you need to open a ticket to AWS Support to map your AWS account ID and Amazon Connect instance to the phone number.
**To map third-party numbers to your account**
Submit an Amazon Connect support ticket to map third-party numbers. Following are instructions if you don't have an AWS Support account.
1. Go to [Support Center](https://console.aws.amazon.com/support/home) and choose **Create a case**.
1. Choose **Account and billing**.
1. In the **Service** box, use the dropdown list to choose **Connect (Number Management)**.
1. In the **Category** box, choose **3rd Party Mapping**.
1. In the **Severity** box, select the severity for your situation.
1. Choose **Next step: Additional information**.
1. On the **Additional information** page:
1. Enter the subject.
1. Under **Description**, include as much information as possible about your request, such as your instance ARN, phones numbers, flows, and more.
**Important**
Do not attach any documents that contain personal information. After we review your case, we'll send you a link to our secured storage (Amazon S3) so you can submit the required documents. This is described in step 12 below.
1. Under **Help us resolve your case faster**, provide all of the required information.
1. Choose **Next step: Solve now or contact us**.
1. On the **Solve now or contact us** page:
1. Choose the **Contact us** tab and select your **Preferred contact language** and your preferred contact method.
1. Choose **Submit**.
1. The Amazon Connect team will review your ticket and get back to you. They will provide a link to our secured storage (Amazon S3) so you can submit required documents.
# Amazon Connect support of the inbound only UIFN service
UIFN service support - Inbound only
A Universal International Freephone number (UIFN) is a unique **inbound only** freephone number that can be used throughout the world. It provides toll-free calling from international locations to your contact center.
Amazon Connect supports UIFN in more than [60 countries](#list-of-uifn-countries) that are registered with the International Telecommunications Union, an organization that supports the administration of the UIFN service.
**Note**
Amazon Connect allows you to enable UIFNs in as many countries as you need, however, it requires a minimum of 5 countries.
A UIFN is composed of a 3-digit country code for a global service application, such as **800**, and an 8-digit Global Subscriber Number (GSN). This results in an 11-digit fixed format.
For example, your UIFN could be \$1800 12345678, where 12345678 is your number.
Due to the special nature of UIFN, attempting to call a UIFN from Amazon Connect in a "loopback mode" is not supported. UIFNs are designed to be called from end phone configurations in the country's public telephone network.
## How to get a UIFN
How to get a UIFN
To request a UIFN within a specific AWS Region, create an AWS Support case. In the support case, provide the following information.
+ Choose the countries you want to enable from the [list of available countries](#list-of-uifn-countries).
+ The Amazon Connect instance(s) associated with the new UIFN numbers. Amazon Connect can support routing numbers to multiple Regions, such as Australia to the Asia Pacific (Sydney) Region, United States to a US Region, or if desired to a single global instance.
+ The required ID verification for your country. Most countries subscribe to [standard ID verification requirements](phone-number-requirements.md#uifn-requirements) for ordering UIFN numbers. However, we recommend checking [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md) for your country to be sure.
For number portability, after you open a case, Amazon will provide you with *Service Provider Change Authorization and Designation of Agency* document.
Amazon Connect can route UIFNs to multiple AWS Regions. For example, if a UIFN is enabled for Australia, it can be routed to your Amazon Connect instance that is located in the Asia Pacific (Sydney) Region. If a UIFN is enabled for **more** countries, each country can be routed to your Amazon Connect instance, which may be in any supported AWS Region.
The following image shows the body of a sample UIFN request submitted to AWS Support. This request is for two UIFNs. The first is for a UIFN that is enabled for Argentina, Brazil, and Colombia, and connected to an Amazon Connect instance in the US West (Oregon) Region. The second request is for a UIFN that is enabled for Japan, Australia, and New Zealand and connected to an Amazon Connect instance located in the Asia Pacific (Singapore) Region.
![\[A support case requesting two UIFNs.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/uifn-example-request.png)
**Important**
**UIFN is an inbound-only service**. Before opening a ticket to request a UIFN:
Ensure you understand that this number cannot be used for outbound.
Check the National reachability of the country in the following section.
Full National reachability means the UIFN reaches all local (in-country) networks. UIFNs in some countries have limited reachability and will only work with specific carriers/networks where you need to use different codes to dial the number (for example, Japan).
## Countries that support UIFNs
Countries that support UIFNs
| Country | How to dial a UIFN and Reachability | How many days it takes a UIFN to be set up |
| --- | --- | --- |
| Argentina | 00-800-XXXX-XXXX National reachability: all fixed networks | 10-25 |
| Australia | 0011-800-XXXX-XXXX National reachability: Optus, Telstra, Vodafone mobile | 10-30 |
| Austria | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Belgium | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Brazil | 0021-800-XXXX-XXXX National reachability: full Activation of international direct dialing service is required for calling parties for both fixed and mobile lines. The subscriber must have enabled the use of Embratel/Claro's international selection code (0021). | 20-30 |
| Bulgaria | 00-800-XXXX-XXXX National reachability: full | 10-20 |
| Canada | 011-800-XXXX-XXXX National reachability: full Calling from payphones is not supported. | 20-40 |
| China | 00-800-XXXX-XXXX National reachability: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/uifn-service.html) | 20-40 |
| Colombia | Dialing format: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/uifn-service.html) National reachability: full | 30-60 |
| Costa Rica | 00-800-XXXX-XXXX National reachability: full | 15-30 |
| Croatia | 00-800-XXXX-XXXX National reachability: all fixed; T-Mobile network | 20-30 |
| Czech Republic | 00-800-XXXX-XXXX National reachability: full | 20-30 |
| Denmark | 00-800-XXXX-XXXX National reachability: full | 10-20 |
| Estonia | 00-800-XXXX-XXXX National reachability: full | 15-25 |
| France | 00-800-XXXX-XXXX National reachability: full, including Monaco | 10-15 |
| French Guiana | 00-800-XXXX-XXXX National reachability: full | 30-60 |
| Germany | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Greece | 00-800-XXXX-XXXX National reachability: all fixed; Cosmotel mobile network | 10-15 |
| Guadeloupe | 00-800-XXXX-XXXX National reachability: full | 30-60 |
| Hong Kong | 006-800-XXXX-XXXX National reachability: full CLI not guaranteed. | 20-40 |
| Hungary | 00-800-XXXX-XXXX National reachability: full Activation of international direct dialing service is required for calling parties for both fixed and mobile lines. Airtime charges may apply when calling from mobiles. | 10-15 |
| Iceland | 00-800-XXXX-XXXX National reachability: all fixed; Iceland Telecom, IMC, Vodafone mobile networks. | 10-20 |
| Israel | Dialing format: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/uifn-service.html) National reachability: full | 20-50 |
| Italy | 00-800-XXXX-XXXX National reachability: all fixed networks, including Vatican and San Marino | 10-15 |
| Japan | Dialing format: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/uifn-service.html) National reachability: full | 20-40 |
| Latvia | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Lithuania | 00-800-XXXX-XXXX National reachability: all fixed networks; Telia LT mobile | 15-30 |
| Luxembourg | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Macao | 00-800-XXXX-XXXX National reachability: full | 15-25 |
| Macedonia | 00-800-XXXX-XXXX National reachability: MakTel fixed, T-Mobile network | 40-60 |
| Malta | 00-800-XXXX-XXXX National reachability: GO and VANILLA fixed networks. GO mobile networks. | 10-15 |
| Martinique | 00-800-XXXX-XXXX National reachability: full | 30-60 |
| Mayotte | 00-800-XXXX-XXXX National reachability: full | 30-60 |
| Monaco | 00-800-XXXX-XXXX National reachability: full | 20-30 |
| Netherlands | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| New Zealand | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Peru | 00-800-XXXX-XXXX National reachability: America Moviles, Nextel, Telefonica Moviles, TESAM, Globalstar networks. Telefonica del Peru fixed and mobile network | 30-50 |
| Philippines | 00-800-XXXX-XXXX National reachability: all fixed networks | 10-15 |
| Portugal | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Reunion | 00-800-XXXX-XXXX National reachability: full | 30-60 |
| Romania | 00-800-XXXX-XXXX National reachability: Orange fixed and mobile network, Rodasy fixed and mobile network, Romtelekom fixed and mobile network, Cosmote mobile network | 10-30 |
| Saint Pierre And Miquelon | 00-800-XXXX-XXXX National reachability: full | 30-60 |
| Singapore | 001 800 XXXX XXXX Activation of international direct dialing service is required for calling parties of both fixed and mobile lines. Airtime charges may apply when calling from mobiles. Calling from Starhub payphones is not supported. | 20-30 |
| Slovakia | 00-800-XXXX-XXXX National reachability: full | 15-30 |
| Slovenia | 00-800-XXXX-XXXX National reachability: full | 15-30 |
| South Africa | 00-800-XXXX-XXXX National reachability: partial Not reachable from MTN and prepaid subscribers. | 10-15 |
| South Korea | 002-800-XXXX-XXXX National reachability: full | 10-20 |
| Spain | 00-800-XXXX-XXXX National reachability: full Concurrent calls: 100 concurrent calls | 10-15 |
| Switzerland | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Taiwan | 00-800-XXXX-XXXX National reachability: full | 10-15 |
| Thailand | 001-800-XXXX-XXXX National reachability: full | 10-20 |
| United Kingdom | 00-800-XXXX-XXXX National reachability: BT, Vodafone, EE networks | 20-40 |
| Uruguay | 00-800-XXXX-XXXX National reachability: full | 15-25 |
# Region requirements for ordering and porting phone numbers in Amazon Connect
Region requirements for ordering and porting phone numbers
Country or region regulations often require a local office address and specific identification documents to purchase and own a phone number. The address that you provide can be the business or personal address where the phone numbers are used.
For a list of the telephony capabilities that Amazon Connect provides, see the [Amazon Connect Telecoms Country Coverage Guide](https://d1v2gagwb6hfe1.cloudfront.net/Amazon_Connect_Telecoms_Coverage.pdf). This guide provides visibility of what regions are supported, and if there are any exceptions to being able to access a country from any commercial region.
Following is a list of ID Requirements by country or region for ordering and porting numbers. **All AWS Regions are supported—except Africa (Cape Town) and AWS GovCloud (US-West)—unless noted otherwise**. When you [ request an international number](number-request.md), we'll work with you to submit your documents.
**Important**
Addresses that can be claimed without presence, such as PO Box addresses, are not valid in any country.
After your numbers are ordered or ported, the exact number of requested phone numbers appear on the **Manage Phone numbers** page in the Amazon Connect admin website for you to [manage](get-connect-number.md#get-connect-number1). You won't have access to all available numbers in that country.
## Anguilla (AI)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Antigua and Barbuda (AG)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$11 268 | Yes | File orders in writing. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable |
### Number portability
Porting is not supported.
## Argentina (AR)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | |
| Toll-free prefixes: \$154 800 | No | |
| Shared-Cost prefixes: \$154 810 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 2AM-4AM or 10AM-12PM or 3PM-5PM UTC-3 Buenos Aires time | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Australia (AU)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address, a contact name, and phone number. An address in Australia is required |
| Toll-free prefixes: \$161 1300, \$161 1800 | No | Your business address, a contact name, and phone number. A global address is acceptable. |
### Number portability
****
| Type of number | Portability windows | Required Documents |
| --- | --- | --- |
| Local telephone numbers | Monday-Friday 8 AM -5 PM AEST/AEDT | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
| Toll-free prefixes: \$161 13, \$161 1800 | Monday-Friday 8 AM -3:30 PM AEST/AEDT | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Austria (AT)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Proof of telecom services at your address, which must match the city code requested. Valid forms of proof (must be issued in the past 6 months): [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
| National prefixes: \$143 720 | Yes | Proof of telecom services at your address, which must be within the country. Valid forms of proof (must be issued in the past 6 months): [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
| Toll-free prefixes: \$143 800 | Yes | Your business name, address, and a copy of the business registration (global).A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Belgium (BE)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). |
| Mobile prefixes: \$132 46 | No | |
| Toll-free prefixes: \$132 800 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
**Note**
Ordering and porting of \$132 78 national numbers is not supported.
## Bahamas (BS)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$11 242 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Barbados (BB)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$11 246 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Bolivia (BO)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| National prefixes: \$1591 50 | No | |
### Number portability
Porting is not supported.
## Bonaire (BQ)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$1599 7 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Brazil (BR)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html)
### Number portability
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html)
## Brunei (BN)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Toll-free prefixes | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Canada (CA)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | |
| Toll-free prefixes | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 7 AM to 5 PM CST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Chile (CL)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Legal Business Name (Razón Social): Extract from the commercial register Local Business Address (must be within Chile): Extract from the commercial register showing the legal business address Tax Registration Documentation: Copy of the RUT (Rol Unico Tributario) - Official Chilean tax identification |
| Toll-free prefixes | Yes | Legal Business Name (Razón Social): Extract from the commercial register Local Business Address (must be within Chile): Extract from the commercial register showing the legal business address Tax Registration Documentation: Copy of the RUT (Rol Unico Tributario) - Official Chilean tax identification |
| Mass Communication Numbers (809 and 600 series) | Yes | Legal Business Name (Razón Social): Extract from the commercial register Local Business Address (must be within Chile): Extract from the commercial register showing the legal business address Tax Registration Documentation: Copy of the RUT (Rol Unico Tributario) - Official Chilean tax identification Additional Requirement: Completed and signed "Declaration of Mass Communications Number Usage - Chile" form |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 9 PM to 3 AM PST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## China (CN)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Colombia (CO)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | |
| Toll-free prefixes: \$157 800 | No | |
### Number portability
Not supported
## Costa Rica (CR)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | |
| Toll-free prefixes: \$1506 800 | No | |
### Number portability
Not supported
## Croatia (HR)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
## Curaçao (CW)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$1599 9 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Cyprus (CY)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). |
| Toll-free prefixes: \$1 357 800 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Czech Republic (CZ)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). |
| Toll-free prefixes: \$1420 800 | Yes | Your business name and address. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 3 PM to 4 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Denmark (DK)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: | Yes | Your business name, address, and service description. A global address is acceptable. |
| Mobile prefixes: \$145 9x | No | |
| Toll-free prefixes: \$145 808 | Yes | Your business name, address, and service description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Dominican Republic (DOM)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | N/A |
| Toll-free prefixes: \$11 8xx | No | NA |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Porting is available only for **Local telephone numbers** Monday-Friday 10:00PM to 04:00AM PST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Ecuador (ECU)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | N/A |
| Toll-free prefixes: \$1593-180000XXXX | No | N/A |
### Number portability
Not supported
## El Salvador (SV)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Businesses must provide their name, address, and RUC/ TaxID number, along with a copy of the business registration and a proof of address. Valid proofs of address include: third-party issued bank statements, utility bills (all issued in the previous 6 months); government documents (issued in the previous year). A local address is required. |
| Toll-free prefixes | Yes | Businesses must provide a copy of business registration and a proof of address. Valid proofs of address include: third-party issued bank statements, utility bills (all issued in the previous 6 months); government documents (issued in the previous year). |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 03:00AM to 05:00AM CST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Estonia (EE)
### For ordering phone numbers
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Toll-free prefixes: \$1372 800 | No | |
| National prefixes: \$1372 | Yes | Your business address. A copy of the ID/business registration. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Finland (FI)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your residence or business address. Both must be a local address corresponding to the area code of the telephone number(s). |
| Toll-free prefixes: \$1358 800 | No | |
| National prefixes: \$1358 75 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## France (FR)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local geographic telephone numbers: \$133 1, \$133 2, \$133 3, \$133 4, \$133 5 | Yes | A business address in France is required. You must provide a copy of the business registration (KBIS, INPI, or INSEE extract issued in the past 3 months), listing the provided address in France as main business address. |
| National multipurpose numbers: \$133 9 7890 | Yes | A business address in France is required. You must provide a copy of the business registration (KBIS, INPI, or INSEE extract issued in the past 3 months), listing the provided address in France as main business address. |
| National verified multipurpose numbers (to be used as caller ID by automated calling services): \$133 9 4847 | Yes | A business address in France is required. You must provide a copy of the business registration (KBIS, INPI, or INSEE extract issued in the past 3 months), listing the provided address in France as main business address. |
| National multipurpose numbers to be used for communications with a technical platform: \$133 9 3937 | Yes | A business address in France is required. You must provide a copy of the business registration (KBIS, INPI, or INSEE extract issued in the past 3 months), listing the provided address in France as main business address. |
| Toll-free prefixes: \$133 801 | Yes | A business address in the European Union is required, as well as a contact phone number. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Number portability is supported for all toll-free prefixes from \$133 800 to \$133 805, geographic prefixes from \$133 1 to \$133 5, and national multipurpose prefixes \$133 9. |
## French Guiana (GF)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Georgia (GE)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| National prefixes: \$1995 70 | No | |
| Local telephone numbers: (Tibilisi) | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). You must provide proof of the address. |
### Number portability
Not supported
## Germany (DE)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). You must provide a copy of the business registration document (issued in the past 6 months) as proof of address. |
| National prefixes: \$149 32 | Yes | A business address in Germany is required. You must provide a copy of the business registration document (issued in the past 6 months) as proof of address. |
| Toll-free prefixes: \$149 800 | Yes | Toll-free prefixes are supported for businesses with an address in Germany (thus referred to as numbers answered or terminated inside Germany), or alternatively for businesses with an address outside Germany (thus referred to as answered or terminated outside of Germany). For businesses with an address in Germany (preferred), you must obtain the number directly from the local regulator and then provide your number assignment certificate to Amazon Connect for number activation. Details about the process are provided when you make the request. If your business address is outside of Germany, you must provide a copy of the business registration, which serves as proof of company registration and proof of address. If the business registration document does not show an address, a utility bill (issued in the past 6 months) is also required. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Greece (GR)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). A copy of your business registration in Greece (extracted within the last 12 months). |
| Toll-free prefixes: \$130 800 | Yes | Your business address. It must be an address in Greece. A copy of your business registration in Greece (extracted within the last 12 months). |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Guatemala (GT)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification | Restrictions |
| --- | --- | --- | --- |
| Local telephone numbers | No | | |
### Number portability
Porting is not supported.
## Guadeloupe (GP)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Honduras (HN)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification | Restrictions |
| --- | --- | --- | --- |
| National DID | No | | |
| Toll-free prefixes: \$1504 800 | No | | |
### Number portability
Porting is not supported.
## Hong Kong (HK)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Businesses must provide their name, address, a copy of the business registration, and a proof of address. Valid proofs of address include: third-party issued bank statements, utility bills (all issued in the previous 6 months); government documents (issued in the previous year). A local address is required. |
| National prefixes: \$1852 58 | Yes | Businesses must provide their name, address, a copy of the business registration, and a proof of address. Valid proofs of address include: third-party issued bank statements, utility bills (all issued in the previous 6 months); government documents (issued in the previous year). |
| Toll-free prefixes: \$1852 800 | Yes | Businesses must provide proof of address.Valid proofs of address include: third-party issued bank statements, utility bills (all issued in the previous 6 months). A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| N/A | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Hungary (HU)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). You must provide a copy of the business registration document (issued in the past 6 months) as proof of address. A copy of the ID or passport of an authorized representative is also required. |
| Toll-free prefixes: \$136 800 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Iceland (IS)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address in Iceland. A copy of your business registration in Iceland. |
| Toll-free prefixes | No | |
### Number portability
Porting is not supported.
## Indonesia (ID)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone number prefixes: \$162 21, \$162 31, \$162 61 | Yes | Your business address, a contact name, and phone number. It must be a local address corresponding to the area code of the telephone number(s). You must also provide a description of how you plan to use the numbers. |
| Mobile prefixes: \$162 855 | Yes | Proof of business address, a copy of the ID or passport of an authorized representative, and the business registration. You must also provide a description of how you plan to use the numbers. |
| Toll-free prefixes: \$162 800 | No | |
### Number portability
Not supported
## Ireland (IE)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). You must provide proof of address (such as a utility bill). |
| Toll-free prefixes: \$1353 1800 | Yes | Your business address in Ireland and a copy of the business registration. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Israel (IL)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Italy (IT)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business name, address, and VAT number. You must provide proof of the address along with a copy of the business registration (extracted within the last 6 months). You must provide the following details of an authorized representative: name and address, birth location and data, and nationality and tax code. Also provide proof of the authorized representative's identity, which can be a copy of an ID or passport. The name of the representative must appear on the business registration. A local address in Italy is required. |
| Toll-free prefixes: \$139 800 | Yes | Your business name, address, and VAT number. You must provide the following details of an authorized representative: name and address, birth location and data, and nationality and tax code. Also provide proof of the authorized representative's identity, which can be a copy of an ID or passport. A business address in the European Union is required. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| For local numbers: Monday-Friday 6AM to 9AM CET For toll-free numbers: Monday-Friday 6AM-4PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Jamaica (JM)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Japan (JP)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Supported Regions | Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- | --- |
| Asia Pacific (Tokyo) | Local telephone numbers: \$181 3, \$181 6 | Yes | Businesses must provide 3 pieces of documentation: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Copies of these documents should be made into a single ZIP file. |
| All | Local number prefixes: \$181 50 | Yes | Businesses must provide 3 pieces of documentation: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Copies of these documents should be made into a single ZIP file. |
| All | Toll-free prefixes: \$181 120, \$181 800 | Yes | Businesses must provide the following documentation: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Copies of these documents should be made into a single ZIP file. |
### Number portability
****
| Supported regions | Portability windows | Required Documents |
| --- | --- | --- |
| All for Toll-free prefixes: \$181 120, \$181 800 | Typically the 1st and 15th of the following month. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Submit an Support ticket to verify the portability of your number(s). |
| Asia Pacific (Tokyo) for Local telephone numbers: \$181 3, \$181 6 | Typically the 1st and 15th of the following month. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Submit an Support ticket to verify the portability of your number(s). |
## Latvia (LV)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Toll-free prefixes: \$1371 80 | Yes | Businesses must provide a copy of the business registration, along with proof of address within Latvia (issued in the past 6 months). Valid forms of proof: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
| National prefixes: \$1371 6 | Yes | Businesses must provide proof of address within Latvia (issued in the past 6 months). Valid forms of proof: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Lithuania (LT)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). |
| Toll-free prefixes: \$1370 800 | Yes | Your business address in the country. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Luxembourg (LU)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$1352 27 | Yes | Your residence or business address. It must be a local address corresponding to the area code of the telephone number(s). A contact phone number. |
| National prefixes: | Yes | An address in Luxembourg is required. Businesses must provide a copy of the business registration. A contact phone number. |
| Toll-free prefixes: \$1352 800 | Yes | Your business name and address. A global address is acceptable. A contact phone number. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Macao (MO)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Macedonia (MK)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Malaysia (MY)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
| Toll-free prefixes: \$160 1800 | Yes | Business Registration Documentation. Your business address. A global address is acceptable. |
### Number portability
Not supported
## Malta (MT)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Martinique (MQ)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Mayotte (YT)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Mexico (MX)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | |
| Toll-free prefixes: \$152 800 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET or 2 PM to 4 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Monaco (MC)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## New Zealand (NZ)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | |
| Toll-free prefixes: \$164 800 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 7 AM to 11 AM NZST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Netherlands (NL)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). |
| Toll-free prefixes: \$131 800 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. Estimated lead time from order to activation is 6 weeks. |
| National prefixes: \$131 85 | Yes | Your business address in the country. |
| National prefixes: \$131 88 | Yes | You must obtain the number directly from the local regulator and then provide your number assignment certificate to Amazon Connect for number activation. Details about the process are provided when you make the request. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Nicaragua (NI)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Mobile prefixes: \$1505 (7) | No | N/A |
## Nigeria (NG)
### For ordering phone numbers
****
| Supported Regions | Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- | --- |
| Africa (Cape Town) | Local telephone numbers | Yes | Businesses must provide a copy of business registration containing a proof of address. Valid proofs of address include: third-party issued bank statements, utility bills (all issued in the previous 6 months); government documents (issued in the previous year). The business address must be inside Nigeria. |
### Number portability
Not supported
## Norway (NO)
### For ordering phone numbers
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html)
Numbers are available to businesses only, not individuals. The DID type is Landline, instead of Geographic. This is because all formerly geographic numbers are now classified as landline, and do not have a geographic zone.
### Number portability
****
| Supported Regions | Portability windows | Required Documents |
| --- | --- | --- |
| Europe (Frankfurt) Europe (London) | Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Panama (PA)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: | No | |
| Toll-free prefixes: \$1507 800 | Yes | Your business address. You can have a maximum of 5 Panama toll-free numbers per business name. A global address is acceptable |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 12 AM to 2 AM PST | **For porting local numbers**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) **For porting toll-free numbers**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Peru (PE)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | |
| Toll-free prefixes: \$151 800 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 PM to 4 AM PST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Philippines (PH)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Agent location | Acceptable Identification |
| --- | --- | --- | --- |
| Local telephone numbers: \$163 2 | Yes | The agent must be located within the Philippines. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
| Toll-free prefixes:\$163 1800 | Yes | The agent must be located within the Philippines. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
| UIFN | Yes | N/A | Your business name, address and service usage description. A global address is acceptable. |
### Coverage limitations
+ TFN : National reachability only from: Globe network
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Poland (PL)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | A local address corresponding to the area code of the telephone number(s), and a copy of your business registration as proof of address. |
| Toll-free prefixes: \$148 800 | Yes | Your business address in Poland. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 12 AM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Portugal (PT)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). Your tax ID (NIF). You must also submit the required proof of Telecom services being provided at the address. |
| National prefixes: \$1351 30 | Yes | Your business address in Portugal. You must also submit the required proof of Telecom services being provided at the address. |
| Toll-free prefixes: \$1351 800 | Yes | Your business address, your tax ID, and a copy of the business registration. A business address in the European Union is required. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Puerto Rico (PR)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$11 787, \$11 939 | No | |
| Toll-free prefixes: \$11 800 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM PST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Reunion (RE)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Romania (RO)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: | Yes | Your address and proof of address. It must be a local address corresponding to the area code of the telephone number(s). |
| Toll-free prefixes: \$140 800 | No | |
| National prefixes: \$140 376 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM PST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Saba (BQ)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$1599 4 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Saint Pierre and Miquelon (PM)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Serbia (RS)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business name, address and service usage description. A global address is acceptable. |
| Toll-free prefixes | No | |
### Number portability
Not supported
## Saint Lucia (LC)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Saint Martin (MF)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$11 758 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Singapore (SG)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| National prefixes: \$165 31 and \$165 6 | Yes | Address required in country. Documents required for company: Company registration documents |
| Toll-free prefixes: \$165 1800 | Yes | Your business address. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 9 AM to 5 PM SGT | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
Porting-out DIDs is only possible for contiguous number blocks of 10 numbers (...0 to ...9) due to market practice.
## Sint Eustatius (BQ)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$1599 3 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Sint Maarten (SX)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$11 721 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Slovakia (SK)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). |
| Toll-free prefixes: \$1421 800 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Slovenia (SI)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address. It must be a local address corresponding to the area code of the telephone number(s). |
| Toll-free prefixes: \$1386 80 | No | |
| National prefixes: \$1386 82 | Yes | An address in Slovenia is required. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## South Africa (ZA)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html)
### Number portability
****
| Supported Regions | Portability windows | Required Documents |
| --- | --- | --- |
| Africa (Cape Town) | Monday - Friday 5 PM – 6 PM GMT\$12 (SAST) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## South Korea (KR)
**Note**
Ordering and porting numbers in South Korea takes longer than most other countries because of extra steps related to Regulator review, and because the many of the steps must be performed in Korean. For more information about ordering and porting numbers in South Korea, see [Guidelines for porting phone numbers to your Amazon Connect project in South Korea](porting-numbers-sk.md).
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| VoIP prefixes numbers: \$182 70 | Yes | Local customers should provide a copy of their **business (tax office) registration certificate**, which is issued by local tax authorities and shows the company's registered address. Submit an Support ticket to verify the documents for new number(s) ordering. |
| Representative numbers: \$182 15, \$182 16 | Yes | Representative number order form is required. Use the form that is provided to you when you make the request. Along with this form, the following documents are required: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Submit an Support ticket to verify the documents for new number(s) ordering. |
| Toll-free prefixes: \$182 80 | Yes | Your business address in South Korea. Local customers should provide a copy of their **business (tax office) registration certificate**, which is issued by local tax authorities and shows the company's registered address. Submit an Support ticket to verify the documents for new number(s) ordering. Submit an Support ticket to order a new number. |
| Geographic Prefixes: \$182 2 | Yes (via Porting) | Same as for VOIP numbers, but the provided business registration document should reference a physical location associated with \$1822 (Seoul) zone. But if new local numbers are needed due to the Korean regulations requiring new local numbers to be physically installed as legacy services, we recommend you pre-plan migrations and ensure that you request numbers with existing providers that have a minimum of 6 months of physical installation of the number. Amazon Connect can support migration of a large number of DIDs, and can port numbers older than 6 months directly to Amazon Connect. |
### Number portability
****
| Type of number | Portability windows | Required documents |
| --- | --- | --- |
| Geographic Prefixes: \$182 2 (any \$182 number other than \$1821, \$1825, \$1827, \$182308) | Monday-Friday 9 AM to 6 PM KST | New SIP Order Form and SIP Port Form for the existing number(s). Use the forms that are provided to you when you make the request. Documents must be signed by a company employee whose month and year of birth are noted, and the company stamp must be applied. Along with these forms the following documents are required: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Submit an Support ticket to verify the portability of your number(s). |
| National Prefixes: \$182 50 | Monday-Friday 9 AM to 6 PM KST | New SIP Order Form and SIP Port Form for the existing number(s). Use the forms that are provided to you when you make the request. Documents must be signed by a company employee whose month and year of birth are noted, and the company stamp must be applied. Along with these forms the following documents are required: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Submit an Support ticket to verify the portability of your number(s). |
| Representative numbers: \$182 15, \$182 16 | Monday-Friday 9 AM to 6 PM KST | RN/TFN change form is required. Use the form that is provided to you when you make the request. Along with this form the following documents are required: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Submit an Support ticket to verify the portability of your number(s). |
| Toll-free prefixes: \$182 80 | Monday-Friday 9 AM to 6 PM KST | RN/TFN change form required. Use the form that is provided to you when you make the request. Along with this form the following documents are required: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Submit an Support ticket to verify the documents for new number(s) ordering. |
| VoIP prefixes numbers: \$182 70 | Monday-Friday 9 AM to 6 PM KST | Effectively, callforward to another \$18270 is possible. New SIP Order Form and SIP Port Form for the existing number(s). Use the forms that are provided to you when you make the request. Documents must be signed by a company employee whose month and year of birth are noted, and the company stamp must be applied. Along with these forms the following documents are required: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) Submit an Support ticket to verify the portability of your number(s). |
## Spain (ES)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address in Spain in the relevant geographic zone, and your company tax ID. A copy of the business registration (Agencia Tributaria or Registro Mercantil). If the address on the business registration is different than the address provided for the telephone numbers, you must also provide a proof of address. |
| Toll-free prefixes: \$134 900 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Sweden (SE)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address in Sweden, your VAT number, and a copy of the business registration. |
| National prefixes: \$146 77 and \$146 10 | Yes | Your business address in Sweden, your VAT number, and a copy of the business registration. |
| Mobile prefixes: \$146 766 | No | |
| Toll-free prefixes: \$146 20 | Yes | Your business address in the European Union, your VAT number, and a copy of the business registration. |
### Number portability
Number portability is not available for \$146 77 numbers.
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Switzerland (CH)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | Yes | Your business address in the country. A copy of the ID/business registration and a proof of address. |
| Toll-free prefixes: \$141 800 | Yes | Your business address and a copy of business registration. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 10 AM to 12 PM CET | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Taiwan (TW)
### For ordering phone numbers
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
## Thailand (TH)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification | Restrictions |
| --- | --- | --- | --- |
| Local telephone numbers | Yes | **For business address inside Thailand**: Business must provide a copy of the ID of a company authorized representative and company certificate. **For business address outside of Thailand**: Proof of business address and proof of ID, such as the business registration. Also, a copy of the ID or passport of an authorized representative. | International caller ID is not guaranteed. |
| Toll-free prefixes: \$166 1800 | Yes | Proof of business address and proof of ID, such as the business registration. Also, a copy of the ID or passport of an authorized representative. The address cannot be in Thailand. | |
### Number portability (Re-Routing)
****
| Type of Number | Portability windows | Required Documents |
| --- | --- | --- |
| Local telephone numbers | Monday-Friday 9 AM to 5 PM ICT | The business address must be in Thailand [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Trinidad and Tobago (TT)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$11 868 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Turks and Caicos (TC)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$11 649 | Yes | An order form is required. Use the form that is provided to you when you make the request. Provide the following information: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) A global address is acceptable. |
### Number portability
Porting is not supported.
## Uganda (UG)
### For ordering phone numbers
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html)
### Number portability
Not supported
## United Kingdom (GB)
For UIFN numbers, supports standard [Regions and requirements](#uifn-requirements).
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers: \$144 1, \$144 2 | No | A local address may be required for number orders in certain area codes. |
| Mobile prefixes: \$144 7 | No | |
| Toll-free prefixes: \$144 800, \$144 808 | No | |
| National prefixes: \$144 33, \$144 84 | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| For local (geographic) numbers: Monday-Friday 9AM to 11AM GMT For non-geographic (national, toll-free) numbers: Monday-Friday 9AM to 11AM GMT or 0AM to 4AM GMT | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) When porting \$144 300 numbers, additional documents might be required to prove you are a public sector or non-profit body. |
## United States (US)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers | No | |
| Toll-free prefixes | No | |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Monday-Friday 7 AM to 5PM CST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/phone-number-requirements.html) |
## Uruguay (UY)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
## Venezuela (VE)
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| Local telephone numbers\$1\$1 | No | Not applicable |
| Toll-free prefixes | No | Not applicable |
**\$1\$1National reachability partial** — We offer national inbound reachability with the following local carriers:
+ CANTV fixed network
+ Movilnet (mobile network)
+ Telefonica-Movistar (fixed and mobile network)
At the moment, we don't offer inbound national recheabiliy with Digitel (fixed and mobile network).
### Number portability
Porting is not supported.
## UIFN requirements
### For ordering phone numbers
****
| Type of Number | Are there ID requirements? | Acceptable Identification |
| --- | --- | --- |
| UIFN | Yes | Your business name, address and service usage description. A global address is acceptable. |
### Number portability
****
| Portability windows | Required Documents |
| --- | --- |
| Preset UIFN times only | Service Provider Change Authorization and Designation of Agency provided by Amazon |
# Set up your customer's chat experience in Amazon Connect
Set up your customer's chat experience
You can provide a chat experience to your customers by using one of the following methods:
+ [Add a chat user interface to your website hosted by Amazon Connect](add-chat-to-website.md).
+ [Customize chat with the Amazon Connect open source example](download-chat-example.md).
+ [Customize your solution using Amazon Connect APIs](integrate-with-startchatcontact-api.md). We recommend starting with the Amazon Connect ChatJS open source library when customizing your own chat experiences. For more information, see the [Amazon Connect ChatJS](https://github.com/amazon-connect/amazon-connect-chatjs) repo on Github.
## More resources to customize the chat experience
More resources
+ Interactive messages provide customers with a prompt and pre-configured display options that they can select from. These messages are powered by Amazon Lex and configured through Amazon Lex using a Lambda. For instructions about how to add interactive messages through Amazon Lex, see this blog: [Set up interactive messages for your Amazon Connect chatbot](https://aws.amazon.com/blogs/contact-center/easily-set-up-interactive-messages-for-your-amazon-connect-chatbot/).
Amazon Connect supports the following templates: a list picker and a time picker. For more information, see [Add Amazon Lex interactive messages for customers in chat](interactive-messages.md).
+ [Enable Apple Messages for Business with Amazon Connect](apple-messages-for-business.md)
+ [Amazon Connect Service API Documentation](https://docs.aws.amazon.com/connect/latest/APIReference), especially the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API.
+ [Amazon Connect Participant Service API](https://docs.aws.amazon.com/connect-participant/latest/APIReference/Welcome.html).
+ [ Amazon Connect Chat SDK and Sample Implementations](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/)
+ [Amazon Connect Streams](https://github.com/aws/amazon-connect-streams). Use to integrate your existing apps with Amazon Connect. You can embed the Contact Control Panel (CCP) components into your app.
+ [Enable message streaming for AI-powered chat](message-streaming-ai-chat.md)
# The chat/SMS channel in Amazon Connect
Web and mobile messaging
**Important**
**Trying to contact Amazon for support?** See [Amazon Customer Service](https://www.amazon.com/gp/help/customer/display.html?icmpid=docs_connect_messagingcap_customerservice) (Amazon orders and deliveries) or [AWS Support](https://aws.amazon.com/premiumsupport/?icmpid=docs_connect_messagingcap_premiumsupport) (Amazon Web Services).
Amazon Connect lets you build chat messaging features—mobile chat, web chat, SMS, and third-party messaging services— into your website and mobile apps. It enables your customers to start chatting with contact center agents from any of your business applications, web or mobile.
Interactions are asynchronous, enabling your customers to start a chat with an agent or Amazon Lex bot, step away from it, and then resume the conversation again. They can even switch devices and continue the chat.
**Topics**
+ [Multiple channels, one experience](#unified-experience-chat)
+ [
## Getting started
](#enable-chat)
+ [
## Example chat scenario
](#example-chat-scenario)
+ [
## When do chats end?
](#when-do-chats-end)
+ [Pricing](#web-and-mobile-chat-pricing)
+ [
## More information
](#chat-more-info)
## Multiple channels, one experience
Multiple channels, one experience
Agents have a single user interface to help customers using voice, chat, and tasks. This reduces the number of tools that agents have to learn and the number of screens they have to interact with.
Chat activities integrate into your existing contact center flows and the automation that you built for voice. You build your flows once and reuse them across multiple channels.
Metrics collection and the dashboards you built automatically benefit from the unified metrics across multiple channels.
## Getting started
To add chat messaging capabilities to your Amazon Connect contact center and allow your agents to engage in chats, perform the following steps:
+ Chat is enabled at the instance level when [an Amazon S3 bucket is created for storing chat transcripts](amazon-connect-instances.md#get-started-data-storage).
+ [Add chat to your agent's routing profile](routing-profiles.md).
+ Optionally, you can set up chat subtypes such as SMS messaging. You procure an SMS-enabled phone number by using AWS End User Messaging SMS, import it into Amazon Connect, and then assign it to your flows. For more information, see:
+ [Request an SMS-enabled phone number through AWS End User Messaging SMS](sms-number.md)
+ [Set up SMS messaging in Amazon Connect](setup-sms-messaging.md)
Agents can then begin accepting chats through the Contact Control Panel.
You can see real-time and historical metrics for the chat messaging channel (for example, arrival time, handle time) as part of their overall Chat channel metrics in the same reporting experience used for calls/chats/tasks in order to assess agent performance and productivity.
Amazon Connect provides several resources to help you add chat to your website. For more information, see [Set up your customer's chat experience in Amazon Connect](enable-chat-in-app.md).
## Example chat scenario
A customer and agent are chatting. The customer stops responding to the agent. The agent asks "Are you there?" and doesn't get a reply. The agent leaves the chat. Now the chat is no longer associated with an agent. Your flow determines what happens next.
In this scenario, the customer eventually sends another message ("Hey, I'm back") and the chat resumes. Depending on the logic that you define in the flow, the chat can be assigned to the original agent, or a different agent or queue.
Here's how you build this scenario:
1. Create a disconnect flow. The following image shows the [Sample disconnect flow in Amazon Connect](sample-disconnect.md) in the flow designer. This flow includes the following connected blocks: **Play prompt**, **Wait** which branches to three **Play prompts** (for **Customer returned**, **Time expired**, and **Error**), then **Transfer to queue** and **Disconnect**.
![\[The sample disconnect flow.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/sample-disconnect-flow.png)
1. In the disconnect flow, add a [Wait](wait.md) block. The Wait block has two branches:
+ **Timeout**: Run this branch if the customer hasn't sent a message after a specified amount of time. The total duration of the chat, including multiple **Wait** blocks, cannot exceed 7 days.
For example, for this branch you might just want to run a **Disconnect** block and end the chat.
+ **Customer return**: Run this branch when the customer returns and sends a message. With this branch, you can route the customer to the previous agent, previous queue, or set a new working queue or agent.
1. In your inbound flow, add the [Set Disconnect Flow](set-disconnect-flow.md) block. Use it to specify that when the agent or Amazon Lex bot has disconnected from the chat and only the customer remains, the set disconnect flow should run.
In the following block, for example, we specified that the **Sample disconnect flow** should run.
![\[The Set disconnect flow block, the Select a flow dropdown menu, the sample disconnect flow option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/set-disconnect-flow.png)
For an example that uses the **Set disconnect flow** block, see the [Sample inbound flow](sample-inbound-flow.md).
## When do chats end?
By default, the duration for a chat conversation, including the time spent waiting when the customer isn't active, can't exceed 25 hours. However, you can change this default duration and instead configure a custom chat duration. You can configure a chat to last from a minimum of 1 hour (60 minutes) to up to 7 days (10,080 minutes). To configure a custom chat duration, call the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API and add the `ChatDurationInMinutes` parameter.
During an ongoing chat session, there's no limit to the number of times a customer can leave and rejoin an existing ongoing chat session. To accomplish this, use the [Wait](wait.md) block. For example, you might wait 12 hours for the customer to resume the chat before ending the chat session. If the customer tries to resume the chat after 12 hours, in the flow you can have an Amazon Lex bot ask if they're contacting you about the same issue or a different one.
By specifying a wait time that's significantly shorter than the chat duration, you help ensure that customers have a good experience. For instance, for a 25-hour duration chat, it's possible for the customer to resume a chat after 24 hours and 58 minutes, and then be cut off after two minutes because the conversation ends at the 25-hour limit.
**Tip**
If you're using Amazon Lex with chat, note that the default session timeout for an Amazon Lex session is 5 minutes. The total duration for a session can't exceed 24 hours. To change the session timeout, see [Setting the Session Timeout](https://docs.aws.amazon.com/lex/latest/dg/context-mgmt.html#context-mgmt-session-timeoutg) in the *Amazon Lex Developer Guide*.
## Pricing
Pricing
Chat is charged on a per use basis. There are no required up-front payments, long-term commitments, or minimum monthly fees. You pay per chat message, independently of the number of agents or customers using it. Regional pricing may vary. For more information, see [Amazon Connect pricing](https://aws.amazon.com/connect/pricing/).
## More information
For more information about chat, see the following topics:
+ [Test voice, chat, and task experiences in Amazon Connect](chat-testing.md)
+ [How routing works with multiple channels](about-routing.md#routing-profile-channels-works)
+ [Create a routing profile in Amazon Connect to link queues to agents](routing-profiles.md)
+ [Amazon Connect Chat SDK and Sample Implementations](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/)
# Add a chat user interface to your website hosted by Amazon Connect
Add a chat user interface to your website
To support your customers through chat, you can add a communications widget to your website that is hosted by Amazon Connect. You can configure the communications widget in the Amazon Connect admin website. You can customize the font and colors, and secure the widget so that it can be launched only from your website. When finished, you will have a short code snippet that you add to your website.
Because Amazon Connect hosts the widget, it ensures that the latest version is always live on your website.
**Tip**
Use of the communications widget is subject to default service quotas, such as the number of required characters for each message. Before launching your communications widget into production, make sure that your service quotas are set for your organization's needs. For more information, see [Amazon Connect service quotas](amazon-connect-service-limits.md).
**Topics**
+ [Supported widget snippet fields that are customizable](supported-snippet-fields.md)
+ [
## Supported browsers
](#chat-widget-supported-browsers)
+ [
## Step 1: Customize your communications widget
](#customize-chat-widget)
+ [
## Step 2: Specify the website domains where you expect to display the communications widget
](#chat-widget-domains)
+ [
## Step 3: Confirm and copy communications widget code and security keys
](#confirm-and-copy-chat-widget-script)
+ [
## Getting error messages?
](#chat-widget-error-messages)
+ [Customize widget launch behavior and button icon](customize-widget-launch.md)
+ [Pass the customer display name](pass-display-name-chat.md)
+ [Pass contact attributes](pass-contact-attributes-chat.md)
+ [Additional customizations for your chat widget](pass-customization-object.md)
+ [Download the transcript for your chat widget](chat-widget-download-transcript.md)
+ [Download and customize our open source example](download-chat-example.md)
+ [
# Start chats in your applications by using Amazon Connect APIs
](integrate-with-startchatcontact-api.md)
+ [
# Send browser notifications to customers when chat messages arrive
](browser-notifications-chat.md)
+ [Programmatic chat disconnect](programmatic-chat-disconnect.md)
+ [Pass custom properties to override the defaults in the communications widget](pass-custom-styles.md)
+ [Target your widget button and frame with CSS/JavaScript](target-widget-button.md)
+ [Troubleshoot issues with your communications widget](ts-cw.md)
+ [Add a pre-contact or pre-chat form](add-precontact-form.md)
+ [Post-chat survey](enable-post-chat-survey.md)
# Supported widget snippet fields in Amazon Connect that are customizable
Supported widget snippet fields that are customizable
The following table lists the communications widget snippet fields that you can customize. Example code after the table shows how to use the snippet fields.
| Snippet field | Type | Description | Additional documentation |
| --- | --- | --- | --- |
| `snippetId` | String | Mandatory, auto-generated | n/a |
| `styles` | String | Mandatory, auto-generated | n/a |
| `supportedMessagingContentTypes` | Array | Mandatory, auto-generated | n/a |
| `customLaunchBehavior` | Object | Customize how your website renders and launches the hosted widget icon | [Customize widget launch behavior and button icon for your website hosted in Amazon Connect](customize-widget-launch.md), later in this topic |
| `authenticate` | Function | Callback function to enable JWT security on your website | [Step 2: Specify the website domains where you expect to display the communications widget](add-chat-to-website.md#chat-widget-domains), earlier in this section. |
| `customerDisplayName` | Function | Pass the customer display name when initializing a contact | [Pass the customer display name when an Amazon Connect chat starts](pass-display-name-chat.md), later in this section. |
| `customStyles` | Object | Override the default CSS styles | [Pass custom properties to override the defaults in the communications widget in Amazon Connect](pass-custom-styles.md), later in this section. |
| `chatDurationInMinutes` | Number | The total duration of the newly started chat session | Default: 1500 - Min 60, Max: 10080 |
| `enableLogs` | Boolean | Enable the debugging logs | Default: false |
| `language` | String | Amazon Connect can do translations for supported ISO-639 format language codes. For more information, see [ https://en.wikipedia.org/wiki/List\$1of\$1ISO\$1639-1\$1codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). This would not translate custom text overrides and message content (both sent and received). | Default: en\$1US. Supported: 'cs\$1CZ', 'da\$1DK', 'de\$1DE', 'en\$1AU', 'en\$1CA', 'en\$1GB', 'en\$1US', 'es\$1ES', 'fi\$1FI', 'fr\$1FR', 'hu\$1HU', 'id\$1ID', 'it\$1IT', 'ja\$1JP', 'ko\$1KR', 'nl\$1NL', 'nn\$1NO' 'pt\$1BR', 'pt\$1PT', 'sk\$1SK', 'sv\$1SE', 'zh\$1CN', 'zh\$1TW' |
| `disableCSM` | Boolean | Disable tracking of the client-side metrics from the communication widget. | Default: false |
| `nonce` | String | Handshake value between iframe and customer website csp policy. Example: customer csp allows 1234 nonce value, iframe which pulls in another script must have the same 1234 nonce value so that browser knows it is a trusted script by iframe parent site. | Default: undefined |
| `customizationObject` | Object | Customize the widget layout and transcript | For more information, see [Additional customizations for your Amazon Connect chat widget](pass-customization-object.md), later in this section. |
| `contactAttributes` | Object | Pass attributes to the contact flow directly from snippet code, without any JWT setup | For more information, see [ Pass contact attributes when a chat initializes](https://docs.aws.amazon.com/connect/latest/adminguide/pass-contact-attributes-chat.html). |
| `customDisplayNames` | Object | Override the System or Bot display name and logo configurations set in the Amazon Connect admin website. | For more information, see [ How to pass override system and bot display names and logos for the communications widget ](https://docs.aws.amazon.com/connect/latest/adminguide/pass-custom-styles.html#pass-override-system). |
| `contactMetadataHandler` | Function | Callback function to access contactId. For example, add an event listener to handle scenarios like calling the StopContact function with the contactId when the browser tab is closed or maintaining chat persistence with a previous contactId. | |
| `registerCallback` | Object | This allows to execute callbacks for the exposed lifecycle events. For more information, see [amazon-connect-chatjs](https://github.com/amazon-connect/amazon-connect-chatjs). | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/supported-snippet-fields.html) |
| `initialMessage` | String | Message to be sent to the newly created chat. Length Constraints: Minimum of 1, Maximum of 1024. | To invoke the Lex bot configured in the contact flow using an initial message, modify the [Get customer input flow block](get-customer-input.md) by selecting the **Initialize bot with message** option. For more information, see [How to configure Get customer input flow block](get-customer-input.md#get-customer-input-properties). |
| `authenticationParameters` | Object | This enables the [Authenticate Customer](authenticate-customer.md) flow block | For more information, see [Enable customer authentication](enable-connect-managed-auth.md). |
| `mockLexBotTyping` | Boolean | Enable mocking typing indicator for Lex Bot messages. | Default: false |
| `customStartChat` | Function | Callback function to call Start Chat API from your backend. | For more information, see [Hosted widget UI with custom Start Chat API](https://github.com/amazon-connect/amazon-connect-chat-interface#option-3-hosted-widget-ui-with-custom-start-chat-api) |
The following example shows how to add snippet fields to the HTML script that adds the chat widget to your web site.
```
(function(w, d, x, id) { /* ... */})(window, document,
'amazon_connect', 'widgetId');
amazon_connect('snippetId', 'snippetId');
amazon_connect('styles', /* ... */);
amazon_connect('registerCallback', {
// Custom event example
// WIDGET_FRAME_CLOSED
/**
* This event is triggered when user clicks on the chat widget close button,
* either widget close button was clicked when error in the chat session or normally by the user.
* This event can be used for webview use cases to go back to main app
*
* @param {string} status - The reason for widget closure
* - "error_chat": Indicates the user clicked on widget close button due to an error in the chat session
* - "close_chat": Indicates the user clicked on widget close button normally by the user
*/
'WIDGET_FRAME_CLOSED': (eventName, { status }) => {
// You can implement custom logic based on the status value(error_chat or close_chat)
if (status == "error_chat") {
// handle error chat
} else if (status == "close_chat") {
// handle close chat
}
},
// System event example
/**
* chatDetails: {
* contactId: string,
* participantId: string,
* participantToken: string,
* }
* data: {
* AbsoluteTime?: string,
* ContentType?: string,
* Type?: string,
* ParticipantId?: string,
* DisplayName?: string,
* ParticipantRole?: string,
* InitialContactId?: string
* }
*/
'PARTICIPANT_JOINED': (eventName, { chatDetails, data }) => {
alert(`${data.ParticipantRole} joined the chat.`);
},
'event_Name_3': callback(function),
'event_Name_4': callback(function),
// ...
});
amazon_connect('initialMessage', 'Your initial message string');
// ...
amazon_connect('snippetFieldHere', /* ... */);
```
## Supported browsers
The pre-built communications widget supports the following browser versions and higher:
+ Google Chrome 85.0
+ Safari 13.1
+ Microsoft Edge version 85
+ Mozilla Firefox 81.0
The communications widget supports browser notifications for desktop devices. For more information, see [Send browser notifications to customers when chat messages arrive](browser-notifications-chat.md).
## Step 1: Customize your communications widget
In this step, you customize the experience of the communications widget for your customers.
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Choose **Customize communications widget**.
![\[The configuration guide page, the customize communications widget link.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-customize-chat-window-button.png)
1. On the **Communications widgets** page, choose **Add communications widget** to begin customizing a new communications widget experience. To edit, delete, or duplicate an existing communications widget, choose from the options under the **Actions** column, as shown in the following image.
![\[The communications widgets page, add communications widget button link.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-add-chat-widget.png)
1. Enter a **Name** and **Description** for the communications widget.
**Note**
The Name must be unique for each communications widget created in an Amazon Connect instance.
1. In the **Communications options** section, choose how your customers can engage with your widget, and then choose **Save and continue**.
**Note**
You can only enable a task or email pre-contact form if chat and voice are not enabled.
The following image shows options to allow chat, message receipts, and create a pre-chat form for customers. To enable a pre chat form, you must first create a [view](view-resources-sg.md) with a connect action button and select the `StartChatContact` action. For more information about pre-chat and pre-contact forms, see [Add the Amazon Connect widget to your website](connect-widget-on-website.md).
![\[The communication widget page configured for chat and web calling.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/comm-widget-page-chat.png)
1. On the **Create communication widget** page, choose the widget button styles, and display names and styles.
As you choose these options, the widget preview updates automatically so that you can see what the experience will look like for your customers.
![\[The preview of the communications widget.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/netra-chat-preview.png)
**Button styles**
1. Choose the colors for the button background by entering hex values ([HTML color codes](https://htmlcolorcodes.com/)).
1. Choose **White** or **Black** for the icon color. The icon color can't be customized.
**Widget header**
1. Provide values for header message and color, and widget background color.
1. **Logo URL**: Insert a URL to your logo banner from an Amazon S3 bucket or another online source.
**Note**
The communications widget preview in the customization page will not display the logo if it's from an online source other than an Amazon S3 bucket. However, the logo will be displayed when the customized communications widget is implemented to your page.
The banner must be in .svg, .jpg or .png format. The image can be 280px (width) by 60px (height). Any image larger than those dimensions will be scaled to fit the 280x60 logo component space.
1. For instructions about how to upload a file such as your logo banner to S3, see [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) in the *Amazon Simple Storage Service User Guide*.
1. Make sure that the image permissions are properly set so that the communications widget has permissions to access the image. For information about how to make a S3 object publicly accessible, see [Step 2: Add a bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteAccessPermissionsReqd.html#bucket-policy-static-site) in the *Setting permissions for website access* topic.
**Chat view**
1. **Typeface**: Use the dropdown to choose the font for the text in the communications widget.
1.
+ **System Message Display Name**: Type a new display name to override the default. The default is **SYSTEM\$1MESSAGE**.
+ **Bot Message Display Name**: Type a new display name to override the default. The default is **BOT**.
+ **Text Input Placeholder**: Type new placeholder text override the default. The default is **Type a message**.
+ **End Chat Button Text**: Type new text to replace the default. The default is **End chat**.
1. **Agent chat bubble color**: Choose the colors for the agent's message bubbles by entering hex values ([HTML color codes](https://htmlcolorcodes.com/)).
1. **Customer chat bubble color**: Choose the colors for the customer's message bubbles by entering hex values ([HTML color codes](https://htmlcolorcodes.com/)).
1. Choose **Save and continue**.
## Step 2: Specify the website domains where you expect to display the communications widget
1. Enter the website domains where you want to place the communications widget. Chat loads only on websites that you select in this step.
Choose **Add domain** to add up to 50 domains.
![\[The add domain option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-add-domain.png)
Domain allowlist behavior:
+ Subdomains are automatically included. For example, if you allow example.com, all its subdomains (like sub.example.com) are also allowed.
+ Protocol http:// or https:// must exactly match your configuration. Specify the exact protocol when setting up allowed domains.
+ All URL paths are automatically allowed. For example, if example.com is allowed, all pages under it (such as example.com/cart or example.com/checkout) are accessible. You cannot allow or block specific subdirectories.
**Important**
Double-check that your website URLs are valid and does not contain errors. Include the full URL starting with https://.
We recommend using https:// for your production websites and applications.
1. Under **Add security for your communications widget**, we recommend choosing **Yes**, and working with your website administrator to set up your web servers to issue JSON Web Tokens (JWTs) for new chat requests. This provides you more control when initiating new chats, including the ability to verify that chat requests sent to Amazon Connect are from authenticated users.
![\[The activation of security for new communication widget requests.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-choose-security.png)
Choosing **Yes** results in the following:
+ Amazon Connect provides a 44-character security key on the next page that you can use to create JSON Web Tokens (JWTs).
+ Amazon Connect adds a callback function within the communications widget embed script that checks for a JSON Web Token (JWT) when a chat is initiated.
You must implement the callback function in the embedded snippet, as shown in the following example.
```
amazon_connect('authenticate', function(callback) {
window.fetch('/token').then(res => {
res.json().then(data => {
callback(data.data);
});
});
});
```
If you choose this option, in the next step you'll get a security key for all chat requests initiated on your websites. Ask your website administrator to set up your web servers to issue JWTs using this security key.
1. Choose **Save**.
## Step 3: Confirm and copy communications widget code and security keys
In this step, you confirm your selections and copy the code for the communications widget and embed it in your website. If you chose to use JWTs in [Step 2](#chat-widget-domains), you can also copy the secret keys for creating them.
### Security key
Use this 44-character security key to generate JSON web tokens from your web server. You can also update, or rotate, keys if you need to change them. When you do this, Amazon Connect provides you with a new key and maintains the previous key until you have a chance to replace it. After you have the new key deployed, you can come back to Amazon Connect and delete the previous key.
![\[The security key provided by Amazon Connect.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-security-key.png)
When your customers interact with the Start chat icon on your website, the communications widget requests your web server for a JWT. When this JWT is provided, the widget will then include it as part of the end customer’s chat request to Amazon Connect. Amazon Connect then uses the secret key to decrypt the token. If successful, this confirms that the JWT was issued by your web server and Amazon Connect routes the chat request to your contact center agents.
#### JSON Web Token specifics
+ Algorithm: **HS256**
+ Claims:
+ **sub**: *widgetId*
Replace `widgetId` with your own widgetId. To find your widgetId, see the example at [Communications widget script](#chat-widget-script).
+ **iat**: \$1Issued At Time.
+ **exp**: \$1Expiration (10 minute maximum).
+ **segmentAttributes (optional)**: A set of system defined key-value pairs stored on individual contact segments using an attribute map. For more information check SegmentAttributes in the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-SegmentAttributes) API.
+ **attributes (optional)**: Object with string-to-string key-value pairs. The contact attributes must follow the limitations set by the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-Attributes) API.
+ **relatedContactId (optional)**: String with valid contact id. The relatedContactId must follow limitations set by the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API.
+ **customerId (optional)**: This can be either an Amazon Connect Customer Profiles ID or a custom identifier from an external system, such as a CRM.
\$1 For information about the date format, see the following Internet Engineering Task Force (IETF) document: [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519), page 5.
The following code snippet shows an example of how to generate a JWT in Python:
```
import jwt
import datetime
CONNECT_SECRET = "your-securely-stored-jwt-secret"
WIDGET_ID = "widget-id"
JWT_EXP_DELTA_SECONDS = 500
payload = {
'sub': WIDGET_ID,
'iat': datetime.datetime.utcnow(),
'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=JWT_EXP_DELTA_SECONDS),
'customerId': "your-customer-id",
'relatedContactId':'your-relatedContactId',
'segmentAttributes': {"connect:Subtype": {"ValueString" : "connect:Guide"}}, 'attributes': {"name": "Jane", "memberID": "123456789", "email": "Jane@example.com", "isPremiumUser": "true", "age": "45"} }
header = { 'typ': "JWT", 'alg': 'HS256' }
encoded_token = jwt.encode((payload), CONNECT_SECRET, algorithm="HS256", headers=header) // CONNECT_SECRET is the security key provided by Amazon Connect
```
### Communications widget script
The following image shows an example of the JavaScript that you embed on the websites where you want customers to chat with agents. This script displays the widget in the bottom-right corner of your website.
![\[The communications widget script.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-code.png)
When your website loads, customers first see the **Start** icon. When they choose this icon, the communications widget opens and customers are able to send a message to your agents.
To make changes to the communications widget at any time, choose **Edit**.
**Note**
Saved changes update the customer experience in a few minutes. Confirm your widget configuration before saving it.
![\[he edit link on the widget preview.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-edit.png)
To make changes to widget icons on the website, you will receive a new code snippet to update your website directly.
## Getting error messages?
If you encounter error messages, see [Troubleshoot issues with your Amazon Connect communications widget](ts-cw.md).
# Customize widget launch behavior and button icon for your website hosted in Amazon Connect
Customize widget launch behavior and button icon
To further customize how your website renders and launches the hosted widget icon, you can configure the launch behavior and hide the default icon. For example, you can programmatically launch the widget from a **Chat with us** button element that is rendered on your website.
**Topics**
+ [How to configure custom launch behavior for the widget](#config-widget-launch)
+ [Supported options and constraints](#launch-options-constraints)
+ [Configure widget launch for custom use cases](#launch-usage)
+ [Enable chat session persistence across tabs](#chat-persistence-across-tabs)
## How to configure custom launch behavior for the widget
How to configure custom launch behavior for the widget
To pass custom launch behavior, use the following example code block and embed it in your widget. All of the fields shown in the following example are optional and any combination can be used.
```
amazon_connect('customLaunchBehavior', {
skipIconButtonAndAutoLaunch: true,
alwaysHideWidgetButton: true,
programmaticLaunch: (function(launchCallback) {
var launchWidgetBtn = document.getElementById('launch-widget-btn');
if (launchWidgetBtn) {
launchWidgetBtn.addEventListener('click', launchCallback);
window.onunload = function() {
launchWidgetBtn.removeEventListener('click', launchCallback);
return;
}
}
})
});
```
## Supported options and constraints
Supported options and constraints
The following table lists the supported custom launch behavior options. Fields are optional and any combination can be used.
| Option name | Type | Description | Default value |
| --- | --- | --- | --- |
| `skipIconButtonAndAutoLaunch` | Boolean | A flag to enable/disable the automatic launch of the widget without the user clicking on the page load. | undefined |
| `alwaysHideWidgetButton` | Boolean | A flag to enable/disable the widget icon button from rendering (unless there is an ongoing chat session). | undefined |
| `programmaticLaunch` | Function | | undefined |
## Configure widget launch for custom use cases
Configure widget launch for custom use cases
### Custom widget launch button
Custom widget launch button
The following example shows changes you would need to make in the widget to configure programmatic launch to open only when the user chooses a custom button element rendered anywhere on your website. For example, they may choose a button named **Contact Us** or **Chat With Us**. Optionally, you can hide the default Amazon Connect widget icon until the widget has been opened.
```
```
```
```
### Hyperlink support
Hyperlink support
The following example shows changes you would need to make in the widget configure `auto-launch`, which opens the widget without waiting for the user to click. You can deploy to a page that hosted by your website to create a shareable hyperlink.
```
https://example.com/contact-us?autoLaunchMyWidget=true
```
```
```
### Load widget assets when button is clicked
Load widget assets when button is clicked
The following example shows changes you would need to make in the widget to make your website page load faster by fetching the widget's static assets when a user clicks the **Chat With Us** button. Typically, only small percentage of customers visiting a **Contact Us** page open the Amazon Connect widget. The widget could be adding latency on page load by fetching files from CDN, even though customers never open the widget.
An alternative solution is to run the snippet code asynchronously (or never) on button click.
```
```
```
var buttonElem = document.getElementById('launch-widget-btn');
buttonElem.addEventListener('click', function() {
(function(w, d, x, id){
s=d.createElement("script");
s.src="./amazon-connect-chat-interface-client.js"
s.async=1;
s.id=id;
d.getElementsByTagName("head")[0].appendChild(s);
w[x] = w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
})(window, document, 'amazon_connect', 'asfd-asdf-asfd-asdf-asdf');
amazon_connect('styles', { openChat: { color: '#000', backgroundColor: '#3498fe'}, closeChat: { color: '#fff', backgroundColor: '#123456'} });
amazon_connect('snippetId', "QVFJREFsdafsdfsadfsdafasdfasdfsdafasdfz0=")
amazon_connect('customLaunchBehavior', {
skipIconButtonAndAutoLaunch: true
});
});
```
### Launch a new chat in a browser window
Launch a new chat in a browser window
The following example shows changes you would need to make in the widget to launch a new browser window and auto-launch chat in a full screen.
```
```
```
```
## Enable chat session persistence across tabs
Enable chat session persistence across tabs
By default if a chat is opened in one tab and then the user opens a new tab and starts another chat, a new chat will start instead of connecting to the existing chat. You can enable chat session persistence across tabs if you want the user to connect to the existing chat that was started in the initial tab.
The chat session is stored in session storage on the browser in the variable `persistedChatSession`. You need to copy this value into the session storage of the new tab when the widget is first initialized. Following are instructions.
To connect to the same chat session when user navigates to different subdomains, you can set the domain property of the cookie. For example, you own two subdomains: `domain1.example.com` and `domain2.example.com`. You can add the property `domain=.example.com` so that the cookie can be accessed from all subdomains.
1. Copy the following code next to the other amazon\$1connect functions in the hosted widget snippet. This uses the `registerCallback` event handlers to store the `persistedChatSession` as a cookie so it can be accessed in the new tab. It also cleans up the cookie when the chat ends.
```
amazon_connect('registerCallback', {
'CONNECTION_ESTABLISHED': (eventName, { chatDetails, data }) => {
document.cookie = `activeChat=${sessionStorage.getItem("persistedChatSession")}; SameSite=None; Secure`;
},
'CHAT_ENDED': () => {
document.cookie = "activeChat=; SameSite=None; Secure";
}
});
```
1. Retrieve the cookie value if it exists and set the session storage value in the new tab.
```
const cookie = document.cookie.split('; ').find(c => c.startsWith('activeChat='));
if (cookie) {
const activeChatValue = cookie.split('=')[1];
sessionStorage.setItem('persistedChatSession', activeChatValue);
}
//Your hosted widget snippet should be on this page
```
# Pass the customer display name when an Amazon Connect chat starts
Pass the customer display name
To deliver a more personalized experience for both your customers and agents, you can customize the Amazon Connect communications widget to pass the customer display name during contact initialization. The name is visible to both the customer and agent throughout the chat interaction. This display name is recorded in the chat transcript.
The following images show the customer's display name in their chat experience, and their name in the agent's CCP.
![\[The customer's name in their chat experience, the customer's name in the agent's CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-displayname.png)
1. How the customer display name may appear to the customer using the chat user interface.
1. How the customer display name may appear to the agent using the CCP.
## How to pass a customer display name in the communications widget
To pass a customer display name, implement your callback function in the snippet. Amazon Connect retrieves the display name automatically.
1. Complete the steps in [Add a chat user interface to your website hosted by Amazon Connect](add-chat-to-website.md), if you haven't already.
1. Augment your existing widget snippet to add a `customerDisplayName` callback. It might look something like the following example:
```
amazon_connect('customerDisplayName', function(callback) {
const displayName = 'Jane Doe';
callback(displayName);
});
```
The important thing is that the name is passed to `callback(name)`.
## What you need to know about the customer display name
+ Only one `customerDisplayName` function can exist at a time.
+ The customer display name must follow the limitations set by the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-Type-ParticipantDetails-DisplayName) API. That is, the name must be a string between 1 and 256 characters.
+ An empty string, null, or undefined is invalid input for the display name. To protect against accidentally passing of these inputs, the widget logs an error, `Invalid customerDisplayName provided`, in the browser console, and then starts the chat with the default display name, **Customer**.
+ Because the snippet is in the front end of your website, do not pass sensitive data as the display name. Be sure to follow the appropriate security practices to keep your data safe and protect against attacks and bad actors.
# Pass contact attributes to an agent in the Contact Control Panel (CCP) when a chat starts
Pass contact attributes
You can use [contact attributes](what-is-a-contact-attribute.md) to capture information about the contact who is using the communications widget. Then, you can display that information to the agent through the Contact Control Panel (CCP), or use it elsewhere in the flow.
For example, you can customize your flow to say the name of the customer in your welcome message. Or, you can use attributes specific to your business, such as account/member IDs, customer identifiers like names and emails, or other metadata associated with a contact.
## How to pass contact attributes into the communications widget
1. Enable security in the communications widget as described in [Add a chat user interface to your website hosted by Amazon Connect](add-chat-to-website.md), if you haven't already:
1. In Step 2, under **Add security for your chat widget**, choose **Yes**.
1. In Step 3, use the security key to generate JSON web tokens.
1. Add the contact attributes to the payload of your JWT as an `attributes` claim.
Following is an example of how you might generate a JWT with contact attributes in Python:
**Note**
JWT should be installed as a prerequisite. To install it, run `pip install PyJWT` in your terminal.
```
import jwt
import datetime
CONNECT_SECRET = "your-securely-stored-jwt-secret"
WIDGET_ID = "widget-id"
JWT_EXP_DELTA_SECONDS = 500
payload = {
'sub': WIDGET_ID,
'iat': datetime.datetime.utcnow(),
'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=JWT_EXP_DELTA_SECONDS),
'segmentAttributes': {"connect:Subtype": {"ValueString" : "connect:Guide"}}, 'attributes': {"name": "Jane", "memberID": "123456789", "email": "Jane@example.com", "isPremiumUser": "true", "age": "45"} }
header = { 'typ': "JWT", 'alg': 'HS256' }
encoded_token = jwt.encode((payload), CONNECT_SECRET, algorithm="HS256", headers=header) // CONNECT_SECRET is the security key provided by Amazon Connect
```
In the payload, you must create a string key `attributes` (as-is, all lowercase), with an object as its value. That object must have string-to-string key-value pairs. If anything other than a string is passed in any one of the attributes, the chat will fail to start.
The contact attributes must follow the limitations set by the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-Attributes) API:
+ Keys must have a minimum length of 1
+ Values can have a minimum length of 0
Optionally, you can add the segmentAttributes string to [SegmentAttributeValue](https://docs.aws.amazon.com/connect/latest/APIReference/API_SegmentAttributeValue.html) object map, in the payload. The attributes are standard Amazon Connect attributes. They can be accessed in flows. The contact attributes must follow the limitations set by the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-SegmentAttributes) API.
## Alternative method: Pass contact attributes directly from snippet code
**Note**
The snippet code prepends `HostedWidget-` to all the contact attribute keys that it passes. In the following example, the agent side will see the key value pair `HostedWidget-foo: 'bar'`.
Although these attributes are scoped with the `HostedWidget-` prefix, they are still mutable client-site. Use the JWT setup if you require PII or immutable data in your flow.
The following example shows how to pass contact attributes directly from snippet code without enabling widget security.
```
```
## Implementation and use cases
Calling disconnect programmatically can be useful in multiple cases. It provides more control on when to terminate the conversation outside of manually clicking the `End Chat` button. Here are some common use cases for when to call `disconnect`.
### On close or navigation
A common use case would be to attach the disconnect functionality to events that fire when the browser or tab context is destroyed. `pagehide` and `beforeunload` are the common events that are fired when tearing down the browser. These are triggered when a user refreshes, navigates to a different URL or closes the tab or browser. Although both events are fired when the browser context is destroyed, there is no guarantee that the `disconnect` function can fully execute before the browser’s resources are cleaned up.
`pagehide` is a more modern page lifecycle event and is supported across all major browsers and operating systems. `beforeunload` is an alternative event to try if the `pagehide` event fails to call disconnect consistently. `beforeunload` is triggered before `pagehide` which may provide additional reliability if the `disconnect` function is failing to complete before the browser is closed. There have been reliability issues regarding `beforeunload` especially on iOS devices.
Following is an example code snippet:
```
// Call disconnect when `beforeunload` triggers
window.addEventListener("beforeunload", (event) => {
document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect();
});
// Call disconnect when `pagehide` triggers
window.addEventListener("pagehide", (event) => {
document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect();
});
```
### On context switching
Another use case would be to trigger a disconnect when the user switches contexts such as when a user switches or minimizes the tab/app or locks their screen. The `visibilitychange` event can reliably handle these scenarios where the context is no longer visible.
Following is an example code snippet:
```
window.addEventListener("visibilitychange", () => {
if (document.visibilityState === "hidden") {
document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect();
} else if (document.visibilityState === "visible") {
...
}
});
```
# Pass custom properties to override the defaults in the communications widget in Amazon Connect
Pass custom properties to override the defaults in the communications widget
To further customize your chat user interface, you can override the default properties by passing your own values. For example, you can set the widget width to 400 pixels and the height to 700 pixels (in contrast to the default size of 300 pixels by 540 pixels). You can also use your preferred font colors and sizes.
## How to pass custom styles for the communications widget
To pass custom styles, use the following example code block and embed it in your widget. Amazon Connect retrieves the custom styles automatically. All of the fields shown in the following example are optional.
```
amazon_connect('customStyles', {
global: {
frameWidth: '400px',
frameHeight: '700px',
textColor: '#fe3251',
fontSize: '20px',
footerHeight: '120px',
typeface: "'AmazonEmber-Light', serif",
customTypefaceStylesheetUrl: "https://ds6yc8t7pnx74.cloudfront.net/etc.clientlibs/developer-portal/clientlibs/main/css/resources/fonts/AmazonEmber_Lt.ttf",
headerHeight: '120px',
},
header: {
headerTextColor: '#541218',
headerBackgroundColor: '#fe3',
},
transcript: {
messageFontSize: '13px',
messageTextColor: '#fe3',
widgetBackgroundColor: '#964950',
agentMessageTextColor: '#ef18d3',
systemMessageTextColor: '#ef18d3',
customerMessageTextColor: '#ef18d3',
agentChatBubbleColor: '#111112',
systemChatBubbleColor: '#111112',
customerChatBubbleColor: '#0e80f2',
},
footer: {
buttonFontSize: '20px',
buttonTextColor: '#ef18d3',
buttonBorderColor: '#964950',
buttonBackgroundColor: '#964950',
footerBackgroundColor: '#0e80f2',
startCallButtonTextColor: '#541218',
startChatButtonBorderColor: '#fe3',
startCallButtonBackgroundColor: '#fe3',
},
logo: {
logoMaxHeight: '61px',
logoMaxWidth: '99%',
},
composer: {
fontSize: '20px',
},
fullscreenMode: true // Enables fullscreen mode on the widget when a mobile screen size is detected in a web browser.
})
```
## Supported styles and constraints
The following table lists the supported custom style names and recommended value constraints. Some styles exist at both the global and component levels. For example, the `fontSize` style exists globally and in the transcript component. Component level styles have higher priority and will be honored on the chat widget.
| Custom style name | Description | Recommended constraints |
| --- | --- | --- |
| `global.frameWidth` | Width of the entire widget frame | Minimum: 300 pixels Maximum: Window width Recommended to adjust based on window size |
| `global.frameHeight` | height of the entire widget frame | Minimum: 480 pixels Maximum: Window height Recommended to adjust based on window size |
| `global.textColor` | Color for all texts | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `global.fontSize` | Font size for all texts | Recommended 12 pixels to 20 pixels for different use cases |
| `global.footerHeight` | Height of the widget footer | Minimum: 50 pixels Maximum: Frame height Recommended to adjust based on frame size |
| `global.typeface` | The typeface used in the widget. | Any typeface from this list: Arial, Times New Roman, Times, Courier New, Courier, Verdana, Georgia, Palatino, Garamond, Book man, Tacoma, Trebuches MS, Arial Black, Impact, Comic Sans MS. You can also add a custom typeface/font-family but you need to host the typeface file with public Read access. For example, you can view the documentation to use Amazon Ember font family in the [Amazon developer library](https://developer.amazon.com/en-US/alexa/branding/echo-guidelines/identity-guidelines/typography). |
| `global.customTypefaceStylesheetUrl` | Location where the custom typeface file is hosted with public Read access. | Link to the public HTTP location where typeface file is hosted. For example, AmazonEmber Light typeface CDN location is `https://ds6yc8t7pnx74.cloudfront.net/etc.clientlibs/developer-portal/clientlibs/main/css/resources/fonts/AmazonEmber_Lt.ttf` |
| `header.headerTextColor` | Text color for the header message | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `header.headerBackgroundColor` | Text color for header background | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `global.headerHeight` | Height of the widget header | Recommended to adjust based on using title or image logo or both. |
| `transcript.messageFontSize` | Font size for all texts | Recommended 12 pixels to 20 pixels for different use cases |
| `transcript.messageTextColor` | Text color for transcript messages | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `transcript.widgetBackgroundColor` | Text color for transcript background | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `transcript.customerMessageTextColor` | Text color for customer messages | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `transcript.agentMessageTextColor` | Text color for agent messages | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `transcript.systemMessageTextColor` | Text color for system messages | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `transcript.agentChatBubbleColor` | Background color for agent message bubbles | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `transcript.customerChatBubbleColor` | Background color for customer message bubbles | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `transcript.systemChatBubbleColor` | Background color for system message bubbles | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `footer.buttonFontSize` | Font size for the action button text | Recommended to adjust based on footer height |
| `footer.buttonTextColor` | Color for the action button text | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `footer.buttonBorderColor` | Color for the action button border | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `footer.buttonBackgroundColor` | Color for the action button background | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `footer.BackgroundColor` | Color for the footer background | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `footer.startCallButtonTextColor` | Color for the start call button text | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `footer.startCallButtonBorderColor` | Color for the start call button border | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `footer.startCallButtonBackgroundColor` | Color for the start call button background | Any CSS legal color value. For more information, see [CSS Legal Color Values](https://www.w3schools.com/cssref/css_colors_legal.php). |
| `logo.logoMaxHeight` | Max height of the logo | Minimum: 0 pixels Maximum: Header height Recommended to adjust based on image size and frame height |
| `logo.logoMaxWidth` | Max width of the logo | Minimum: 0 pixels Maximum: Header width Recommended to adjust based on image size and frame width |
| `composer.fontSize` | Font size for the composer text | Recommended 12 pixels to 20 pixels for different use cases |
| `fullscreenMode` | Enables fullscreen mode on the widget when a mobile screen size is detected in a web browser. | type: boolean |
Following are the elements that make up the communications widget.
![\[Elements that make up the communications widget.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-elements.png)
## How to pass override system and bot display names and logos for the communications widget
To override the System/Bot display name and logo configurations set in the Amazon Connect admin website, embed the following code block into your widget code snippet. All of the fields shown in the following example are optional.
```
amazon_connect('customDisplayNames', {
header: {
headerMessage: "Welcome!",
logoUrl: "https://example.com/abc.png",
logoAltText: "Amazon Logo Banner"
},
transcript: {
systemMessageDisplayName: "Amazon System",
botMessageDisplayName: "Alexa"
},
footer: {
textInputPlaceholder: "Type Here!",
endChatButtonText: "End Session",
closeChatButtonText: "Close Chat",
startCallButtonText: "Start Call"
},
})
```
### Supported properties and constraints
| Custom style name | Description | Recommended constraints |
| --- | --- | --- |
| `header.headerMessage` | Text for the header message | Minimum length: 1 character Maximum length: 11 characters Recommended to adjust based on header width |
| `header.logoUrl` | URL pointing to the logo image | Maximum length: 2048 characters Must be a valid URL pointing to a .png, .jpg or .svg file |
| `header.logoAltText` | Text to override the alt attribute for the logo banner | Maximum length: 2048 characters |
| `transcript.systemMessageDisplayName` | Text to override SYSTEM\$1MESSAGE display name | Minimum length: 1 character Maximum length: 26 characters |
| `transcript.botMessageDisplayName` | Text to override BOT display name | Minimum length: 1 character Maximum length: 26 characters |
| `footer.textInputPlaceholder` | Text to override placeholder in text input | Minimum length: 1 character Maximum length: 256 characters |
| `footer.endChatButtonText` | Text to override end chat button text | Minimum length: 1 character Maximum length: 256 characters Recommended to adjust based on button width |
| `footer.closeChatButtonText` | Text to override close chat button text | Minimum length: 1 character Maximum length: 256 characters Recommended to adjust based on button width |
| `footer.startCallButtonText` | Text to override start call button text | Minimum length: 1 character Maximum length: 256 characters Recommended to adjust based on button width |
## Preview your communications widget with custom properties
Make sure to preview your communications widget with the custom properties before putting it into production. Custom values can break the communications widget user interface if not set properly. We recommend testing it on different browsers and devices before releasing it to your customers.
Following are a few examples of things that might break when improper values are used and the suggested fixes.
+ **Issue:** The widget window takes up too much of the screen.
**Fix:** Use a smaller `frameWidth` and `frameHeight`.
+ **Issue:** The font size is too small or too large.
**Fix:** Adjust the font size.
+ **Issue:** There is a blank area below end chat (footer).
**Fix:** Use a smaller `frameHeight` or a larger `footerHeight`.
+ **Issue:** The end chat button is too small or too big.
**Fix:** Adjust `buttonFontSize`.
+ **Issue:** The end chat button is going outside the footer area.
**Fix:** Use a larger `footerHeight` or a smaller `buttonFontSize`.
# Target your Amazon Connect widget button and frame with CSS/JavaScript
Target your widget button and frame with CSS/JavaScript
The communication widget renders the open/close widget button and the widget frame directly on the host website. There are specific selectors that you can use to either target these elements using CSS or reference them in JavaScript.
**Tip**
To update the colors of the widget button, or the styles of the widget itself, use the [Amazon Connect admin website](add-chat-to-website.md#customize-chat-widget). For more customizable styles, you can [pass custom styles](pass-custom-styles.md) directly to the communications widget.
## Widget element IDs and examples
Widget element IDs and examples
The following images show how the chat widget button appears on the user's screen. The first image shows Open button to open the chat widget. The second image shows the Close button to close the chat widget.
![\[Side-by-side images of the chat widget to open and to close the chat window.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/widget-elements.png)
1. Open widget button: `#amazon-connect-open-widget-button`
1. Close widget button: `#amazon-connect-close-widget-button`
1. Widget frame: `#amazon-connect-widget-frame`
1. Widget frame while open: `#amazon-connect-widget-frame.show`
1. Widget frame while closed: `#amazon-connect-widget-frame:not(.show)`
Following is an example of a CSS style sheet that modifies these elements:
```
/* Target widget button while widget is minimized */
#amazon-connect-open-widget-button {
...
}
/* Target widget button while widget is showing */
#amazon-connect-close-widget-button {
...
}
/* Target widget frame */
#amazon-connect-widget-frame {
...
}
/* Target widget frame while it is showing */
#amazon-connect-widget-frame.show {
...
}
/* Target widget frame while it is minimized */
#amazon-connect-widget-frame:not(.show) {
...
}
```
Following is an example of referencing these elements using JavaScript:
```
const openWidgetButton = document.getElementById("amazon-connect-open-widget-button");
const closeWidgetButton = document.getElementById("amazon-connect-close-widget-button");
const widgetFrame = document.querySelector("#amazon-connect-widget-frame");
const openWidgetFrame = document.querySelector("#amazon-connect-widget-frame.show");
const hiddenWidgetFrame = document.querySelector("#amazon-connect-widget-frame:not(.show)");
```
# Troubleshoot issues with your Amazon Connect communications widget
Troubleshoot issues with your communications widget
This topic is for developers who need to investigate issues that may occur when configuring a communications widget in the Amazon Connect admin website.
**Topics**
+ [
## "Something went wrong"
](#sww)
+ [
## Customers not receiving agent messages: Network or WebSocket disconnected
](#mam)
+ [
## Bypassing CORS when opening third-party links
](#bcwotpl)
## "Something went wrong"
If you see the following **Something went wrong** error message when loading your communications widget, open the browser tools to view the error logs.
![\[An error message that says Something went wrong.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-error-message.png)
Following are common issues that cause this error.
### 400 Invalid request
If the logs mention a 400 invalid request, there are a few possible causes:
+ Your communications widget is not being served on an allowed domain. You must specifically state the domains where you will host your widget.
+ The request to the endpoint is not properly formatted. This usually occurs only if the contents of the embed snippet have been modified.
### 401 Unauthorized
![\[The Something went wrong error message.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/something-went-wrong.png)
If the logs mention a 401 unauthorized, this is a problem with the JSON Web Token (JWT) authentication. It displays the above error page.
After you have the JWT, you need to implement it in the `authenticate` callback function. The following example shows how to implement it if you're trying to fetch your token and then use it:
```
amazon_connect('authenticate', function(callback) {
window.fetch('/token').then(res => {
res.json().then(data => {
callback(data.data);
});
});
});
```
Here is a more basic version of what needs to be implemented:
```
amazon_connect('authenticate', function(callback) {
callback(token);
});
```
For instructions on implementing JWT, see [Step 3: Confirm and copy communications widget code and security keys](add-chat-to-website.md#confirm-and-copy-chat-widget-script).
If you have implemented the callback already, the following scenarios may still cause a 401:
+ Invalid signature
+ Expired token
### 404 Not found
A 404 status code is typically caused when the requested resource doesn't exist:
+ An invalid widgetId is specified in the API request
+ The widgetId is valid but the associated flow has been deleted or archived
+ The widget hasn't been published, or it has been deleted
Verify that your snippet is exactly how it was copied from the Amazon Connect admin website, and none of the identifiers have changed.
If the identifiers have not changed and you are seeing a 404, contact AWS Support.
### 500 Internal server error
500 Internal server error
This can be caused by your service-linked role not having the required permissions to start chat. This happens if your Amazon Connect instance was created before October 2018 because you don’t have service-linked roles set up.
**Solution**: Add the `connect:*` policy on the role that is associated with your Amazon Connect instance. For more information, see [Use service-linked roles and role permissions for Amazon Connect](connect-slr.md).
If your service-linked role has the correct permissions, contact AWS Support.
## Customers not receiving agent messages: Network or WebSocket disconnected
During a chat session, a customer who is using a chat application loses their network/WebSocket connection. They quickly re-gain connection, but messages that were sent by the agent during that time aren't rendered in the customer's chat interface.
The following image shows an example of the customer's chat interface and agent's Contact Control Panel side-by-side. A message the agent sent is not rendered in the customer's chat session. However, it appears to the agent as though the customer has received it.
![\[A message in the CCP that is not sent to the contact.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tw-cw-001-message-not-sent.png)
If the customer's chat application loses it's network/WebSocket connection, the chat user interface must do the following to retrieve future messages as well as messages that were sent to it while disconnected:
+ Re-establish the WebSocket connection to receive future incoming messages again.
+ Make a [chatSession.getTranscript](https://github.com/amazon-connect/amazon-connect-chatjs?tab=readme-ov-file#chatsessiongettranscript) ([getTranscripts](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) API) request to retrieve all missing messages that were sent while the customer was disconnected.
If the agent sends a message while the customer's chat user interface is disconnected, the message is successfully stored in the Amazon Connect back end: the CCP is working as expected and messages are all recorded in transcript, but the customer's device is unable to receive messages. When the client reconnects to the WebSocket, there is a gap in messages. Future incoming messages will appear again from the WebSocket, but the gap messages are still missing unless the code explicitly makes a call to the [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) API.
### Solution
Use the [chatSession.onConnectionEstablished](https://github.com/amazon-connect/amazon-connect-chatjs?tab=readme-ov-file#chatsessiononconnectionestablished) event handler to call the [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) API. The `chatSession.onConnectionEstablished` event handler is triggered when the WebSocket re-connects. ChatJS has built-in heartbeat and retry logic for the WebSocket connection. Because ChatJS is not storing the transcript, however, you must add custom code to the chat user interface to manually fetch the transcript again.
The following code sample shows how to implement `onConnectionEstablished` to call `GetTranscript`.
```
import "amazon-connect-chatjs";
const chatSession = connect.ChatSession.create({
chatDetails: {
ContactId: "the ID of the contact",
ParticipantId: "the ID of the chat participant",
ParticipantToken: "the participant token",
},
type: "CUSTOMER",
options: { region: "us-west-2" },
});
// Triggered when the websocket reconnects
chatSession.onConnectionEstablished(() => {
chatSession.getTranscript({
scanDirection: "BACKWARD",
sortOrder: "ASCENDING",
maxResults: 15,
// nextToken?: nextToken - OPTIONAL, for pagination
})
.then((response) => {
const { initialContactId, nextToken, transcript } = response.data;
// ...
})
.catch(() => {})
});
```
```
function loadLatestTranscript(args) {
// Documentation: https://github.com/amazon-connect/amazon-connect-chatjs?tab=readme-ov-file#chatsessiongettranscript
return chatSession.getTranscript({
scanDirection: "BACKWARD",
sortOrder: "ASCENDING",
maxResults: 15,
// nextToken?: nextToken - OPTIONAL, for pagination
})
.then((response) => {
const { initialContactId, nextToken, transcript } = response.data;
const exampleMessageObj = transcript[0];
const {
DisplayName,
ParticipantId,
ParticipantRole, // CUSTOMER, AGENT, SUPERVISOR, SYSTEM
Content,
ContentType,
Id,
Type,
AbsoluteTime, // sentTime = new Date(item.AbsoluteTime).getTime() / 1000
MessageMetadata, // { Receipts: [{ RecipientParticipantId: "asdf" }] }
Attachments,
RelatedContactid,
} = exampleMessageObj;
return transcript // TODO - store the new transcript somewhere
})
.catch((err) => {
console.log("CustomerUI", "ChatSession", "transcript fetch error: ", err);
});
}
```
For another example, see this [open source implementation on GitHub](https://github.com/amazon-connect/amazon-connect-chat-interface/blob/c88f854073fe6dd45546585c3bfa363d3659d73f/src/components/Chat/ChatSession.js#L408).
## Bypassing CORS when opening third-party links
To enhance security, the communications widget operates within a sandbox environment. As a result, third-party links shared within the widget cannot be opened.
**Solution**
There are two options for bypassing CORS to allow third-party links to be opened.
+ **(Recommended)**
Update the sandbox attribute to allow opening links in new tab which can be done by adding the following attribute to the code snippet:
```
amazon_connect('updateSandboxAttributes', 'allow-scripts allow-same-origin allow-popups allow-downloads allow-top-navigation-by-user-activation allow-popups-to-escape-sandbox')
```
**Note**
The attribute value can be updated as needed to allow for specific actions. This is an example for how to allow opening links in new tab.
+ Remove the sandbox attribute which can be done by adding the following attribute to the code snippet:
```
amazon_connect('removeSandboxAttribute', true)
```
# Add a pre-contact or pre-chat form
Add a pre-contact or pre-chat form
You can capture customer information before starting a contact:
+ **Pre-contact form**: Add to capture information from the customer before starting a task or email contact.
+ **Pre-chat form**: Add to capture information from the customer before starting a chat contact.
After you capture the information, you can display it to the agent through the Contact Control Panel (CCP), or use it elsewhere in the flow.
To create the form, you create a custom view and use the connect action button component. For more information on views, see [Use the UI builder in Amazon Connect for resources in step-by-step guides](no-code-ui-builder.md).
The connect action button allows you to take in user input from the form and select what action to take when the form is submitted - start a task/email or chat.
# Enable post-chat survey
Post-chat survey
Post-chat survey enables you to collect end customer feedback immediately after a chat conversation ends. With the **`DisconnectOnCustomerExit`** parameter in the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API, you can configure automatic agent disconnection when end customer disconnects, ensuring that disconnect flow is triggered consistently regardless of which participant disconnects first.
## Implementation options
Implementation options
There are two ways to enable post-chat survey:
### For Custom Chat Widget
If you're using a custom chat implementation:
1. Upgrade to the latest version of [amazon-connect-chatjs](https://github.com/amazon-connect/amazon-connect-chatjs).
1. Add the `DisconnectOnCustomerExit` parameter to your [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API request:
```
{
"DisconnectOnCustomerExit": ["AGENT"],
// ... other StartChatContact parameters
}
```
### For Amazon Connect Communication Widget
If you're using the Amazon Connect Communication Widget:
1. Open the Amazon Connect console and navigate to **Communication widgets**.
1. Enable the post-chat survey setting through the Communication Widgets page.
![\[The Communication Widget settings page showing the post-chat survey option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/post-chat-survey-communication-widget.png)
## Update contact flow to add post-chat survey as a disconnect flow
Configure disconnect flow
To enable post-chat survey, you'll need to update the disconnect flow that's connected to your chat solution. Once configured, the survey will automatically trigger when customers end their chat sessions.
For information about creating a disconnect flow, see [Example chat scenario](web-and-mobile-chat.md#example-chat-scenario).
There are two ways to implement a survey in your disconnect flow:
+ **Option \$11: Using ShowView block** - Use the [Flow block in Amazon Connect: Show view](show-view-block.md) to display a custom survey interface.
+ **Option \$12: Using Lex** - Integrate with Amazon Lex for text-based survey collection. For more information, see [Add an Amazon Lex bot to Amazon Connect](amazon-lex.md).
**Note**
For supervisor barge-in scenarios, ensure you add a [Flow block in Amazon Connect: Set working queue](set-working-queue.md) block before **Transfer to Queue**. Omitting it will cause chat contacts to terminate rather than transfer for this feature.
![\[A flow diagram showing the Set Working Queue block before Transfer to Queue for supervisor barge-in scenarios.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/post-chat-survey-set-working-queue-block.png)
**Contact Trace Records**
When a customer ends a chat session, Amazon Connect sets `disconnectReason` to `CUSTOMER_DISCONNECT` in the [ContactTraceRecord](ctr-data-model.md#ctr-ContactTraceRecord). When `DisconnectOnCustomerExit` is configured, the system generates a new contact ID (`nextContactId`) and initiates the configured disconnect flow.
Example:
```
{
"contactId": "104c05e3-abscdfre",
"nextContactId": "4cbae06d-ca5b-1234567",
"channel": "CHAT",
"initiationMethod": "DISCONNECT",
"disconnectReason": "CUSTOMER_DISCONNECT"
}
```
[How contact attributes work in Amazon Connect](what-is-a-contact-attribute.md) will update in Contact Search and Contact Details.
![\[Contact details showing the contact attributes for a post-chat survey.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/post-chat-survey-contact-attributes.png)
## Additional resources
+ [StartChatContact API](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)
+ [Sample inbound flow in Amazon Connect for the first contact experience](sample-inbound-flow.md)
+ [Example chat scenario](web-and-mobile-chat.md#example-chat-scenario)
+ [Flow block in Amazon Connect: Set working queue](set-working-queue.md)
+ [Flow block in Amazon Connect: Transfer to queue](transfer-to-queue.md)
+ [Amazon Connect ShowView](https://docs.aws.amazon.com/connect/latest/adminguide/show-view-block.html)
+ [Amazon Connect with Lex](https://docs.aws.amazon.com/connect/latest/adminguide/amazon-lex.html)
+ [How contact attributes work in Amazon Connect](what-is-a-contact-attribute.md)
# Integrate Amazon Connect chat into a mobile application
Integrate chat into a mobile application
This topic explains how to integrate Amazon Connect Chat into your mobile application. You can use one of the following options:
+ [WebView integration](#webview)
+ The [Amazon Connect Chat SDKs for iOS and Android](#integrate-chat-with-mobile-sdks-for-mobile)
+ [React Native integration](#react-native-integration)
Use the Amazon Connect [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API to initiate contact.
**Topics**
+ [
## Which integration option to use
](#integrate-options)
+ [
## Amazon Connect chat integration workflow
](#integrate-chat-with-mobile-workflow)
+ [
## Get started with Amazon Connect chat integration
](#integrate-chat-with-mobile-getting-started)
## Which integration option to use
This section provides a description of each integration option to help you decide which one to use for your solution.
### WebView integration
The Amazon Connect Chat WebView integration allows you to embed the full chat experience into your mobile applications with minimal development effort. This method uses `WebView` on Android and `WKWebView` on iOS to provide a seamless and comprehensive chat interface. It is ideal for teams looking for a quick, out-of-the-box solution to integrate chat functionality without extensive customizations.
This approach ensures secure communication and leverages the web-based Amazon Connect chat interface. However, you will need to configure your app to handle cookies and JavaScript properly.
For more information on implementing WebView integration, see the Amazon Connect chat [UI Examples](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples) GitHub repository.
**Recommendation**: WebView-based integration is ideal for rapid development and minimal maintenance while ensuring comprehensive chat functionality.
### Amazon Connect Chat SDKs for Mobile
The Amazon Connect Chat SDKs for iOS and Android simplify the integration of Amazon Connect chat for native mobile applications. The SDKs help handle client side chat logic and back-end communications similar to the Amazon Connect ChatJS Library.
The Amazon Connect Chat SDKs wrap the Amazon Connect Participant Service APIs and abstracts away the management of the chat session and WebSocket. This allows you to focus on the user interface and experience while relying on the Amazon Connect Chat SDK to interact with all the back-end services. This approach still requires you to use your own chat back end to call the Amazon Connect `StartChatContact` API to initiate contact.
+ For more information on the Swift-based iOS SDK, see the [Amazon Connect Chat SDK for iOS](https://github.com/amazon-connect/amazon-connect-chat-ios) GitHub page.
+ For more information on the Kotlin-based Android SDK, see the [Amazon Connect Chat SDK for Android ](https://github.com/amazon-connect/amazon-connect-chat-android) GitHub page.
**Benefits**: The Native SDKs enable robust functionality and high performance, making them ideal for applications that require deep customization and a seamless user experience.
### React Native integration
Amazon Connect Chat React Native integration offers a cross-platform solution. It enables teams to build chat functionality for both Android and iOS with a shared codebase. This method balances customization and development efficiency while leveraging React Native's capabilities for creating robust mobile applications.
This integration uses native bridges to access advanced features and ensures consistent performance and a uniform user experience across platforms. It's easier to implement key features such as WebSocket communication by using libraries such as `react-native-websocket` and API calls with `axios`.
**Best for**: Teams that want to maximize code reuse while maintaining functional flexibility.
## Amazon Connect chat integration workflow
The following diagram shows the programming flow between a customer using a mobile app and an agent. Numbered text in the diagram corresponds to numbered text below the image.
![\[Diagram showing the Amazon Connect chat program flow.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/integrate-chat-mobile-diagram.png)
**In the diagram**
1. When a customer starts a chat in the mobile app, the app should send a request to Amazon Connect using the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API. This requires specific parameters, such as the API endpoint and IDs for the [instance](amazon-connect-instances.md) and [contact](connect-contact-flows.md) flow, to authenticate and initiate the chat.
1. The `StartChatContact` API interacts with your back-end system to obtain a participant token and a contact ID that act as unique identifiers for the chat session.
1. The app's UI passes the `StartChatContact` response to the mobile SDK in order for the SDK to properly communicate with the [Amazon Connect Participant Service](https://docs.aws.amazon.com/connect/latest/APIReference/API_Operations_Amazon_Connect_Participant_Service.html) and set up the customer’s chat session.
1. The SDK exposes a [chatSession](https://github.com/amazon-connect/amazon-connect-chat-ios?tab=readme-ov-file#chatsession-apis) object to the UI, which contains easily usable methods to interact with the chat session.
1. Under the hood, the SDK interacts with the [Amazon Connect Participant Service](https://docs.aws.amazon.com/connect/latest/APIReference/API_Operations_Amazon_Connect_Participant_Service.html) using the [AWS SDK](https://aws.amazon.com/developer/tools/). The communication with the Amazon Connect Participant Service is responsible for all customer interactions with the chat session. This includes actions such as `CreateParticipantConnection`, `SendMessage`, `GetTranscript`, or `DisconnectParticipant`.
1. The SDK also manage the WebSocket connection needed to receive messages, events and attachments from the agent. This will all be handled and parsed by the SDK and surfaced to the UI in an easily consumed structure.
## Get started with Amazon Connect chat integration
The following steps and resources will help you get started with integrating Amazon Connect Chat into your native mobile applications:
1. You can quickly set up a [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) stack to provide the necessary back-end to call StartChatContact by looking at our [startChatContactAPI](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/cloudformationTemplates/startChatContactAPI) example on GitHub.
1. For examples that show how to build your mobile chat UI powered by the Amazon Connect Chat SDKs, check out our [UI Examples](https://github.com/amazon-connect/amazon-connect-chat-ui-examples) GitHub project.
Refer to our sample [iOS](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/iOSChatExample) and [Android](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/androidChatExample) chat examples that showcase how to power a chat application using the Amazon Connect Chat SDK for iOS/Android.
1. Check out the [Amazon Connect Chat SDK for iOS](https://github.com/amazon-connect/amazon-connect-chat-ios) and [Amazon Connect Chat SDK for Android](https://github.com/amazon-connect/amazon-connect-chat-android) GitHub pages. The GitHub page contains API documentation and an implementation guide that explains any prerequisites and installation steps.
1. Set up React Native integration: Leverage the [React Native](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/connectReactNativeChat) example for guidance on implementing react native based solution.
1. If there are any questions or issues regarding the set up or use of the Amazon Connect Chat SDK on your mobile applications, you can file an issue on either the [Amazon Connect Chat SDK for iOS Issues](https://github.com/amazon-connect/amazon-connect-chat-ios/issues) page or the [Amazon Connect Chat SDK for Android Issues](https://github.com/amazon-connect/amazon-connect-chat-android/issues) page. If there is an issue with the mobile chat UI examples, you can file an issue on the [Amazon Connect Chat UI Examples Issues](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/issues) page.
# Enable text formatting in Amazon Connect for your customer's chat experience
Enable text formatting
With Amazon Connect message formatting, you can enable your customers and agents to quickly add structure and clarity to their chat messages.
**Topics**
+ [
## Supported formatting types
](#supported-format-types)
+ [Enable message formatting](#how-to-enable-message-formatting)
+ [
## How to add email and phone links
](#add-email-phone-links)
+ [
## How to add chatbot messages
](#add-bot-messages)
## Supported formatting types
You can provide the following types of formatting on both the chat user interface and the agent application using markdown:
+ Bold
+ Italic
+ Bulleted list
+ Numbered list
+ Hyperlinks
+ Emoji
+ Attachments. To enable attachments, follow [Enable attachments in your CCP so customers and agents can share and upload files](enable-attachments.md).
## How to enable message formatting
Enable message formatting
1. When you create a new [chat user interface](add-chat-to-website.md), rich text formatting is enabled out of the box. No additional configuration is required.
1. To add text formatting capabilities to an existing [chat user interface](add-chat-to-website.md), update the [communications widget code](add-chat-to-website.md) with the following code that is highlighted in bold:
```
(function(w, d, x, id){
s=d.createElement('script');
s.src='https://your-instance-alias.my.connect.aws/connectwidget/static/amazon-connect-chat-interface-client.js';
s.async=1;
s.id=id;
d.getElementsByTagName('head')[0].appendChild(s);
w[x] = w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
})(window, document, 'amazon_connect', 'widget-id');
amazon_connect('styles', { openChat: { color: 'white', backgroundColor: '#123456'}, closeChat: { color: 'white', backgroundColor: '#123456'} });
amazon_connect('snippetId', 'snippet-id');
amazon_connect('supportedMessagingContentTypes', [ 'text/plain', 'text/markdown' ]);
```
The code that is highlighted in red is set to the correct values when you get the snippet from the Amazon Connect console. The only content you choose to add or remove is the last line in bold for `supportedMessagingContentTypes`.
1. To add text formatting capabilities to your own custom chat user interface (for example, [Chat Interface](https://github.com/amazon-connect/amazon-connect-chat-interface) or your own UI solution on top of [ChatJS](https://github.com/amazon-connect/amazon-connect-chatjs)), follow these steps:
1. Call the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API. When calling `StartChatContact`, add the `SupportedMessagingContentTypes` parameter as shown in bold in the following example:
```
// Amazon Connect StartChatContact API
{
"Attributes": {
"string" : "string"
},
"ClientToken": "string",
"ContactFlowId": "your flow ID",
"InitialMessage": {
"Content": "string",
"ContentType": "string"
},
"InstanceId": "your instance ID",
"ParticipantDetails": {
"DisplayName": "string"
}
// optional
"SupportedMessagingContentTypes": [ "text/plain", "text/markdown" ]
}
```
1. Import `chatjs` as an object, as shown in the following example:
```
import "amazon-connect-chatjs";
this.session = connect.ChatSession.create({
...
});
this.session.sendMessage({
message: "message-in-markdown-format",
contentType: "text/markdown"
});
```
If you don't use ChatJs, see these topics for information about sending markdown text through Amazon Connect APIs: [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) and [SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html).
1. Send messages with markdown. See the previous code snippet for importing `chatjs` as an object for an example of how to send messages. You can use simple markdown for formatting text in chats. If you're already [using chatjs today to send plaintext messages](https://github.com/amazon-connect/amazon-connect-chatjs/blob/master/src/core/chatController.js#L66) you can modify your existing logic to call [SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html) with `text/markdown` as `contentType` instead of `text/plain` when you want to send markdown messages. Be sure to update the `sendMessage` parameter to have the markdown format of your messages. For more information, see [Markdown Guide Basic Syntax](https://www.markdownguide.org/basic-syntax/).
1. Implement your own logic in the UI package to render markdown messages in the input area and chat transcript. If you use React, you can use [react-markdown](https://github.com/remarkjs/react-markdown) as a reference.
**Note**
Text formatting capabilities appear to your agent only if the feature has been enabled for your customer in the chat user interface. If text formatting is not supported or enabled on the customer chat user interface, the agent will not have the ability to compose and send messages with text formatting.
All text formatting capabilities except attachments are available for [quick responses](create-quick-responses.md).
## How to add email and phone links
The following example shows how to add clickable and callable links to your web and mobile applications.
```
Call us today: [+1 (123) 456-7890](tel:+11234567890)
[Call Us](tel:+11234567890)
[Skype Us](callto:+91123-456-7890)
[Fax Us](fax:+91123-456-7890)
[Text Us](SMS:+91123-456-7890)
[Email Us](mailto:name@email.com)
```
## How to add chatbot messages
When you enable markdown for chat messages, you can use rich text formatting for the following types of chatbot messages:
+ [Play prompt](play.md) flows
+ [Get customer input](get-customer-input.md) flows
+ `SYSTEM_MESSAGE`
+ `Lex BOT`
+ `Third Party BOT`
+ `Lex BOT Lambda`
The following image shows how to enable a prompt manually in a [Play prompt](play.md) flow block:
![\[Image of a flow block and a prompt with 2 links, one for an FAQ and another for a phone number.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chat-rtf-play-prompt-flow-1.png)
The following image shows how to enable a prompt manually in the a [Get customer input](get-customer-input.md) flow block, then associate the flow block with an Amazon Lex bot:
![\[Image of a flow block and a prompt with 2 links, one for an FAQ and another for a phone number.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chat-rtf-get-customer-flow.png)
The following image shows how the prompt appears in the SYSTEM\$1MESSAGE and various BOT message types:
![\[Image showing "Review our FAQ" and "give us a call" links in SYSTEM and BOT messages.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chat-rtf-sys-bot-messages.png)
The following image shows how to set up a prompt in an Amazon Lex bot intent:
![\[Image of an Amazon Lex intent containing a prompt with 2 links, one for an FAQ and another for a phone number.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chat-rtf-lex-flow.png)
For more information about intents, see [Adding intents](https://docs.aws.amazon.com/lexv2/latest/dg/add-intents.html) in the *Amazon Lex V2 Developer Guide*. For more information about Lambda messages, see [Enabling custom logic with AWS Lambda functions](https://docs.aws.amazon.com/lexv2/latest/dg/lambda.html), also in the *Amazon Lex V2 Developer Guide*.
# Enable notifications for chat customers in Amazon Connect
Enable message *Delivered* and *Read* receipts
You can enable message *Delivered* and *Read* in your [chat user interface](add-chat-to-website.md) so your customers know the status of the messages they send. This provides transparency to customers, and improves the overall chat experience.
Regardless of whether message receipts are enabled, the message receipt data and events are always sent and can be seen in the network log. Enabling and disabling message receipts in your chat user interface only affects whether the receipts appear in the communication widget transcript.
**Tip**
By default message receipts are already enabled in the [Test chat](chat-testing.md#test-chat) experience, the Contact Control Panel (CCP), and [downloadable open source example](download-chat-example.md) of the chat widget.
**To enable message receipts in your chat user interface**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Choose **Customize communications widget**.
![\[The configuration guide page, the customize communications widget option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-customize-chat-window-button.png)
1. Choose **Edit**.
![\[The saved communications widget customization page, the edit button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-edit-messagereceipt.png)
1. By default **Message receipts** is not enabled. Set to **Enabled**.
![\[The message receipts option, enabled.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-enable-messagereceipt.png)
Message receipts are now enabled. Customers who are using the communications widget will start seeing *Delivered* and *Read* receipts immediately.
# Set up chat timeouts for chat participants
Set up chat timeouts
When a chat conversation between an agent and a customer has been inactive (no messages sent) for a certain amount of time, you may want to consider a chat participant to be idle, and you may even want to automatically disconnect an agent from the chat.
To do this you can configure both idle timeouts and auto-close timeouts using the [UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html) action.
**Tip**
This topic is about setting up chat timeouts for customer-agent conversations. If you're looking for information about configuring chat timeouts for when customers are interacting with Lex, see the [Configurable time-outs for chat input during a Lex interaction](get-customer-input.md#get-customer-input-configurable-timeouts-chat) section of the [Flow block in Amazon Connect: Get customer input](get-customer-input.md) block.
**You can set four different types of timers.**
+ You specify the amount of time that has to elapse before an action is taken.
+ Any combination of timers can be used.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/setup-chat-timeouts.html)
**Specify all timers in minutes.**
+ Minimum: 2 minutes
+ Maximum: 480 minutes (8 hours)
**Timers apply to participant roles, and apply for life of the chat.**
+ You configure timers for participant roles such as agent and customer, rather than individual participants.
+ After you set the timers, they apply for the life of the chat. If a chat is transferred, the timers apply to the new agent/customer interaction.
## How chat timers work
How chat timers work
Timers behave as follows:
+ Timers run when both an agent and a customer are connected to the chat, or when a customer and a custom participant (such as a custom bot) are connected.
+ Timers first start when an agent/custom participant joins the chat, and stop when the agent/custom participant leaves the chat.
+ Idle timers run before auto-disconnect timers, if both are configured for a role. For example, if both timers are configured, then the auto-disconnect timer starts only after a participant is deemed idle.
+ If only one type of timer is configured for a role, then that timer starts immediately.
+ If at any time a participant sends a message, the timers for that participant are reset. If they were considered idle, they will no longer be considered idle.
+ When an attachment is added to a message, the chat timer is reset.
+ The configuration that was set when the agent/custom participant joined applies for as long as the agent/custom participant remains on the chat. If you update the timer configuration while an agent/custom participant and customer are already connected to each other, the new configuration is stored but not applied until and unless a new agent/custom participant connects to the chat.
+ When an auto-disconnect event occurs, all participants other than the customer (such as the agent, any monitoring supervisor, or custom participants) are disconnected. If the agent is the one disconnected, and if a [Set disconnect flow](set-disconnect-flow.md) block has been configured, then the chat is routed to it.
### Idle timer expiry
Idle timer expiry
Following is what happens when an idle timer expires during a customer-custom participant interaction:
1. An idle event is fanned out to all websockets/streaming endpoints.
1. If an auto-disconnect timer is configured, it is started.
1. If the idle timer expires while the chat contact is in a **Wait** block, the contact is NOT routed down the **Time Expired** branch. No action is taken if this scenario occurs.
### Auto-disconnecting custom participants
Auto-disconnecting custom participants
When an auto-disconnect timer expires, the custom participant is disconnected from the chat.
Amazon Connect performs one of the following steps when auto-disconnect timers expire:
1. The chat currently resides in a [Wait](wait.md) block that is configured for a custom participant.
+ The custom participant is disconnected from the chat, and the chat resumes the flow by taking the **Bot participant disconnected** branch.
1. The chat currently resides in a [Wait](wait.md) block that is configured for the customer OR the chat is not in a **Wait** block.
+ The custom participant is disconnected from the chat and no other actions are taken.
## Messages displayed to participants
Messages displayed to participants
Messages are displayed to all participants when any one of the following events happen:
+ A participant becomes idle.
+ An idle participant sends a message, and is no longer idle.
+ An auto-disconnect occurs. Because the agent is disconnected, they won't be able to see the message.
These events are not persisted to the transcripts, nor billed.
Default messages (in all supported languages) are displayed to agents in the Contact Control Panel (CCP) for each of these events.
The following image show examples of default idleness messages that the agent would see in the CCP. For example, *Agent has become idle*.
![\[The ccp, the default idleness messages.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chat-timeout-message.png)
## Recommended usage
Recommended usage
To use the chat timeout feature, we recommend that you do the following:
1. Embed a call to the [UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html) action in a Lambda in a contact flow.
1. Depending on your use case, place the Lambda either immediately after starting the chat (at the beginning of the flow) or right before routing the contact to a queue.
## Customize the customer's chat user interface for a disconnect event
Customize the customer's chat user interface for a disconnect event
To customize your customer's chat user interface for a disconnect event, see the following methods in the [ChatJS](https://github.com/amazon-connect/amazon-connect-chatjs):
+ `onParticipantIdle(callback)`
+ `onParticipantReturned(callback)`
+ `onAutoDisconnection(callback)`
Use these methods to register callback handlers which are triggered when the new events arrive.
# Enable push notifications for mobile chat
Enable push notifications for mobile chat
Push notifications for mobile chat are configured through [AWS End User Messaging](https://docs.aws.amazon.com/sms-voice/latest/userguide/what-is-service.html). You can enable push notifications for mobile chat on iOS or Android devices, allowing you to alert customers about new messages even when they aren't actively using your mobile application. You can enable this feature in your existing app integrated with the [Amazon Connect mobile SDKs](https://docs.aws.amazon.com/connect/latest/adminguide/integrate-chat-with-mobile.html), a [webview solution](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples), or a custom native solution.
The following steps and resources will help you get started with integrating Amazon Connect push notifications into your native mobile applications:
## Step 1: Obtain credentials from Apple's APNs and Google's FCM console
Step 1: Obtain credentials from Apple's APNs and Google's FCM console
In order to set up Amazon Connect so that it can send push notifications to your apps, you first have to obtain credentials from Apple's APNs and Google's FCM console that will enable [AWS End User Messaging](https://docs.aws.amazon.com/sms-voice/latest/userguide/what-is-service.html) to send notifications to your mobile applications. The credentials that you provide, depend on which push notification system you use:
+ For Apple Push Notification service (APNs) credentials, see [Obtain an encryption key and key ID from Apple](https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns#Obtain-an-encryption-key-and-key-ID-from-Apple) and [Obtain a provider certificate from Apple](https://developer.apple.com/documentation/usernotifications/establishing-a-certificate-based-connection-to-apns#Obtain-a-provider-certificate-from-Apple) in the Apple Developer documentation.
+ For Google's Firebase Cloud Messaging (FCM) credentials they can be obtained through the Firebase console, see [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging).
## Step 2: Create an AWS End User Messaging service application using the AWS console and enable the push notification channel for FCM or APNs
Step 2: Create an AWS End User Messaging service application using the AWS console and enable the push notification channel for FCM or APNs
Before you can enable Amazon Connect to send push notifications, you first have to [create an AWS End User Messaging application and enable the push notifications](https://docs.aws.amazon.com/push-notifications/latest/userguide/procedure-enable-push.html) channel in the [AWS console](https://console.aws.amazon.com/push-notifications/).
Follow these directions to create an application and enable any of the push channels. To complete this procedure you are only required to enter an application name. You can enable or disable any of the push channels at a later time:
1. Open the AWS End User Messaging Push console at [https://console.aws.amazon.com/push-notifications/](https://console.aws.amazon.com/push-notifications/)
1. Choose **Create application**.
1. For **Application name** enter the name for your application.
1. (Optional) Follow this optional step to enable the **Apple Push Notification service (APNs)**.
1. For **Apple Push Notification service (APNs)** select **Enable**.
1. For **Default authentication type** choose either:
1. If you choose **Key credentials**, provide the following information from your Apple developer account. AWS End User Messaging Push requires this information to construct authentication tokens.
1. **Key ID** – The ID that's assigned to your signing key.
1. **Bundle identifier** – The ID that's assigned to your iOS app.
1. **Team identifier** – The ID that's assigned to your Apple developer account team.
1. **Authentication key** – The .p8 file that you download from your Apple developer account when you create an authentication key.
1. If you choose **Certificate credentials**, provide the following information:
1. **SSL certificate** – The .p12 file for your TLS certificate.
1. **Certificate password** – If you assigned a password to your certificate, enter it here.
1. **Certificate type** – Select the type of certificate to use.
1. (Optional) Follow this optional step to enable the **Firebase Cloud Messaging (FCM)**.
1. For **Firebase Cloud Messaging (FCM)** select **Enable**.
1. Choose **Token credentials** for** Default authentication type, **then choose your service JSON file.
1. Choose **Create application**.
## Step 3: Associate the AWS End User Messaging application with an Amazon Connect instance
Step 3: Associate the AWS End User Messaging application with an Amazon Connect instance
To enable push notifications on an [Amazon Connect instance](https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html), you will need to associate an AWS End User Messaging application with an [Amazon Connect instance](https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html) by calling the [CreateIntegrationAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html) API with the `PINPOINT_APP` [IntegrationType](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html#API_CreateIntegrationAssociation_RequestSyntax). You can call this API with [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/connect/create-integration-association.html) or the [Amazon Connect SDK](https://aws.amazon.com/developer/tools/) for any supported languages. This is a one-time onboarding step required for each integration between an AWS End User Messaging application and an Amazon Connect instance.
## Step 4: Get device token with FCM or APNs SDK, and register it with Amazon Connect
Step 4: Get device token with FCM or APNs SDK, and register it with Amazon Connect
You will need to fetch the device token and use it to register an end-user mobile device with an Amazon Connect chat contact to send push notifications for new messages in the chat. Read the below FCM/APNs developer documentation for how the device token is generated and obtained from the mobile application.
+ For Apple Push Notification service (APN), see [Registering your app with APNs](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns) in the Apple Developer documentation.
+ For Firebase Cloud Messaging (FCM), see [Best practices for FCM registration token management](https://firebase.google.com/docs/cloud-messaging/manage-tokens).
To register the device with a chat contact, we recommend that you do the following:
1. When the mobile application calls the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API, pass the `deviceToken` and `deviceType` as [contact attributes](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-Attributes). For webview and hosted communication widget users, see [How to pass contact attributes into the communications widget](https://docs.aws.amazon.com/connect/latest/adminguide/pass-contact-attributes-chat.html#how-to-contact-attributes-chatwidget) for more details.
1. Embed a call to the [CreatePushNotificationRegistration](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html) action in a Lambda function in a contact flow. The flow block should read `deviceToken` and `deviceType` from the user-defined contact attributes, and the `initialContactId` from the system attributes, then pass these values to the Lambda function.
1. Depending on your use case, place the Lambda function either immediately after starting the chat (at the beginning of the flow) if you want the end user to receive push notifications immediately, or right before routing the contact to a queue so that they will receive the contact only an when agent is about to join. Once the API call is made, the device will start receiving push notifications when a new message comes from the agent or system. By default, push notifications will be sent for all the system and agent messages.
![\[Invoke lambda function flow block in the Amazon Connect admin website flow designer.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/step-4-set-up-push-notifications-for-mobile-chat-1.png)
1. (optional) Embed a call to the [DeletePushNotificationRegistration](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html) action in a Lambda function in a flow. Once the API call is made, the device will stop receiving push notifications when a new message comes from the agent or system.
## Step 5: Receive push notification on your mobile applications
Step 5: Receive push notification on your mobile applications
Check out our [Amazon Connect Chat UI Examples](https://github.com/amazon-connect/amazon-connect-chat-ui-examples) project and refer to our sample [iOS](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/iOS-WKWebView-sample) and [Android](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/android-webview-sample) chat webview examples that showcase how to integrate Amazon Connect APIs to onboard and receive push notifications.
## Monitor your usage for push notifications
Monitor your usage for push notifications
To ensure the reliability, availability, and performance of your push notifications, it's crucial to monitor their usage. You can track this information through several channels:
1. AWS provides comprehensive monitoring tools for push notifications. For more information, see [Monitoring AWS End User Messaging Push](https://docs.aws.amazon.com/push-notifications/latest/userguide/monitoring-overview.html).
1. Depending on the push notification service you're using, you can access additional usage data through their respective consoles.
1. Firebase Cloud Messaging (FCM) : Consult the FCM documentation on [Understanding message delivery](https://firebase.google.com/docs/cloud-messaging/understand-delivery?platform=android) for insights into your FCM usage.
1. Apple Push Notification service (APNs) : Review the APNs documentation section on [Viewing the status of push notifications using Metrics and APNs](https://developer.apple.com/documentation/usernotifications/viewing-the-status-of-push-notifications-using-metrics-and-apns) to monitor your notification status.
# Enable customers to resume chat conversations in Amazon Connect
Enable persistent chat
Customers often start a chat, then leave the conversation and return later to continue chatting. This may happen many times over the course of several days, months, or even years. To support long running chats like these, you enable persistent chat.
With persistent chat, customers can resume previous conversations with the context, metadata, and transcripts carried forward. They don't need to repeat themselves when they return to a chat, and agents have access to the entire conversation history.
## Chat rehydration
Persistent chat is achieved through a process called chat rehydration. This process enables chat transcripts to be retrieved from previous chat contacts and displayed. It allows customers and agents to easily continue conversations from where they left off.
**Important**
Only chat sessions that have ended are allowed to rehydrate onto a new chat session, as transcript generation occurs asynchronously.
Users should wait 30-60 seconds before attempting to rehydrate from a previously ended chat.
Amazon Connect supports two types of rehydration:
+ `ENTIRE_PAST_SESSION`: Starts a new chat session and rehydrates all chat segments from past chat sessions.
+ `FROM_SEGMENT`: Starts a new session and rehydrates from the specified past chat segment.
For example use cases that show these different rehydration modes, see [Example use cases](#persistentchatscenario).
## RelatedContactId
A new contact can have an association with an existing contact through the `RelatedContactId`. This new contact contains a copy of the [contact properties](connect-attrib-list.md) from the related contact.
For more information about how the `RelatedContactId` is modeled in contact records, see [Data model for Amazon Connect contact records](ctr-data-model.md).
For persistent chat, the `RelatedContactId` depicts the `contactId` used to source chat rehydration.
## How to enable persistent chat
There are two ways you can enable persistent chat:
+ Specify a previous contact ID when creating a new chat. For instructions, see [Enable persistent chat when creating a new chat contact](#enable-persistent-chat-creating-new-chat-contact).
+ Add the [Create persistent contact association](create-persistent-contact-association-block.md) block to a flow. For instructions, see [Enable persistent chat in a flow](#enable-persistent-chat-within-contact-flow).
**Note**
You can choose either method to persist chats but not both. That is, you can only enable persistence of a `SourceContactID` on a new chat once.
To deliver persistent chat experiences, you need to provide a previous contact ID when starting a new chat or when using the [Create persistent contact association](create-persistent-contact-association-block.md) flow block. This is not automatically done for you. We recommend that you create a repository for storing contact record data. The repository enables retrieval of this data for each of your customers.
There are two ways you can create entries in a repository:
+ Use [chat message streaming](https://docs.aws.amazon.com/connect/latest/adminguide/chat-message-streaming.html) to create an entry when a chat has ended.
+ Inspect [contact events](https://docs.aws.amazon.com/connect/latest/adminguide/contact-events.html#contact-events-data-model) and use [AWS Lambda function](https://docs.aws.amazon.com/connect/latest/adminguide/connect-lambda-functions.html) for creating entries into your repository.
After a repository is set up, you can retrieve the previous contact ID for the customer and provide it when starting a new chat or within the [Create persistent contact association](create-persistent-contact-association-block.md) flow block.
In addition, ensure past chat transcripts can be retrieved from your instance's Amazon S3 bucket. The following two things prevent Amazon Connect from retrieving transcripts and don't allow chats to persist:
+ You use multiple chat transcript buckets.
+ You change the chat transcript file name that is generated by Amazon Connect.
### Enable persistent chat when creating a new chat contact
To set up persistent chat experiences when creating a new chat contact, provide the previous `contactId` in the `SourceContactId` parameter of the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API. This enables the chat transcripts of previous contacts to be rehydrated. The transcripts are shown in the chat to both the customer and agent. For an example, see [Example use cases](#persistentchatscenario).
### Enable persistent chat in a flow
To set up persistent chat experiences in a flow:
1. After a chat contact has been created, add the [Create persistent contact association](create-persistent-contact-association-block.md) block to your flow.
1. Use a user-defined attribute to specify a source contact ID.
Alternatively, you can use the [CreatePersistentContactAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreatePersistentContactAssociation.html) API to provide a source contact ID to make the current chat persistent.
Rehydration is started after the chat has started, when using the flow block or API. A rehydrated event is emitted to notify you when rehydration has completed.
## Example use cases
For example, a customer starts a chat session:
1. Agent a1 accepts the chat, and the conversation starts between the customer and agent a1. This is the first contact created in the current chat session. For example, the `contactId` **C1** might be 11111111-aaaa-bbbb-1111-1111111111111.
1. Agent a1 then transfers the chat to Agent a2. This creates another contact. For example, `contactId` **C2** might be 2222222-aaaa-bbbb-2222-222222222222222.
1. Agent a2 ends the chat.
1. The customer is forwarded to the disconnect flow for a post-chat survey that creates another contact. For example, `contactId` **C3** might be 33333333-aaaa-bbbb-3333-3333333333333.
1. The post-chat survey is displayed, and the chat session ends.
1. Later, the customer returns and wants to resume their past chat session.
At this point, there are potentially two different use cases for the customer. Following are the persistent chat use cases the customer can have, and how you configure Amazon Connect to provide them.
### Use case 1
The customer wants to continue their past chat session but they want to hide the post-chat survey. You use the following configuration to provide this experience.
**Request**:
```
PUT /contact/chat HTTP/1.1
Content-type: application/json
{
"Attributes": {
"string" : "string"
},
"ContactFlowId": "string",
"InitialMessage": {
"Content": "string",
"ContentType": "string"
},
"InstanceId": "string",
... // other chat fields
// NEW Attribute for persistent chat
"PersistentChat" : {
"SourceContactId":"2222222-aaaa-bbbb-2222-222222222222222"
"RehydrationType":"FROM_SEGMENT"
}
}
```
#### Configuration
+ SourceContactId = 2222222-aaaa-bbbb-2222-222222222222222 (the contactId for C2)
+ RehydrationType = "`FROM_SEGMENT`"
#### Expected behavior
+ This configuration starts a persistent chat session from the specified past ended contact C2 (for example, 2222222-aaaa-bbbb-2222-222222222222222).
Transcripts of past chat sessions C2 (2222222-aaaa-bbbb-2222-222222222222222) and C1 (11111111-aaaa-bbbb-1111-1111111111111) are accessible in the current persistent chat session. Note that chat segment C3 (33333333-aaaa-bbbb-3333-3333333333333) is dropped from the persistent chat session.
+ In this case, the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) response returns C2 (2222222-aaaa-bbbb-2222-222222222222222) as "ContinuedFromContactId".
+ The `RelatedContactId` for this persistent chat session is 2222222-aaaa-bbbb-2222-222222222222222 (C2).
### Use case 2
The customer wants to continue the past chat session and see the transcript of the entire past engagement (and they don’t want to hide the post-chat survey). You use the following configuration to provide this experience.
**Note**
For the `ENTIRE_PAST_SESSION` rehydration type, specify the first contact (initial `contactId`) of the past chat session as the `SourceContactId` attribute.
**Request**:
```
PUT /contact/chat HTTP/1.1
Content-type: application/json
{
"Attributes": {
"string" : "string"
},
"ContactFlowId": "string",
"InitialMessage": {
"Content": "string",
"ContentType": "string"
},
"InstanceId": "string",
... // other chat fields
// NEW Attribute for persistent chat
"PersistentChat":{
"SourceContactId":"11111111-aaaa-bbbb-1111-1111111111111" // (first contactId C1)
"RehydrationType":"ENTIRE_PAST_SESSION"
}
}
```
#### Configuration
+ SourceContactId = `11111111-aaaa-bbbb-1111-1111111111111` (C1)
+ RehydrationType = "E`NTIRE_PAST_SESSION`"
#### Expected behavior
+ This starts a persistent chat session from the most recently ended chat contact (C3). Transcripts of past chat sessions C3, C2 and C1 are accessible in the current persistent chat session.
+ In this case, the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) response returns 33333333-aaaa-bbbb-3333-3333333333333 (C3) as "ContinuedFromContactId".
+ The `RelatedContactId` for this persistent chat session is 33333333-aaaa-bbbb-3333-3333333333333 (C3)
**Note**
Chat linkages are cumulative. After chat sessions are linked, they carry over.
For example, if a contact (`contactId` C2) that belongs to a past chat session was linked to a contact (`contactId` C1) from a different past chat session, then a new persistent chat session created by linking C2 results in implicit linkage of C1 as well. The new persistent chat session will have the following linkage: C3 → C2 → C1
The past contactId, which the persistent chat session is continued from, is exposed in the `ContinuedFromContactId` field in the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API response. It's also in the RelatedContactId field in the [contact record](ctr-data-model.md#ctr-ContactTraceRecord) for the contact
## How to access past chat contact transcript for a persistent chat
Accessing the past chat transcript for persistent chat uses the existing `NextToken` pagination model. The initial call to [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) on a newly started persistent chat session contains a `NextToken` in the response, if past chat messages exist. `NextToken` must be used to access the past chat transcript along with setting the `ScanDirection` to `BACKWARD` on the subsequent [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) call to fetch past chat messages.
If there are multiple past chat messages, [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) returns a new `NextToken` and the same process can be repeated to fetch more past chat transcripts.
## Not supported: using `StartPosition` and `contactId` filters for persistent chat
Amazon Connect does not support using `StartPosition` and `contactId` filters on the [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) call for transcript item attributes that are from the past chat.
# Enable real-time chat message streaming in Amazon Connect
Enable real-time message streaming
Amazon Connect Chat provides [APIs](https://docs.aws.amazon.com/connect/latest/APIReference/Welcome.html) that enable you to subscribe to a real-time stream of chat messages. Using these APIs, you can:
+ Stream chat messages in real time when a new chat contact is created.
+ Extend the current Amazon Connect Chat functionality to support use cases like building integrations with SMS solutions and third-party messaging applications, enabling mobile push notifications, and creating analytics dashboards to monitor and track chat message activity.
**Note**
This page describes how to subscribe to an SNS endpoint for real-time streaming of chat messages in Amazon Connect. If you're trying to enable message streaming for conversational AI interactions in Amazon Connect, see [Enable message streaming for AI-powered chat](message-streaming-ai-chat.md).
## How the message streaming APIs work
The [Amazon Connect message streaming APIs](https://docs.aws.amazon.com/connect/latest/APIReference/Welcome.html) are triggered when certain events occur within an Amazon Connect Chat contact. For example, when a customer sends a new chat message, the event sends a [payload](sns-payload.md) to a specified endpoint containing data about the message that was just sent. Messages are published using [Amazon Simple Notification Service](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (Amazon SNS) to a specific endpoint.
This topic describes how to set up real-time message streaming using Amazon Connect and Amazon SNS. The steps are:
1. Use the Amazon SNS console to create a new standard SNS topic and set up the messages.
1. Call the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API to initiate the chat contact.
1. Call the [StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html) API to initiate message streaming.
1. Call the [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) API to create the participant's connection.
## Step 1: Create a standard SNS topic
1. Go to the Amazon SNS console.
1. [Create a SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) in your AWS account. In the **Details** section, for **Type**, choose **Standard**, enter a name for the topic, and then choose **Create topic**.
**Note**
Currently, the message streaming APIs only support standard SNS for real-time streaming of messages. They don't support [Amazon SNS FIFO (first in, first out) topics](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html).
1. After you create the topic, its Amazon Resource Name (ARN) is displayed in the **Details** section. Copy the topic ARN to the clipboard. You'll use the topic ARN in the next step, and in [Step 3: Enable message streaming on the contact](#step3-chat-streaming).
The topic ARN looks similar to the following example:
```
arn:aws:sns:us-east-1:123456789012:MyTopic
```
1. Choose the **Access policy** tab, choose **Edit**, and then add a resource-based policy on the SNS topic so that Amazon Connect has permission to publish to it. Following is a sample SNS policy that you can copy and paste into the JSON editor, and then customize with your values:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"Service":"connect.amazonaws.com"
},
"Action":"sns:Publish",
"Resource":"arn:aws:sns:us-east-1:111122223333:TopicName",
"Condition":{
"StringEquals":{
"aws:SourceAccount":"111122223333"
},
"ArnEquals":{
"aws:SourceArn":"arn:aws:connect:us-east-1:111122223333:instance/InstanceId"
}
}
}
]
}
```
------
**Note**
The default **Access policy** comes with conditions applied to `sourceOwner` such as:
```
"Condition": {
"StringEquals": {
"AWS:SourceOwner": "921772911154"
}
}
```
Make sure you remove it and replace with `SourceAccount`, for example:
```
"Condition":{
"StringEquals":{
"aws:SourceAccount":"YOUR_AWS_ACCOUNT_ID"
},
"ArnEquals":{
"aws:SourceArn":"YOUR_CONNECT_INSTANCE_ARN"
}
}
```
This prevents a [cross-service confused deputy](cross-service-confused-deputy-prevention.md) issue.
1. If you're using server-side encryption on SNS, verify you have `connect.amazonaws.com` permission enabled on the KMS key. Following is a sample policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "key-consolepolicy-3",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root",
"Service": "connect.amazonaws.com"
},
"Action": "kms:*",
"Resource": "*"
},
{
"Sid": "Allow access for Key Administrators",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root",
"Service": "connect.amazonaws.com"
},
"Action": [
"kms:Create*",
"kms:Describe*",
"kms:Enable*",
"kms:List*",
"kms:Put*",
"kms:Update*",
"kms:Revoke*",
"kms:Disable*",
"kms:Get*",
"kms:Delete*",
"kms:TagResource",
"kms:UntagResource",
"kms:ScheduleKeyDeletion",
"kms:CancelKeyDeletion"
],
"Resource": "*"
}
]
}
```
------
## Step 2: Initiate the chat contact
1. Call the Amazon Connect [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API to initiate the chat contact.
For information about how to create the SDK client for calling Amazon Connect APIs, see the following topics:
+ [Class AmazonConnectClientBuilder](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/connect/AmazonConnectClientBuilder.html)
+ [Creating Service Clients](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/creating-clients.html)
1. Keep track of `ContactId` and `ParticipantToken` from the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) response since these response attributes are used for calling other chat APIs required to enable streaming. This is described in the next steps.
## Step 3: Enable message streaming on the contact
+ Call [StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html) to enable real-time message streaming to your SNS topic.
+ **Limits**: You can subscribe to up to two SNS topics per contact.
+ When you call [StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html), you'll need to provide the Amazon Resource Name (ARN) of the SNS topic (see [Step 1: Create a standard SNS topic](#step1-chat-streaming)).
A single SNS topic ARN may be used across multiple AWS accounts, but it must be in the same Region as your Amazon Connect instance. For example, if your topic ARN is in **us-east-1**, your Amazon Connect instance must be in **us-east-1**.
+ For initial chat messages that aren't received on the streaming endpoint, you can call the [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) API to receive the initial messages.
## Step 4: Create the participant connection
+ Call [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) with the `ConnectParticipant` attribute passed as true.
+ You must call [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) within five minutes of creating the chat.
+ Calling [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) with `ConnectParticipant` set to true only works if you enabled streaming in [Step 2: Initiate the chat contact](#step2-chat-streaming) and caller participant is `Customer`.
+ This step (creating the participant connection) is optional if you have already successfully connected to the chat contact using `WEBSOCKET`.
## Next steps
You are all set for working with the message streaming APIs.
1. To verify it is working, check that messages are published to the SNS topic you created. You can do this using Amazon CloudWatch metrics. For instructions, see [Monitoring Amazon SNS topics using CloudWatch](https://docs.aws.amazon.com/sns/latest/dg/sns-monitoring-using-cloudwatch.html).
1. Because SNS has [limited retention](https://aws.amazon.com/blogs//aws/sns-ttl-control/), we recommend that you set up [Amazon Simple Queue Service (Amazon SQS)](https://aws.amazon.com/sqs/) [Amazon Kinesis](https://aws.amazon.com/kinesis/), or another service to retain messages.
1. Using [StopContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StopContactStreaming.html) is optional and not required if the chats are being [disconnected](disconnect-hang-up.md) through a contact flow, or if the customer disconnects the chat. However, `StopContactStreaming` provides the option to stop the message streaming on the SNS topic, even if the chat is active and ongoing.
# Use the Amazon SNS payload after enabling message streaming in Amazon Connect
SNS payload
After you’ve enabled message streaming successfully, you may need to filter the message to send it to the intended participant: agent, customer, or all.
To filter by participant, read the specific SNS headers attribute— `MessageVisibility`—to determine whether the message is intended for customer-only, agent-only, or all.
+ To send to the customer only: For all code that faces the customer, clients need to filter out messages intended for the customer and build the following logic for forwarding the message to them.
```
if ( ( MessageVisibility == CUSTOMER || MessageVisibility == ALL) && ParticipantRole != CUSTOMER )
```
+ To send to the agent only:
```
if ( ( MessageVisibility == AGENT || MessageVisibility == ALL) && ParticipantRole != AGENT )
```
You can also leverage the filtering capability in Amazon SNS by building custom [subscription filtering policies](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html). This offloads the message filtering logic from the SNS topic subscriber to the SNS service itself.
## Message attributes in the payload
Message attributes in the payload
Following is a description of each message attribute in the Amazon SNS payload:
+ `InitialContactId`: The initial contact ID of the chat.
+ `ContactId`: The current contact ID of the chat. The `InitialContactId` and `ContactId` can differ if there has been new agent in the chat or the queue-to-queue contact flow.
+ `ParticipantRole`: The participant who sent the message.
+ `InstanceId`: The Amazon Connect instance ID.
+ `AccountId`: The AWS account ID.
+ `Type`: Possible values: `EVENT`, `MESSAGE`.
+ `ContentType`: Possible values: `application/vnd.amazonaws.connect.event.typing`, `application/vnd.amazonaws.connect.event.participant.joined`, `application/vnd.amazonaws.connect.event.participant.left`, `application/vnd.amazonaws.connect.event.transfer.succeeded`, `application/vnd.amazonaws.connect.event.transfer.failed`, `application/vnd.amazonaws.connect.message.interactive`, `application/vnd.amazonaws.connect.event.chat.ended`, and more.
+ `MessageVisibility`: Possible values: `AGENT`, `CUSTOMER`, `ALL`.
## Example SNS payload
Example SNS payload
```
{
"Type" : "Notification",
"MessageId" : "ccccccccc-cccc-cccc-cccc-ccccccccccccc",
"TopicArn" : "arn:aws:sns:us-west-2:009969138378:connector-svc-test",
"Message" : "{\"AbsoluteTime\":\"2021-09-08T13:28:24.656Z\",\"Content\":\"help\",\"ContentType\":\"text/plain\",\"Id\":\"333333333-be0d-4a44-889d-d2a86fc06f0c\",\"Type\":\"MESSAGE\",\"ParticipantId\":\"bbbbbbbb-c562-4d95-b76c-dcbca8b4b5f7\",\"DisplayName\":\"Jane\",\"ParticipantRole\":\"CUSTOMER\",\"InitialContactId\":\"33333333-abc5-46db-9ad5-d772559ab556\",\"ContactId\":\"33333333-abc5-46db-9ad5-d772559ab556\"}",
"Timestamp" : "2021-09-08T13:28:24.860Z",
"SignatureVersion" : "1",
"Signature" : "examplegggggg/1tEBYdiVDgJgBoJUniUFcArLFGfg5JCvpOr/v6LPCHiD7A0BWy8+ZOnGTmOjBMn80U9jSzYhKbHDbQHaNYTo9sRyQA31JtHHiIseQeMfTDpcaAXqfs8hdIXq4XZaJYqDFqosfbvh56VPh5QgmeHTltTc7eOZBUwnt/177eOTLTt2yB0ItMV3NAYuE1Tdxya1lLYZQUIMxETTVcRAZkDIu8TbRZC9a00q2RQVjXhDaU3k+tL+kk85syW/2ryjjkDYoUb+dyRGkqMy4aKA22UpfidOtdAZ/GGtXaXSKBqazZTEUuSEzt0duLtFntQiYJanU05gtDig==",
"SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-11111111111111111111111111111111.pem",
"UnsubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-west-2:000000000000:connector-svc-test:22222222-aaaa-bbbb-cccc-333333333333",
"MessageAttributes" : {
"InitialContactId" : {"Type":"String","Value":"33333333-abc5-46db-9ad5-d772559ab556"},
"MessageVisibility" : {"Type":"String","Value":"ALL"},
"Type" : {"Type":"String","Value":"MESSAGE"},
"AccountId" : {"Type":"String","Value":"999999999999"},
"ContentType" : {"Type":"String","Value":"text/plain"},
"InstanceId" : {"Type":"String","Value":"dddddddd-b64e-40c5-921b-109fd92499ae"},
"ContactId" : {"Type":"String","Value":"33333333-abc5-46db-9ad5-d772559ab556"},
"ParticipantRole" : {"Type":"String","Value":"CUSTOMER"}
}
}
```
# Troubleshoot issues with message streaming in Amazon Connect
Troubleshoot issues with message streaming
## Messages are not getting published to SNS
When this happens, we recommend checking the information in [Step 1: Create a standard SNS topic](chat-message-streaming.md#step1-chat-streaming):
+ Make sure you are using standard SNS and not [Amazon SNS FIFO (first in, first out)](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html). Currently, the message streaming APIs support only standard SNS for real-time streaming of messages.
+ Make sure an SNS resource-based permission is applied correctly in your account.
+ If server-side encryption is enabled, you need to give the same Amazon Connect service principal permission for encrypt and decrypt.
## Flow doesn't start
If you're using the message streaming APIs in place of websockets, send a connection acknowledgment event; see [Step 4: Create the participant connection](chat-message-streaming.md#step4-chat-streaming). This is synonymous to connecting to websocket. The flow begins only after that the connection acknowledgement event.
Call [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) after [StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html) to mark `Customer` as connected; see [Step 3: Enable message streaming on the contact](chat-message-streaming.md#step3-chat-streaming). This ensures messages are sent after you have confirmed that the customer is ready to receive them.
## Issue not resolved?
If after trying the previous solutions you still have issues with message streaming, contact Support for help.
Amazon Connect administrators can choose one of the following options to contact support:
+ If you have an AWS Support account, go to [Support Center](https://console.aws.amazon.com/support/home) and submit a ticket.
+ Otherwise, open the [AWS Management Console](https://console.aws.amazon.com/) and choose **Amazon Connect**, **Support**, **Create case**.
It is helpful to provide the following information:
+ Your contact center instance ID/ARN. To find your instance ARN, see [Find your Amazon Connect instance ID or ARN](find-instance-arn.md).
+ Your Region.
+ A detailed description of the issue.
# Customize chat flow experiences in Amazon Connect by integrating custom participants
Customize chat flow experiences
You can integrate other solutions, such as bots, with Amazon Connect chat to create customized chat flow experiences.
Following is an overview of how you can customize your chat flow experience. Implement these steps for each chat segment after the chat conversation is started. We recommend adding an [AWS Lambda function](invoke-lambda-function-block.md) block to call the APIs in your chat flow.
**Important**
Add a [Play prompt](play.md) block before a [AWS Lambda function](invoke-lambda-function-block.md) block. This is required only when an **Invoke AWS Lambda** block is the first block in your inbound chat flow.
1. [Enable real-time streaming of chat messages](chat-message-streaming.md).
1. Call the Amazon Connect [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) API to add a custom participant (`ParticipantRole` = `CUSTOM_BOT`) to the chat contact.
1. For information about how to create the SDK client for calling Amazon Connect APIs, see the following topics:
+ [Class AmazonConnectClientBuilder](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/connect/AmazonConnectClientBuilder.html)
+ [Creating Service Clients](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/creating-clients.html)
1. Keep the `ParticipantToken` that is obtained from [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) to call [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html). `CreateParticipantConnection` returns a `ConnectionToken`, which you can use to call other Amazon Connect Participant APIs.
When calling [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) to create a connection for a custom participant:
+ Set `ConnectParticipant` to `True` to mark the custom participant as connected for message streaming.
+ Pass `Type` as `CONNECTION_CREDENTIALS` to call the subsequent Amazon Connect Participant Service APIs.
+ `CreateParticipantConnection` should be called within 15 seconds of calling `CreateParticipant`.
1. After the participant is added to the contact, they can exchange messages with the customer by using Amazon Connect Participant Service APIs.
1. To disconnect the participant, call the [ DisconnectParticipant](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_DisconnectParticipant.html) API.
**Note**
A custom participant cannot be added to a chat when an agent or Amazon Lex bot is already present on the contact.
A custom participant will be disconnected when an agent or Amazon Lex bot joins a contact.
Only one custom participant can be present on a contact.
A custom participant is not permitted to access attachments a customer may upload.
We recommend configuring how long a custom participant can chat with a contact:
+ Set the **Timeout** property on the [Wait](wait.md) block for the `ParticipantRole` = `CUSTOM_BOT`.
+ If the custom bot participant is not disconnected before the timeout, then the contact is routed down the **Time Expired** branch. This allows you to decide which block to run next to resolve the customer's query.
**Note**
If a contact is routed down the **Time Expired** branch, they are not disconnected from the contact. You must call the [ DisconnectParticipant](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_DisconnectParticipant.html) API to disconnect the participant.
## Activate timers for customers who are joined to a custom participant
Activate timers for customers who are joined to a custom participant
You can activate timers on customers who are joined to custom participants, such as custom bots. This enables you to detect when a customer stops responding so you can then terminate that bot conversation, and perform the next step in the flow. By terminating idle participants, you can reduce the number of open chats where there is a non-responsive customer engaged with a custom participant.
Perform the following steps to integrate an Idle Participant Custom Bot Extension and optionally set custom timer values. These steps assume that the you already use the custom participant feature for chat.
1. Before the custom participant joins the chat, invoke the [UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html) API for the customer.
1. Timers activate only for the customer. Custom participants do not have idle participant or auto-disconnect timers.
1. You can choose the method for invoking the API.
1. Timer values configured in this step persist for the life of the chat. If you want different timer values for the **customer and agent interaction**, see Step 2.
1. If your client is already set up this way, you don't need to take any other action to integrate your custom participant.
1. (Optional) To configure timers and timer values that are different during the **customer and agent interaction** than during the **customer and custom participant interaction**:
+ Before the agent joins the chat, invoke the [UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html) API again with the configurations you want.
For more information about chat timers, see [Set up chat timeouts for chat participants](setup-chat-timeouts.md).
### Starting timers
Starting timers
A timer begins for the customer after the custom participant establishes a connection to them using the [CreateParticipantConnection](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-participant_CreateParticipantConnection.html) API.
### What happens when non-compatible participants join a chat with a custom participant
What happens when non-compatible participants join a chat with a custom participant
Following is what happens when an agent or Lex bot participant joins a chat with a custom participant, and they are non-compatible participants:
1. The custom participant is automatically disconnected from the chat.
1. All previously active timers are terminated and new timers are created for the connected participants (if timers are configured).
1. Each new timer is also updated with the latest configuration (if needed). This effectively establishes a new "Idle session" for the new set of active participants on the chat.
### Interaction with the Wait block timer
Interaction with the Wait block timer
The idle timer does not impact how the [Wait](wait.md) block works.
The **Wait** block timer that starts when the chat contact enters a **Wait** block continues to work. If the **Wait** block timer expires, the contact resumes the flow and is routed down the **Time Expired** branch, regardless of whether any idle participant timers are active.
## Troubleshooting tips
+ `ResourceNotFoundException`:
If you get a `ResourceNotFoundException` for the custom participant when calling the `CreateParticipantConnection` API, check whether the `CreateParticipantConnection` API was called within 15 seconds of `CreateParticipant` API.
+ `AccessDeniedException`:
If you get an `AccessDeniedException` error and the participant role is a CUSTOM\$1BOT, it indicates the bot is trying to access attachments. The participant role of CUSTOM\$1BOT is not permitted to access attachments that customers upload.
# Set up customer authentication in Amazon Connect for chat contacts
Set up customer authentication
You can prompt your customers to sign in and authenticate during a chat. For example, unauthenticated customers engaged with a chat bot can be prompted to sign in before to being routed to an agent.
This built-in capability leverages Amazon Connect Customer Profiles and [Amazon Cognito](https://aws.amazon.com/cognito/). There are no additional costs for using Customer Profiles, which is already [enabled](enable-customer-profiles.md) in your Amazon Connect instance if you chose the default settings during setup. For information about Amazon Cognito pricing, see the [Amazon Cognito pricing](https://aws.amazon.com/cognito/pricing/) page.
To set up customer authentication for chat:
1. [Enable customer authentication](enable-connect-managed-auth.md#enable-customer-auth) for your Amazon Connect instance.
1. [Enable the authentication message](enable-connect-managed-auth.md#enable-auth-message).
1. Add an [Authenticate Customer](authenticate-customer.md) block to your flow.
If your contact center is using an existing authentication solution external to Amazon Connect, see [Pre-chat authentication](pre-chat-auth.md).
# Enable customer authentication for hosted communication widgets
Enable customer authentication
This topic explains how to set up authentication if you're using the Amazon Connect hosted communication widget for chat. You enable customer authentication for your Amazon Connect instance, and then enable an authentication message that displays a link which opens a popup to the Amazon Cognito hosted UI.
## Required IAM policies
Required IAM policies
If you use custom IAM policies to manage access to the Amazon Connect console, see [Required permissions for custom IAM policies](security-iam-amazon-connect-permissions.md) for a list of the permissions needed to access the **Customer authentication** page.
## Enable customer authentication in your Amazon Connect instance
Enable customer authentication in your instance
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. On the left navigation menu, choose **Applications**, **Customer Authentication**. If you don't see this option, it may not be available in your AWS Region. For information about where customer authentication is available, see [Customer authentication availability by Region](regions.md#customerauthentication_region).
1. On the **Customer authentication** page, choose **Create user pool in Amazon Cognito**. This opens the Amazon Cognito console.
1. Create a new user pool with your identity provider. For instructions, see [Getting started with user pools](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-user-pools.html) in the *Amazon Cognito Developer Guide*.
**Note**
You must select **Don't generate a client secret** when you configure your Amazon Cognito app client. Only Amazon Cognito app clients without client secrets are supported. For more information, see [Application-specific settings with app clients](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) in the *Amazon Cognito Developer Guide*.
1. After you have created an Amazon Cognito user pool, return to the **Customer authentication** page and choose **Associate User Pool**.
1. In the **User Pool **section, choose the user pool you created from the dropdown menu, and then choose **Confirm**.
This associates the user pool to your Amazon Connect instance. It enables the [Authenticate Customer](authenticate-customer.md) flow block to access the user pool.
1. Continue to the next step: [Enable the authentication message](#enable-auth-message).
## Enable the authentication message
Enable the authentication message
To enable the authentication message, add the authentication parameters snippet variable at the end of your snippet. For information about adding snippet variables, see [Supported widget snippet fields in Amazon Connect that are customizable](supported-snippet-fields.md). The following code is an example of the authentication parameters snippet you need to add.
```
amazon_connect('authenticationParameters', {
redirectUri: 'your_redirect_url', // https://example.com
identityProvider: 'your_identity_provider_name' //optional
});
```
Where:
+ `redirectUri` is the redirect URI you configured in your IdP (Identity Provider) and Amazon Cognito. This is where your customer is automatically directed after signing in. In this page you can check the URL parameters and if there is a code and state, you can call the [UpdateParticipantAuthentication](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantAuthentication.html) API with those values. After the API call completes, close the popup; the customer is returned to the chat experience.
+ `identityProvider` is the identity provider name you configured in Amazon Cognito. This field is optional. If a value is provided, then the sign in link automatically directs the customer to the login page of the identity provider instead of to the Amazon Cognito-managed login page where they would have to select an identity provider to use for login.
When the flow reaches the [Authenticate Customer](authenticate-customer.md) block, you can register a callback and store the state locally to validate in the redirect URI, as shown in the following example code snippet:
```
amazon_connect('registerCallback', {
'AUTHENTICATION_INITIATED' : (eventName, data) => {
console.log(data.state)
},
});
```
After you enable customer authentication, add an [Authenticate Customer](authenticate-customer.md) block to your flow. This block authenticates chat contacts during the flow, and route them to specific paths based on the authentication result.
# Pre-chat authentication using the Amazon Connect StartChatContact API
Pre-chat authentication
Customers who authenticate in your website or mobile application before starting a chat can be recognized as authenticated when a chat is initiated. You can do this by using the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API.
After an authenticated customer starts a chat, set their status using the parameters in the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API, as shown in the following code snippet:
```
"SegmentAttributes": {
"connect:CustomerAuthentication" : {
"ValueMap": {
"Status": {
"ValueString": "AUTHENTICATED"
}
}
},
"CustomerId": "12345"
```
`CustomerId` is an optional field to identify the customer. This can be either an Amazon Connect Customer Profiles ID or a custom identifier from an external system, such as a CRM.
# Enable message streaming for AI-powered chat
Enable message streaming for AI-powered chat
Amazon Connect supports message streaming for AI-powered chat interactions. Responses from AI agents appear progressively as they're generated, improving the customer experience during conversations.
The following are integration options, along with features of each option:
+ Amazon Connect agents
+ Eliminates Amazon Lex timeout limitations
+ Provides fulfillment messages during processing (such as "One moment while I review your account")
+ Displays partial responses with progressive text (growing text bubble)
+ Third-party bots via Amazon Lex or Lambda
+ Eliminates Amazon Lex timeout limitations
+ Standard bot response behavior
Instances created starting December 2025 are automatically opted into this feature. For existing instances, you must enable message streaming manually using the API or through the console.
## Enable message streaming using the API
Use the [UpdateInstanceAttribute](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateInstanceAttribute.html) API to enable message streaming. Set the `MESSAGE_STREAMING` attribute to `true`.
```
aws connect update-instance-attribute \
--instance-id your-instance-id \
--attribute-type MESSAGE_STREAMING \
--value true
```
To opt out, set the attribute to `false`.
## Enable message streaming using the console
For newly created instances, message streaming is enabled by default.
For existing instances:
1. Open the Amazon Connect console and choose your instance.
1. In the navigation pane, choose **Flows** > **Amazon Lex bots**.
1. Under **Lex bots configuration**, select **Enable message streaming in Amazon Connect**.
**Note**
When you enable message streaming using the console, the required `lex:RecognizeMessageAsync` permission is automatically added to the bot alias resource-based policy. When using the API, you must add this permission manually.
![\[Enable message streaming option in the Amazon Connect console.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/message-streaming-ai-chat-enablement.png)
## Update Lex bot permissions
After message streaming is enabled, Amazon Connect needs permission to call the Amazon Lex API:
```
lex:RecognizeMessageAsync
```
You must update the resource-based policy for each Amazon Lex bot alias used by the Amazon Connect instance.
### When to update the bot's resource-based policy
+ **New instances** – Any newly associated Amazon Lex bot alias will have `lex:RecognizeMessageAsync` in its alias policy by default.
+ **Existing instances with existing bots** – If the instance previously used Amazon Lex and you enable message streaming now, you must update the resource-based policy on all associated Amazon Lex bot aliases to include the new permission.
### Example snippet for Lex bot alias resource-based policy
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "connect-us-west-2-MYINSTANCEID",
"Effect": "Allow",
"Principal": {
"Service": "connect.amazonaws.com"
},
"Action": [
"lex:RecognizeMessageAsync",
"lex:RecognizeText",
"lex:StartConversation
],
"Resource": "arn:aws:lex:us-west-2:123456789012:bot-alias/MYBOT/MYBOTALIAS",
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "123456789012"
},
"ArnEquals": {
"AWS:SourceArn": "arn:aws:connect:us-west-2:123456789012:instance/MYINSTANCEID"
}
}
}
]
}
```
You can add this permission by calling the Amazon Lex [UpdateResourcePolicy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UpdateResourcePolicy.html) API to update the Amazon Lex bot alias resource-based policy to include the `lex:RecognizeMessageAsync` action for the Amazon Connect instance ARN resource.
**Important**
This feature currently does not support branching back to the same [Flow block in Amazon Connect: Get customer input](get-customer-input.md) flow block or reusing a Amazon Lex bot with the same alias in another **Get customer input** block. Instead, create a new **Get customer input** block using a different Amazon Lex bot alias.
## Timeout limits
The following timeout limits apply to chat experiences:
+ **Standard chat experience** – 10-second timeout
+ **Chat streaming** – 60-second timeout
# Enable in-flight sensitive data redaction and message processing
Enable in-flight sensitive data redaction and message processing
Amazon Connect supports message processing that intercepts and modifies chat messages before they reach any participant. This capability enables automatic redaction of sensitive data and custom message processing, helping businesses maintain compliance and security standards.
The following are processing options, along with features of each option:
+ Built-in sensitive data redaction
+ Automatically detects and removes credit card numbers, social security numbers, and other PII
+ Supports multiple languages, including English, French, Portuguese, German, Italian, and Spanish variants. For a list of the languages supported by Contact Lens redaction, see [Languages supported by Amazon Connect features](supported-languages.md).
+ Choose to redact selected or all sensitive data entities
+ Replace with generic placeholders ([PII]) or entity-specific placeholders ([NAME], [CREDIT\$1CARD])
+ Custom message processors (via Lambda). For more information, see [What is Lambda?](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) in the AWS *Lambda Developer's Guide*.
+ Integrate third-party services for language translation
+ Apply profanity filtering
+ Transform messages using AI/LLM services
+ Implement business-specific message modifications
To configure message processing, define redaction rules in the **Set recording and analytics behavior** block. For more information, see [Enable redaction of sensitive data](enable-analytics.md#enable-redaction). You can also specify a Lambda function for custom processing.
Your custom processor Lambda will take in an input JSON in the following format:
```
{
"version": "1.0",
"instanceId": "string",
"associatedResourceArn": "string",
"chatContent": {
"absoluteTime": "string",
"content": "string",
"contentType": "string",
"id": "string",
"participantId": "string",
"displayName": "string",
"participantRole": "string",
"initialContactId": "string",
"contactId": "string"
}
}
```
And output a JSON in the following format:
```
{
"status": "string", // "PROCESSED"|"APPROVED"|"FAILED"|"REJECTED"
"result": {
"processedChatContent": {
"content": "string",
"contentType": "string" // "text/plain"|"text/markdown"|"application/json"
}
}
}
```
The processed chat content will replace the original message when published to chat participants.
# Set up SMS messaging in Amazon Connect
Set up SMS messaging
You can enable SMS messaging on Amazon Connect so your customers can text you from their mobile device. With Amazon Lex, you can automate responses to their questions, saving agents valuable time and effort.
This topic explains how to set up and test SMS messaging for Amazon Connect. You use AWS End User Messaging SMS to procure an SMS-enabled phone number, enable two-way SMS on the number, and then import it into Amazon Connect.
Using one phone number that is shared for both voice and SMS isn't supported.
**Topics**
+ [Step 1: Request a number in AWS End User Messaging SMS](#get-sms-number)
+ [Step 2: Enable two-way SMS on the phone number](#enable-twoway-sms)
+ [Step 3: Update flows to branch on SMS contacts](#branch-on-sms-contacts)
+ [Step 4: Test sending and receiving SMS messages](#test-sms)
+ [Step 5: Prerequisites for going into production](#verify-sms-config)
+ [Customers not receiving SMS messages?](#ts-sms-config)
+ [Next steps](#sms-nextsteps)
## Step 1: Request a number in AWS End User Messaging SMS
Step 1: Request a number in AWS End User Messaging SMS
**Important**
Some countries require phone numbers to be registered for use in the country. It can take up to 15 business days to process a registration request after it is submitted. We strongly recommend you begin this process early. For more information about registering, see [Registrations](https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations.html).
We also strongly recommend reviewing [Best practices for requesting SMS numbers](sms-number.md#bp-request-sms-number) before requesting a number.
For instructions for using the CLI to perform this step, see [Request a phone number](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-request.html) in the *AWS End User Messaging SMS User Guide*.
1. Open the AWS SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/).
1. In the navigation pane, under **Configurations**, choose **Phone numbers** and then **Request originator**.
1. On the **Select country** page you must choose the **Message destination country** from the drop down that messages will be sent to. Choose **Next**.
1. On the **Messaging use case** section, enter the following:
+ Under **Number capabilities** choose either **SMS** or **Voice**, depending on your requirements.
**Important**
Capabilities for SMS and Voice can't be changed after the phone number has been purchased.
+ **SMS** – Choose if you need SMS capabilities.
+ **Voice (text to audio)** – Choose if you need voice capabilities.
+ Under **Estimated monthly SMS message volume per month – optional** choose the estimated number of SMS messages you will send each month.
+ For **Company headquarters - optional** choose either of the following:
+ **Local** – Choose this if your company headquarters is in the same country as your customers who will receive SMS messages. For example, you would choose this option if your headquarters is in the United States and your users who will receive messages are also in the United States.
+ **International** – Choose this if your company headquarters is not in the same country as your customers who will receive SMS messages.
+ For **Two-way messaging** choose **Yes** if you require two-way messaging.
1. Choose **Next**.
1. Under **Select originator type** choose one of the recommended phone number type or one of the available number types. The available options are based on the use case information you filled out in the previous steps.
+ If you choose 10DLC and already have a registered campaign, you can choose the campaign from the **Associate to registered campaign**.
+ If the number type you want isn't available, you can choose **Previous** to go back and modify your use case. Also check the [Supported countries and regions (SMS channel)](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-sms-by-country.html) to make sure the originator type you want is supported in the destination country.
+ If you want to request a short code or long code, you need to open a case with Support. For more information, see [Requesting short codes for SMS messaging with Amazon Pinpoint SMS](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-request-short-code.html) and [Requesting dedicated long codes for SMS messaging with Amazon Pinpoint SMS](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-long-code.html).
1. Choose **Next**.
1. On **Review and request** you can verify and edit your request before submitting it. Choose **Request**.
1. A **Registration Required** window may appear depending on the type of phone number you requested. Your phone number is associated with this registration and can't send messages until your registration has been approved. For more information about registrations requirements, see [Registrations](https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations.html).
1. For **Registration form name** enter a friendly name.
1. Choose **Begin registration** to finish registering the phone number or **Register later**.
**Important**
Your phone number can't send messages until your registration has been approved.
You are still billed the recurring monthly lease fee for the phone number regardless of registration status.
## Step 2: Enable two-way SMS on the phone number
Step 2: Enable two-way SMS on the phone number
After you have successfully procured a phone number from AWS End User Messaging SMS, you enable two-way SMS on the phone number with Amazon Connect as the message destination. You can enable two-way SMS messaging for individual phone numbers. When one of your customers sends a message to your phone number, the message body is sent to Amazon Connect.
For instructions for using the CLI to perform this step, see [Two-way SMS messaging](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-two-way-sms.html) in the *AWS End User Messaging SMS User Guide*.
**Note**
Amazon Connect for two-way SMS is available in the AWS Regions listed in [Messaging integrations](regions.md#messaging-integrations_region).
1. Open the AWS SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/).
1. In the navigation pane, under **Configurations**, choose **Phone numbers**.
1. On the **Phone numbers** page choose a phone number.
1. On the **Two-way SMS** tab choose the **Edit settings** button.
1. On the **Edit settings** page choose **Enable two-way message**, as shown in following image.
![\[The AWS End User Messaging SMS edit settings page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/sms-edit-settings.png)
1. For **Destination type** choose **Amazon Connect**.
1. For Amazon Connect in **Two-way channel role** choose **Choose existing IAM roles**.
1. In the **Existing IAM roles** drop down choose an existing IAM role as the message destination. For example IAM policies, see [IAM policies for Amazon Connect](https://docs.aws.amazon.com/sms-voice/latest/userguide/phone-numbers-two-way-sms.html#phone-number-two-way-connect-iam-policy) in the *AWS End User Messaging SMS User Guide*.
**Tip**
If you can't create a policy or role, double-check that your Amazon Connect instance is in a [Region supported by Amazon Connect SMS](regions.md#messaging-integrations_region).
1. Choose **Save changes**.
1. In the **Import Phone Number to Amazon Connect** window:
1. For the **Incoming messages destination** drop down choose the Amazon Connect instance that will receive incoming messages.
![\[The AWS End User Messaging SMS import phone numbers page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/sms-import-phone-number.png)
1. Choose **Import Phone Number**.
1. After the number is successfully imported to Amazon Connect, you can view it in the Amazon Connect admin website: In the left navigation, choose **Channels**, **Phone numbers**. The SMS number appears on the **Phone numbers** page, as shown in the following image.
![\[The Amazon Connect admin website, the Phone numbers page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/golden-sms-channel.png)
## Step 3: Update flows to branch on SMS contacts
Step 3: Update flows to branch on SMS contacts
If you have existing flows that you want to branch when a contact uses SMS, add a [Check contact attributes](check-contact-attributes.md) block to your flows. This block enables you to send SMS contacts to a specific queue, or take another action.
1. Add a [Check contact attributes](check-contact-attributes.md) block to your flow, and open the **Properties** page.
1. In **Attribute to check** section, set **Namespace** to **Segment attributes** and **key** to **Subtype**.
For more information about Segment attributes, see [SegmentAttributes](ctr-data-model.md#segmentattributes) in the *ContactTraceRecord* topic.
1. In the **Conditions to check** section, set **condition** to **Equals** and **value** to **connect:SMS**.
The following image of a **Properties** page shows it's configured to branch when the contact comes in on the SMS channel.
![\[The properties page of the check contact attributes block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/golden-check-attributes-block.png)
1. Associate the SMS phone number with the flow: In the left navigation, choose **Channels**, **Phone numbers**, choose the SMS number, and then choose **Edit**.
![\[The Edit phone number page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/golden-sms-number.png)
1. Under **Flow/IVR**, choose the flow you updated, and then choose **Save**.
![\[The properties page of the check contact attributes block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/golden-assign-flow-sms-number.png)
**Tip**
When you first purchase a phone number, the phone number's status is **Pending**. When the phone number is ready to use, the phone number's status is **Active**. If the phone number requires [registration](https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations.html), then you must complete that step before the phone number's status changes to **Active**.
## Step 4: Test sending and receiving SMS messages
Step 4: Test sending and receiving SMS messages
In this step you use the Contact Control Panel (CCP) and a mobile phone to test sending and receiving SMS messages.
1. In your CCP, set your status to **Available**.
1. Using a mobile device, send an SMS to the phone number that you requested in [Step 1: Request a number in AWS End User Messaging SMS](#get-sms-number).
**Tip**
If your AWS End User Messaging SMS phone number is still in the SMS sandbox, you can only test sending and receiving SMS messages with verified destination numbers that you have configured. For move instructions, see [Moving from the SMS sandbox to production](https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations.html).
![\[The agent's CCP and the customer's phone sending SMS messages.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/sms-testing2.png)
## Step 5: Prerequisites for going into production
Step 5: Prerequisites for going into production
Before you use SMS in production mode, make sure you've completed the following prerequisites for AWS End User Messaging SMS.
1. [Move your account out of SMS/MMS sandbox mode](https://docs.aws.amazon.com/sms-voice/latest/userguide/sandbox.html)
1. [Set up your registration for SMS/MMS](https://docs.aws.amazon.com/sms-voice/latest/userguide/registrations.html)
1. [Confirm that your spend quota matches your usage requirements](https://docs.aws.amazon.com/sms-voice/latest/userguide/awssupport-spend-threshold.html)
1. [Check your opt-out lists](https://docs.aws.amazon.com/sms-voice/latest/userguide/opt-out-list.html)
## Customers not receiving SMS messages?
Customers not receiving SMS messages?
Before opening an AWS Support ticket, please verify that you've completed [Step 5: Prerequisites for going into production](#verify-sms-config).
## Next steps
Next steps
We recommend the following steps to provide the best experience for your agents and customers.
+ [Enable customers to resume chat conversations in Amazon Connect](chat-persistence.md): Customers can resume previous conversations with the context, metadata, and transcripts carried forward. They don't need to repeat themselves when they return to a chat, and agents have access to the entire conversation history.
+ [Create quick responses for use with chat and email contacts in Amazon Connect](create-quick-responses.md): Provide agents with pre-written responses to common customer inquiries that they can use while they chat with customers. Quick responses make it faster for agents to respond to customers.
# Add the Amazon Connect widget to your website to accept chat, task, email, and web calling contacts
Add the Amazon Connect widget to your website
The topics in this section explain how to create and customize a communications widget for your website. You'll create a contact form that determines the behavior for contacts created through your widget, and then customize the widget's appearance and functionality.
**Topics**
+ [
## Step 1: Create a contact form for your widget
](#create-web-form)
+ [
## Step 2: Customize your communications widget
](#customize-communications-widget)
+ [
## Step 3: Specify the website domains where you expect to display the communications widget
](#communications-widget-domains)
+ [
## Step 4: Confirm and copy communications widget code and security keys
](#confirm-and-copy-communications-widget-script)
## Step 1: Create a contact form for your widget
In this step, you create and customize a View that determines the behavior for contacts created through your widget.
1. Log in to the Amazon Connect admin website at [https://instance name.my.connect.aws/](https://instance name.my.connect.aws/). Under the **Routing** tab, select **Flows**.
1. At the top left, click **Views**.
1. Select **Create View**.
1. Here you can configure a contact form for your customers using the [no-code builder](no-code-ui-builder.md). Some important tips:
+ Using the Form component will allow you to link Form Inputs to your contact on creation. Form linking will allow you to take input directly from anyone interacting with your widget and use the information they include in the form during contact creation.
+ The Connect Action component is the most important element in the form for creating a contact. This component should be used without any other button type components in the form.
+ Exactly one Connect Action component must be present to use the View with a Contact Form widget.
+ There are three options supported for ConnectActionType for the Connect Action component:
+ StartEmailContact
+ StartTaskContact
+ StartChatContact
Both Email and Task can be used in a contact form. To create a pre-chat form for chat contacts, see [Add a chat user interface to your website hosted by Amazon Connect](add-chat-to-website.md).
+ There are many style options for the View components, allowing you to customize the form to fit your environment.
1. Once you’ve added a **Connect Action button** to your form, you can set values for the contacts created by the form by linking them to the options in the Connect Action button. Components that you would like to link must be in the same Form in the View as the **Connect Action button**.
![\[The activation of security for new communication widget requests.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-web-form-components-1.png)
The following components are supported for form linking:
+ Form Input
+ Dropdown (turn off multi-select)
+ Date Picker
+ Text Area
+ Time Picker
1. Once your View is ready, select **Publish**.
## Step 2: Customize your communications widget
In this step, you customize the experience of the communications widget for your customers.
1. Log in to the Amazon Connect admin website at [https://instance name.my.connect.aws/](https://instance name.my.connect.aws/). Choose **Customize communications widget**.
1. On the Communications widgets page, choose **Add communications widget** to begin customizing a new communications widget experience. To edit, delete, or duplicate an existing communications widget, choose from the options under the **Actions** column.
1. Enter a **Name** and **Description** for the communications widget.
**Note**
The Name must be unique for each communications widget created in an Amazon Connect instance.
1. In the **Communications options** section, select **Add Contact Form**.
1. Select the View you configured in the previous step. If the Connect Action component in the View does not have a contact flow set, you will need to set one here.
1. Click **Save and Continue**.
On the **Create communication widget** page, choose the widget button styles, and display names and styles. As you choose these options, the widget preview updates automatically so that you can see what the experience will look like for your customers.
**Note**
The preview does not display the View contact form that you've created. Only the header styling is displayed.
### Display type
You may choose between two display types for Contact Form widgets:
+ *Floating action button* allows you to pin your widget as an interactable button on the bottom right corner of the web page
+ *Embedded inline* allows you to embed your widget directly in the web page without requiring a button push to load it
### Button styles
1. Choose the colors for the button background by entering hex values (HTML color codes).
1. Choose White or Black for the icon color. The icon color can't be customized.
### Widget header
1. Provide values for header message and color, and widget background color.
1. *Logo URL:* Insert a URL to your logo banner from an Amazon S3 bucket or another online source.
**Important**
The communications widget preview in the customization page will not display the logo if it's from an online source other than an Amazon S3 bucket. However, the logo will be displayed when the customized communications widget is implemented to your page.
The banner must be in .svg, .jpg or .png format. The image can be 280px (width) by 60px (height). Any image larger than those dimensions will be scaled to fit the 280x60 logo component space.
+ For instructions about how to upload a file such as your logo banner to S3, see [Uploading objects](#) in the *Amazon Simple Storage Service User Guide*.
+ Make sure that the image permissions are properly set so that the communications widget has permissions to access the image. For information about how to make a S3 object publicly accessible, see [Step 2: Add a bucket policy](#) in the Setting permissions for website access topic.
## Step 3: Specify the website domains where you expect to display the communications widget
1. Enter the website domains where you want to place the communications widget. The widget loads only on websites that you select in this step.
Choose **Add domain** to add up to 50 domains.
![\[The add domain option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-add-domain.png)
Domain allowlist behavior:
+ Subdomains are automatically included. For example, if you allow example.com, all its subdomains (like sub.example.com) are also allowed.
+ Protocol http:// or https:// must exactly match your configuration. Specify the exact protocol when setting up allowed domains.
+ All URL paths are automatically allowed. For example, if example.com is allowed, all pages under it (such as example.com/cart or example.com/checkout) are accessible. You cannot allow or block specific subdirectories.
**Important**
Double-check that your website URLs are valid and does not contain errors. Include the full URL starting with https://.
We recommend using https:// for your production websites and applications.
1. Under **Add security for your communications widget**, we recommend choosing **Yes**, and working with your website administrator to set up your web servers to issue JSON Web Tokens (JWTs) for new contact requests. This provides you more control when initiating new contacts, including the ability to verify that requests sent to Amazon Connect are from authenticated users.
![\[The activation of security for new communication widget requests.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-choose-security.png)
Choosing **Yes** results in the following:
+ Amazon Connect provides a 44-character security key on the next page that you can use to create JSON Web Tokens (JWTs).
+ Amazon Connect adds a callback function within the communications widget embed script that checks for a JSON Web Token (JWT) when a contact is initiated.
You must implement the callback function in the embedded snippet, as shown in the following example.
```
amazon_connect('authenticate', function(callback) {
window.fetch('/token').then(res => {
res.json().then(data => {
callback(data.data);
});
});
});
```
If you choose this option, in the next step you'll get a security key for all contact requests initiated on your websites. Ask your website administrator to set up your web servers to issue JWTs using this security key.
1. Choose **Save**.
## Step 4: Confirm and copy communications widget code and security keys
In this step, you confirm your selections and copy the code for the communications widget and embed it in your website. If you chose to use JWTs in [Step 3](#communications-widget-domains), you can also copy the secret keys for creating them.
### Security key
Use this 44-character security key to generate JSON web tokens from your web server. You can also update, or rotate, keys if you need to change them. When you do this, Amazon Connect provides you with a new key and maintains the previous key until you have a chance to replace it. After you have the new key deployed, you can come back to Amazon Connect and delete the previous key.
![\[The security key provided by Amazon Connect.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-security-key.png)
When your customers interact with the communications widget on your website, the widget requests your web server for a JWT. When this JWT is provided, the widget will then include it as part of the end customer's contact request to Amazon Connect. Amazon Connect then uses the secret key to decrypt the token. If successful, this confirms that the JWT was issued by your web server and Amazon Connect routes the contact request to your contact center agents.
#### JSON Web Token specifics
+ Algorithm: **HS256**
+ Claims:
+ **sub**: *widgetId*
Replace `widgetId` with your own widgetId. To find your widgetId, see the example at [Communications widget script](#communications-widget-script).
+ **iat**: \$1Issued At Time.
+ **exp**: \$1Expiration (10 minute maximum).
+ **segmentAttributes (optional)**: A set of system defined key-value pairs stored on individual contact segments using an attribute map. For more information check SegmentAttributes in the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-SegmentAttributes) API.
+ **attributes (optional)**: Object with string-to-string key-value pairs. The contact attributes must follow the limitations set by the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-Attributes) API.
+ **relatedContactId (optional)**: String with valid contact id. The relatedContactId must follow limitations set by the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API.
+ **customerId (optional)**: This can be either an Amazon Connect Customer Profiles ID or a custom identifier from an external system, such as a CRM.
\$1 For information about the date format, see the following Internet Engineering Task Force (IETF) document: [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519), page 5.
The following code snippet shows an example of how to generate a JWT in Python:
```
import jwt
import datetime
CONNECT_SECRET = "your-securely-stored-jwt-secret"
WIDGET_ID = "widget-id"
JWT_EXP_DELTA_SECONDS = 500
payload = {
'sub': WIDGET_ID,
'iat': datetime.datetime.utcnow(),
'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=JWT_EXP_DELTA_SECONDS),
'customerId': "your-customer-id",
'relatedContactId':'your-relatedContactId',
'segmentAttributes': {"connect:Subtype": {"ValueString" : "connect:Guide"}}, 'attributes': {"name": "Jane", "memberID": "123456789", "email": "Jane@example.com", "isPremiumUser": "true", "age": "45"} }
header = { 'typ': "JWT", 'alg': 'HS256' }
encoded_token = jwt.encode((payload), CONNECT_SECRET, algorithm="HS256", headers=header) // CONNECT_SECRET is the security key provided by Amazon Connect
```
### Communications widget script
The following image shows an example of the JavaScript that you embed on the websites where you want customers to interact with your contact center. This script displays the widget in the bottom-right corner of your website.
**Note**
Include the widget script in the HTML element that needs to render the widget when using the Embedded inline style.
![\[The communications widget script.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-code.png)
When your website loads, customers first see the widget icon. When they choose this icon, the communications widget opens and customers are able to initiate contact with your agents.
To make changes to the communications widget at any time, choose **Edit**.
**Note**
Saved changes update the customer experience in a few minutes. Confirm your widget configuration before saving it.
![\[The edit link on the widget preview.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-edit.png)
To make changes to widget icons on the website, you will receive a new code snippet to update your website directly.
# Enable Apple Messages for Business with Amazon Connect
Enable Apple Messages for Business
Your customers can engage directly with your contact center from within their Messages application on their iPhone, iPad, and Mac.
When you enable Apple Messages for Business, your customers can find answers to their questions and request help from agents to resolve issues, while using the familiar Messages application they use every day to chat with friends and family. Any time customers use Search, Safari, Spotlight, Siri, or Maps to call your registered phone number, they will be provided with the option to chat with your contact center.
Apple Messages for Business integration with Amazon Connect enables you to use the same configuration, analytics, routing, and agent UI that you already use for [Amazon Connect Chat](web-and-mobile-chat.md).
## Prerequisites: Determine if Apple Messages for Business is the right channel for your use case
In order to qualify as a business, make sure you meet the criteria listed in the [Apple Messages for Business documentation](https://register.apple.com/resources/messages/messaging-documentation/#qualifying-as-a-business).
If you determine that Apple Messages for Business is the right channel for your business, fill in the following forms:
+ [Apple Messages for Business readiness document](https://register.apple.com/resources/messages/messaging-documentation/resources/Messages-for-Business_Readiness.pdf)
+ [Description of your four primary use cases for Apple Messages for Business](https://register.apple.com/resources/messages/messaging-documentation/resources/Messages-for-Business_UseCases.pdf)
## Step 1: Register with Apple
Integrate Apple Messages for Business with Amazon Connect by first registering with Apple as a brand. When you do, you'll get a unique Apple Messages for Business Account ID, and you can then link your Apple Messages for Business account to Amazon Connect.
1. Go to the [Apple Messages for Business](https://register.apple.com/business-chat) page. In the box that says **As a business, I want to connect with my customers in the Messages app**, choose **Get Started**.
1. Create an Apple ID for your business, if you don't already have one.
An Apple ID is typically for the personal use of Apple services, such as storing personal content in iCloud and downloading apps from the App Store. If you have a personal Apple ID, we recommend that you create a separate one using your organization’s email address to administer Messages for Business. A separate administrative Apple ID lets you distinguish Messages for Business communications from personal Apple communications.
1. Register a profile for a new Messages for Business account by accepting **Apple’s Terms of Service**. We recommend creating a [Commercial Messages for Business Account](https://register.apple.com/resources/messages/messaging-documentation/register-your-acct#create-a-commercial-business-chat-account). You then provide business details, such as a logo and support hours.
1. Select Amazon Connect as your Messaging Service Provider. You can do this by selecting Amazon Connect from the drop-down or by entering the following URL:
+ **https://messagingintegrations.connect.amazonaws.com/applebusinesschat**
After you submit your application to Apple, you’ll see the status of your application at the top of your **Messages for Business Account** page.
For more information about registering with Apple, see the following articles on Apple's website: [Getting Started with Messages for Business](https://register.apple.com/resources/business-chat/BC-GettingStarted.pdf) and [Messages for Business Policies and Best Practices](https://register.apple.com/resources/business-chat/BC-Policies_and_Best_Practices.pdf).
## Step 2: Gather required information
Gather the following information so you have it on hand when you open a support ticket in Step 3:
1. **Apple Messages for Business Account ID**: After you’ve been approved by Apple Messages for Business, you will be issued an Apple Messages for Business Account ID. For information about locating your Apple Messages for Business Account ID, see [Find your Apple Messages for Business Account ID for your integration with Amazon Connect](find-apple-messages-for-business-account-id.md).
**Note**
Your Apple Messages for Business Account ID is a randomized string of numbers and letters. It is not the same as your Apple ID.
1. **Apple Token**: This is a unique ID that authenticates your account. For help locating your Apple token, see [Find your Apple token when integrating Apple Messages for Business with Amazon Connect](find-apple-token-id.md).
1. **Amazon Connect instance ARN**: This is the identifier for the instance you want to link to your Apple business account. For information about locating your instance ID, see [Find your Amazon Connect instance ID or ARN](find-instance-arn.md).
**Note**
Make sure you have service-linked roles enabled for the integration.
If your instance was created before **October 2018**, add the `connect:*` policy on the role that is associated with your Amazon Connect instance. For more information about service-linked roles, see [Use service-linked roles and role permissions for Amazon Connect](connect-slr.md).
1. **Amazon Connect flow ID**: This is the identifier for the flow you want to use for inbound chats. For information about locating your flow ID, see [Find the flow ID when integrating Apple Messages for Business with Amazon Connect](find-contact-flow-id.md).
## Step 3: Link your Apple Messages for Business ID to Amazon Connect
In this step you create an Amazon Connect support ticket to link your Apple Messages for Business ID to Amazon Connect.
1. Create a [special Support ticket](https://support.console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=service-chime-end-user&categoryCode=other) to link your Apple Messages for Business to Amazon Connect.
If prompted, login using your AWS account.
**Tip**
Looking for technical support? [Open an Support ticket here](https://console.aws.amazon.com/support/home).
1. Choose **Account and billing**.
1. Use the dropdown box to choose **Chime (End user)**. For **Category** choose **Activation**, and then choose **Next step: Additional information**.
1. For **Subject** enter **Apple Messages for Business Integration request**.
1. In the **Description** box, copy and paste the following template:
```
Subject: Apple Messages for Business Integration request
Body:
Apple Messages for Business Account ID (required): enter your account ID
Apple Token (required): enter your Apple token
Amazon Connect Instance ARN (required): enter your instance ARN
Amazon Connect Flow ID (required): enter your flow ID
```
1. Attach the two forms from the [prerequisites](#apple-messages-for-business-prerequisites) section to the support ticket.
**Note**
This step is required. Your request will not be processed if you do not attach these forms.
The following image shows an example of a completed ticket:
![\[An example completed ticket.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-sample-use-case-description.png)
1. Choose **Next step**.
1. Choose **Contact us**, choose your **Preferred contact language**, and then choose **Web** as the contact method, if it's not selected by default.
![\[The contact methods.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-contact-support-options.png)
1. Choose **Submit**.
1. Support will work directly with the Amazon Connect team on your request and follow up with any additional questions.
### Next steps
After Apple Messages for Business is enabled for your Amazon Connect instance, you can [ add Apple Messages for Business features](add-apple-messages-for-business-features.md) to your messages. For example:
+ Deflect calls with Apple's Message Suggest.
+ Embed Apple Messages for Business buttons on your website.
+ Add list pickers, time pickers, forms, and quick replies to your messages.
+ Add Apple Pay, iMessage Apps, and Authentication to your integration.
+ Use rich links for URLs.
+ Route Apple Messages for Business messages using contact attributes.
+ Enable Attachments for your integration.
Additionally, pass the [Apple experience review](https://register.apple.com/resources/messages/messaging-documentation/xp-review).
## Step 4: Create and Submit Experience Review Recording
Record a demo experience for review by Amazon Connect and Apple Messages for Business. The video must accurately represent the user journey that occurs when the account is in production (all use cases). Only upload a recording of the user's point of view (user's device). You don't need to send recordings from the agent console or the bot activated on the backend. You can split the video into multiple parts if needed. Demonstrate the [Rich Features](https://register.apple.com/resources/messages/messaging-documentation/customer-journey#interactive-features) you have integrated in the experience, the live agent interaction, and any [out of hours messages](https://register.apple.com/resources/messages/messaging-documentation/ux-design#automated-messaging). Make sure you follow Apple Messages for Business's [Best Practices](https://register.apple.com/resources/messages/messaging-documentation/ux-design#best-practices) and [Policies](https://register.apple.com/resources/messages/messaging-documentation/policies).
**Tips for developing the user experience**
+ **Introductory/welcome message:** Auto-respond to first message in a new conversation should be provided within 5 seconds by an automated system. When the customer starts a conversation with an automated system, provide a message like **This is an automated agent** or **I'm an automated agent**. For more information, see [Automated Messaging](https://register.apple.com/resources/messages/messaging-documentation/ux-design#automated-messaging).
+ **Terms of Use and Privacy Policy statements:** These should be handled via a [Rich Link](https://register.apple.com/resources/messages/msp-rest-api/type-richlink#rich-link-messages) to the brand's web site, allowing users to read the full terms at their convenience. Do not send large bubbles of legal text in the conversation. These should only be sent the first time a user engages in the channel with the brand, or when the terms have been updated.
+ **Initial triage:** A triage menu should be sent at the beginning of the interaction. This is a quick way to guide and help the user. You may use a Quick Reply message (up to 5 options). For more information, see [Triage Customers](https://register.apple.com/resources/messages/messaging-documentation/ux-design#triage-customers).
+ **Make an introduction:** Always introduce live agents when a conversation begins, and after transferring a customer to a new agent.
+ **Live support availability:** If a customer sends help outside of normal customer service hours when live agents aren't available, an automated response should let them know when a live agent is able to respond. For more information, see [Automated Messaging](https://register.apple.com/resources/messages/messaging-documentation/ux-design#automated-messaging).
+ **Allow switching from an automated to a live agent:** A live agent must be reachable anytime the customer texts the word "help". Additionally, if an automated agent doesn't understand a request, the agent must seamlessly transition to a live agent after displaying a message like "I'm routing your message to a live agent to better assist you."
+ **Don't ask for previously provided information:** Agents can access the entire conversation history, including previous responses and recent transactions, so there should be no need to ask a customer to repeat information.
+ **Rich Link:** All URLs should be sent as Rich Links. This means that no tap-to-load issues or in-text links should be sent. For more information, see [Use rich links for URLs](add-apple-messages-for-business-features.md#rich-links) .
+ **Feature bubbles:** Should have a relevant thumbnail image and call to action text, so customers are clear on the content of the feature and recognize it as a tap-able item.
+ **We encourage the use of satisfaction surveys:** Once you complete an interaction with a customer, you may want to provide them with a customer service satisfaction (CSAT) survey. For a better customer experience, provide the CSAT surveys after the experience and not after every FAQ. For more information, see [Satisfaction Surveys](https://register.apple.com/resources/messages/messaging-documentation/ux-design#satisfaction-surveys).
+ **Typing indicators:** When an agent, live or automated, starts typing, the typing indicator should be displayed, so the experience is consistent. The typing indicator should be displayed before any message type (text or interactive). For messages sent by bots, as well as messages in sequence, use only a 1-second typing indicators before each message. For more information, see [Typing Indicator Message](https://register.apple.com/resources/messages/msp-rest-api/common-specs#typingindicatormessage).
After your experience review recording is created, you can once again create an Amazon Connect support ticket to share. Feedback will be provided by Amazon Connect and Apple Messages for Business before final approval.
1. Create a [special Support ticket](https://support.console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=service-chime-end-user&categoryCode=other) to share your experience review recording. If prompted, login using your AWS account.
1. Choose **Account and billing**.
1. Use the dropdown box to choose **Chime (End user)**. For **Category** choose **Activation**, and then choose **Next step: Additional information**.
1. For **Subject** enter **Apple Messages for Business Experience Review request**.
1. In the **Description** box, copy and paste the following template:
```
Subject: Apple Messages for Business Experience Review request
Body:
Apple Messages for Business Account ID (required): enter your account ID
```
1. Attach the experience review recording.
1. Choose **Next step**.
1. Choose **Contact us**, choose your **Preferred contact language**, and then choose **Web** as the contact method, if it's not selected by default.
1. Choose **Submit**.
1. Support will work directly with the Amazon Connect team on your request and follow up with any feedback.
# Send a test message for Apple Messages for Business to test integration with Amazon Connect
Send a test message
After onboarding to the Apple Messages for Business account, use the following steps to send a test message to make sure the integration is set up properly.
## Step 1: Add internal testers to your Messages for Business account
1. Sign in to [Apple Business Register](https://register.apple.com/).
1. Choose **Messages for Business Accounts** and select the account to add testers.
1. Scroll down the page to **Account Testing**.
1. Add the Apple IDs of your internal testers.
1. When your list is complete and you are ready to begin testing, choose **Send to new testers** to send an instructional email to your testers.
An instructional email containing a link to your Messages for Business conversation is sent to the Apple ID email address of each tester. If a tester does not receive the email, then recheck that their email address is provided in the Account Testing section. It's most likely that the email address is incorrect or it's not an Apple ID. For security reasons, Apple cannot verify Apple ID email addresses.
## Step 2: Test sending and receiving messages
When your testers get the instructional email, they will need to activate the link in it. After doing this, they can send messages to your agents, who can then reply from the Contact Control Panel (CCP).
Note the following:
1. Design a test to trigger all of your Apple Messages for Business features.
1. You should observe that messages sent from an iOS device arrive to your test business. Employees testing from your support agent desktop should be able to respond to these test messages.
1. Your testers may notice your brand colors are not visible in the Messages header. Brand color is not available while your account is in test mode. The colors for your brand will display correctly after your account goes online.
1. If you send the testing link to someone whose email is not listed in the Account Testing section, they will not be able to send messages.
1. If you provide a Redirect Page URL and your testers try to enter Messages for Business from an unsupported device, they will land either on a default or redirected page. You can set your Redirect Page URL in the **Unsupported Devices** section at the bottom of your Messages for Business account page.
**To begin testing**
1. Check that your testers are using a device with a supported iOS: iOS 11.3 and later, or macOS 10.13.4.
1. Ask your testers to doing the following:
1. Use their supported devices to find the email sent to them.
1. Open the email from the supported device, and then choose the link. It takes them to a Messages for Business conversation in the Messages app.
## Troubleshoot
If you encounter any issues when sending a test message, follow these steps:
1. Confirm that you’ve allowlisted your email address/Apple ID as a tester in your Messages for Business account.
1. Confirm the following settings on your Apple device:
+ Go to **Settings** > **Messages** and check that **iMessage** is enabled.
+ Go to **Settings** > **Messages** > **Send & Receive** and check that the AppleID is correct and messages are allowed to receive.
1. Check that you're using a supported iOS. Apple devices running iOS 11.3 and later or macOS 10.13.4 and later support Messages for Business.
1. When you selected Amazon Connect as your MSP in your Apple Account, did you select **Amazon Connect** from the dropdown? Or did you enter the following URL:
+ https://messagingintegrations.connect.amazonaws.com/applebusinesschat
If you entered the URL, doublecheck for typos.
1. Confirm your Apple business account is **Online** in the [Apple Business Register](https://register.apple.com/). If the account is in a pending state, then select **Send for review**. This needs to be repeated after making additional Apple ID allow-listing changes or other Apple business account configuration changes.
# Enable authentication for Apple Messages for Business
To begin the setup process, first navigate to your Identity Provider.
## Identity Provider Configuration
The following Amazon Connect domain must be registered as an allowed Redirect URI for the Identity Provider(s) used for authentication:
```
https://participant.connect.region.amazonaws.com/participant/authentication/update
```
## Integration with Amazon Cognito
You can [add your Identity Provider(s)](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-identity-provider.html) to an existing Amazon Cognito user pool or create a new [Amazon Cognito user pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html).
Within this user pool you can create an [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) and select some or all of your Identity Providers. Take note of the app client's client ID. For this app client, the following Amazon Connect domain must be added as an Allowed callback URL:
```
https://participant.connect.region.amazonaws.com/participant/authentication/update
```
**Note**
You must select **Don't generate a client secret** when configuring the Amazon Cognito app client. Only Amazon Cognito app clients without client secrets are supported.
## Configure your Amazon Cognito app client with the Apple Messages for Business Portal
On **Integrated OAuth2 Authentication**, configure your Amazon Cognito app client client ID as the **Client Identifier** and your Amazon Cognito user pool domain's [authorization endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html) as the **OAuth URL**.
![\[Customer authentication for Amazon Cognito user pools.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/configuring-your-cognito-app-client-with-the-apple-messages-for-business-portal.png)
## Configure your user pools with Amazon Connect
On the **Customer authentication** page on the Amazon Connect console associate the user pool that will be used for the authentication.
![\[Customer authentication for Amazon Cognito user pools.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/configuring-your-user-pools-with-connect.png)
## Enable Amazon Connect Customer Profiles
**Enable Customer Profiles**
On the **Customer Profiles** page in Amazon Connect console, ensure that Customer Profiles is enabled for your instance. If **No Customer Profiles domain associated with this instance of Amazon Connect.** is displayed, then see [Enable Customer Profiles for your Amazon Connect instance](enable-customer-profiles.md).
![\[Enable customer profiles in the Amazon Connect console.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/apple-messages-for-business-configuring-amazon-connect-customer-profiles.png)
### Grant Customer Profile permission(s) to security profiles (optional)
To grant users (agent, admin) permissions to view/edit/publish Customer Profiles in Agent Workspace, see [Update Customer Profiles permissions for agents](security-profile-customer-profile-agent.md). After permission(s) are granted to security profile(s), users should be able to access the features in the Agent Workspace.
For a detailed list of permissions, see [Customer Profiles security profile permissions](security-profile-list.md#customerprofiles-permissions-list).
## Configure the Authenticate Customer flow block
For instructions, see [Flow block in Amazon Connect: Authenticate Customer](authenticate-customer.md).
# Add Apple Messages for Business features
## Deflect calls with Apple’s Message Suggest
With [Message Suggest](https://register.apple.com/resources/messages/messaging-documentation/message-with-customers#triggering-message-suggest) you can allow users to choose between voice and messaging when tapping on your business phone number in Safari, Maps, Siri, or Search.
To enable Message Suggest, send an email to the Apple Messages for Business Team at **registry@apple.com** with the following information and Apple can set up the channel for you:
+ Provide all of your primary phone numbers, including high call volume phone numbers.
+ Provide phone contact hours to set customer expectations for your after-hours message.
+ Provide intent, group, and body parameters to associate with each phone number.
+ Provide an estimate of how many customers your agents can support per day. This can be increased or decreased depending on operational capacity.
To learn more about enabling Message Suggest, see [Apple’s Message Suggest FAQs](https://register.apple.com/resources/business-chat/faq/business-chat-suggest-faqs.html).
## Embed Apple Messages for Business buttons
To embed Apple Messages for Business buttons on your website or mobile app, do the following:
1. Add Apple’s Messages for Business JS (JavaScript) library to your webpage headers.
1. Add a `div` container to house the button.
1. Customize the banner, fallback support, and button color to meet your brand’s needs.
The Messages for Business button must contain the following, at minimum:
+ A class attribute to specify the type of container: banner, phone, or message.
+ A data-apple-business-id attribute with the business ID you received when you registered your company with Messages for Business.
## Authentication
Authentication allows customers to sign in to your Identity Provider(s) of choice during a chat conversation. The authentication feature leverages the OAuth2 and OIDC framework to verify the identity of the customer upon successful sign in. for more information, see [Enable authentication for Apple Messages for Business](enabling-authentication-for-apple-messages-for-business.md).
## Start a chat from a URL
You can give your customers the ability to start a conversation with you from your website or an email message.
For example, customers may start a chat using a URL that you provide. When they click the URL, the system redirects them to Messages so they can send your business a text message.
You decide how and where to provide the URL. You can include it as a link in an email message, on your website, or use it as the action for a button in your app.
Use the URL **https://bcrw.apple.com/urn:biz:*your-business-id***, replacing *your-business-id* with the business ID you received from Apple after registering with Messages for Business.
Following are optional query string parameters you can include in the URL:
+ `biz-intent-id`: Use to specify the intention, or purpose, of the chat.
+ `biz-group-id`: Use to indicate the group, department, or individuals best qualified to handle the customer's specific question or problem.
+ `body`: Use to prepopulate the message so the customer only presses **Send** to start the conversation.
Following is an example of what the URL might look like for a customer with a credit card question for the billing department:
+ `https://bcrw.apple.com/urn:biz:22222222-dddd-4444-bbbb-777777777777?biz-intent-id=account_question&biz-group-id=billing_department&body=Order%20additional%20credit%20card`.
## Add list pickers, time pickers, forms, attachments, and quick replies
A list picker prompts your customer to select an item, such as a product or the reason for their inquiry. A time picker prompts your customer to choose an available time slot, such as to schedule an appointment. A quick reply prompts your customer to select a simple, inline response. Forms allow you to create rich, multiple page, interactive flows for customers.
For information about how to set up list pickers, time pickers, forms, and quick replies, see [Add Amazon Lex interactive messages for customers in chat](interactive-messages.md).
For information about how to enable attachments, see [Enable attachments to share files using chat](enable-attachments.md).
## Apple Pay
Apple Pay allows consumers to complete purchases without having to manage paper bills, coins, or physical bank cards. Using Apple Messages for Business, consumers can complete transactions with their favorite brands without having to leave the Messages app.
Apple Pay is a distinct feature, but shares similarities to Apple Pay in-app and Apple Pay on the Web. When a business asks for payment from a customer who is purchasing goods and services through Apple Messages for Business, the customer can use Apple Pay to make the payment.
![\[Picture of a smartphone using Apple Pay.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/apple-pay-1.png)
To learn more about Apple Pay, see [Apple Pay for developers](https://developer.apple.com/apple-pay/).
For information about how to set up Apple Pay using Connect, see [Add Amazon Lex interactive messages for customers in chat](interactive-messages.md).
## iMessage Apps
iMessage apps or Apple Custom Interactive Messages (CIM) increase interactivity between end-customers and business customers, allowing end-customers to receive iMessage Apps from businesses. These iMessage Apps contain a richer set of information for end-customers to interact with completely inside of Apple’s Messages app, allowing the end-customer to remain in the conversation to perform the same interactions. This makes the Apple CIM more customizable than other existing interactive message types.
The following figure is an example of an iMessage App sent using an Apple CIM with a detailed map and location pin:
![\[Image of an iMessage app sent using an Apple CIM with a detailed map and location pin.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/imessage-apps-1.png)
For information about how to set iMessage Apps using Amazon Connect, see [Add Amazon Lex interactive messages for customers in chat](interactive-messages.md).
## Use rich links for URLs
Rich links show an inline preview of a URL that contains an image or video. Unlike normal URLs, customers can view the image or video preview immediately in a chat without choosing a "Tap to Load Preview" message.
### Requirements for using rich links in Amazon Connect
To use rich links in Amazon Connect chat messages, your URL and images must meet the following requirements:
+ Your website must use Facebook Open Graph tags. For more information, see [A Guide to Sharing for Webmasters](https://developers.facebook.com/docs/sharing/webmasters/).
+ The image accompanying the URL must be .jpeg, .jpg, or .png.
+ The website must be HTML.
**Note**
When you first use the rich link feature, we recommend that you send the URL in a message separate from your chat text, as shown in the following example. The first message introduces the URL. The next message includes the URL.
![\[A URL sent in a chat message.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-rich-link.png)
## Use Apple Messages for Business contact attributes in contact flows
Contact attributes enable you to store temporary information about the contact so you can use it in the flow.
For example, if you have different lines of business using Apple Messages for Business, you can branch to different flows based on the **AppleBusinessChatGroup** contact attribute. Or, if you want to route Apple Messages for Business messages differently from other chat messages, you can branch based on MessagingPlatform.
For more information about contact attributes, see [Use Amazon Connect contact attributes](connect-contact-attributes.md).
Use the following contact attributes to route Apple Messages for Business customers.
| Attribute | Description | Type | JSON |
| --- | --- | --- | --- |
| MessagingPlatform | The messaging platform from where the customer request originated. Exact value: **AppleBusinessChat** | User-defined | \$1.Attributes.MessagingPlatform |
| AppleBusinessChatCustomerId | The customer’s opaque ID provided by Apple. This remains constant for the AppleID and a business. You can use this to identify if the message is from a new customer or a returning customer. | User-defined | \$1.Attributes.AppleBusinessChatCustomerId |
| AppleBusinessChatIntent | You can define the intent or purpose of the chat. This parameter is included in a URL that initiates a chat session in Messages when a customer chooses the **Business Chat** button. | User-defined | \$1.Attributes.AppleBusinessChatIntent |
| AppleBusinessChatGroup | You define the group which designates the department or individuals best qualified to handle the customer’s particular question or problem. This parameter is included in a URL that initiates a chat session in Messages when a customer chooses the **Business Chat** button. | User-defined | \$1.Attributes.AppleBusinessChatGroup |
| AppleBusinessChatLocale | Defines the language and AWS Region preferences that the user wants to see in their user interface. It consists of a language identifier (ISO 639-1) and a Region identifier (ISO 3166). For example, **en\$1US**. | User-defined | \$1.Attributes.AppleBusinessChatLocale |
| AppleFormCapability | Whether the customer device supports forms. If true, the customer device is supported. If false, the device is not supported. | User-defined | \$1.Attributes.AppleFormCapability |
| AppleAuthenticationCapability | Whether the customer device supports Authentication (OAuth2). If true, the customer device is supported. If false, their device is not supported. | User-defined | \$1.Attributes.AppleAuthenticationCapability |
| AppleTimePickerCapability | Whether the customer device supports time pickers. If true, the customer device is supported. If false, the device is not supported. | User-defined | \$1.Attributes.AppleTimePickerCapability |
| AppleListPickerCapability | Whether the customer device supports list pickers. If true, the customer device is supported. If false, the device is not supported. | User-defined | \$1.Attributes.AppleListPickerCapability |
| AppleQuickReplyCapability | Whether the customer device supports quick replies. If true, the customer device is supported. If false, the device is not supported. | User-defined | \$1.Attributes.AppleQuickReplyCapability |
# Update an Apple Messages for Business integration with Amazon Connect
Update an Apple Messages for Business integration
You will need to update your Apple Messages for Business integration if you want to change the flow ID or other information.
1. Open an [Support ticket](https://console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=customer-account&categoryCode=activation).
If prompted, login using your AWS account.
1. In the **Use case description** box, copy and paste the following template to indicate this is an **update **request:
```
Subject: Update Apple Messages for Business Integration request
Body:
Apple Messages for Business Account ID (required): enter your current account ID change to new account ID
Apple Token (required): enter your token
Amazon Connect Instance ARN (required): enter your current instance ARN change to new instance ARN
Amazon Connect Flow ID (required): enter your current flow ID change to new flow ID
```
**Note**
If you update your Amazon Connect Instance ARN, you must also update your contact flow ID.
1. Expand **Contact options**, and then choose your **Preferred contact language**, and then choose **Web** as the contact method, if it's not selected by default.
![\[The contact options page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-contact-support-options.png)
1. Choose **Submit**.
1. Support will work directly with the Amazon Connect team on your request and follow up with any additional questions.
# Delete an Apple Messages for Business integration with Amazon Connect
Delete an Apple Messages for Business integration
1. Open an [Support ticket](https://console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=customer-account&categoryCode=activation).
If prompted, log in by using your AWS account.
1. In the **Use case description** box, copy and paste the following template to indicate this is an **delete** request:
```
Subject: Delete Apple Messages for Business Integration
Body:
Apple Messages for Business Account ID (required): enter your account ID
Amazon Connect Instance ARN (required): enter your instance ARN
Amazon Connect Flow ID (required): enter your flow ID
```
The following image shows an example of a completed ticket:
1. Expand **Contact options**, and then choose your **Preferred contact language**, and then choose **Web** as the contact method, if it's not selected by default.
![\[The contact options page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-contact-support-options.png)
1. Choose **Submit**.
1. Support will work directly with the Amazon Connect team on your request and follow up with any additional questions.
# Find your Apple Messages for Business Account ID for your integration with Amazon Connect
Find your Apple Messages for Business Account ID
1. In [Apple Business Register](https://register.apple.com/), navigate to **Message Service Provider** and click or tap **Test your Messaging Service Provider connection**.
![\[The messaging service provider page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-messaging-service-provider.png)
1. Click or tap **Copy ID**.
![\[The messaging service provider connection page, the copy ID link.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-account-id.png)
# Find your Apple token when integrating Apple Messages for Business with Amazon Connect
Find your Apple token
+ In [Apple Business Register](https://register.apple.com/) navigate to **Messaging Service Provider** and choose **Copy Token**.
![\[The messaging service provider page., the copy token link.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-msp-copytoken.png)
# Find the flow ID when integrating Apple Messages for Business with Amazon Connect
Find the flow ID
The flow ID is the flow you want to use for inbound Apple Messages for Business messages. Flows define the experiences for your customer when they begin a new chat.
You can either reuse an existing flow that you’re already using for voice or chat contacts, or create a new one specifically for Apple Messages for Business contacts. For instructions about creating a new inbound flow, see [Create an inbound flow](create-contact-flow.md#create-inbound-contact-flow).
For more information about flows, see [Flows in Amazon Connect](connect-contact-flows.md).
**To find your flow ID for Apple Messages for Business**
1. Log in to the Amazon Connect console with an **Admin** account, or an account assigned to a security profile that has permissions to view contact flows.
1. On the navigation menu, choose **Routing**, **Contact flows**.
1. Select the flow you want to use.
**Note**
Only choose flows that are type **Flow (inbound)**. Apple Messages for Business doesn't work with other flow types, such as **Customer queue**, **Customer hold**, **Customer whisper**, etc.
1. In the flow designer, expand **Show additional flow information**.
![\[A sample flow, the show additional flow information section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-find-contactflow-id.png)
1. Under the ARN (Amazon Resource Number), copy everything after contact-flow/. For example, in the following image, you would copy the underlined part.
![\[A diagram showing how to copy the key portion of the Amazon Resource Number.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/abc-find-contactflow-id-copy.png)
1. Notice the **Type** = **Flow (Inbound)**.
1. The flow ID is at the end of the ARN. Only copy this end part.
# Manage Apple Messages for Business chats in your Amazon Connect instance
Manage customer chats
When you integrate Apple Messages for Business with your Amazon Connect instance, messages from Apple Messages for Business behave exactly like any other chat messages arriving to your contact center.
**Note**
The Amazon Connect Chat service quota limits apply to Apple Messages for Business. To learn more, see [Amazon Connect service quotas](amazon-connect-service-limits.md).
## Set up automatic replies
Set up automatic replies
You can use Amazon Lex to set up automatic replies to chat. For a tutorial that introduces you to setting up Amazon Lex and Amazon Connect, see [Add an Amazon Lex bot to Amazon Connect](amazon-lex.md).
# Set up WhatsApp Business messaging
The topics in this section explain how to set up and test WhatsApp Business messaging for Amazon Connect. You use [AWS End User Messaging Social](https://docs.aws.amazon.com/social-messaging/latest/userguide/what-is-service.html) to link a WhatsApp Business Account and phone number to an Amazon Connect instance, then import the linked phone number into Amazon Connect. Customers can then use WhatsApp to send messages to your call center.
You can also use Amazon Lex to automate responses to customer questions, which saves agents time and effort. For more information, see [Getting started with Amazon Lex](https://docs.aws.amazon.com/lexv2/latest/dg/getting-started.html) in the *Amazon Lex Developer Guide*.
**Topics**
+ [
## Prerequisites
](#whatsapp-prerequisites)
+ [
## Step 1: Enable Amazon Connect as the event destination
](#enable-connect-destination)
+ [
## Step 2: Configure an inbound contact flow on your phone number
](#inbound-contact-flow)
+ [
## Step 3: Send and receive test messages
](#send-receive-test-messages)
+ [
## Next steps: Prepare to go live
](#whatsapp-next-steps)
+ [
## Troubleshoot common problems
](#whatsapp-troubleshooting)
+ [
# WhatsApp Business messaging capabilities and limitations with Amazon Connect
](whatsapp-messaging-capabilities.md)
## Prerequisites
Before you can integrate WhatsApp with Amazon Connect, you must have the following items:
+ A WhatsApp Business Account.
+ A WhatsApp phone number. The number must be able to receive a voice call or an SMS text message in order to complete Meta's phone number verification process for WhatsApp Business messaging. You can use an Amazon Connect voice number or an AWS End User Messaging SMS number for the WhatsApp phone number. You can also use a phone number that you own outside of AWS.
When using an Amazon Connect voice number or AWS End User Messaging SMS number, we recommend claiming a new number that isn’t used with live voice or SMS traffic to avoid potential disruption of service.
You can use the AWS End User Messaging Social console at [https://console.aws.amazon.com/social-messaging/](https://console.aws.amazon.com/social-messaging/) to create the WhatsApp Business Account and phone number. For more information, see [Signing up for WhatsApp](https://docs.aws.amazon.com/social-messaging/latest/userguide/getting-started.html#getting-started-embedded) in the *AWS End User Messaging Social User Guide*.
**Important**
WhatsApp has an automated business verification process that can take up to 2 weeks to complete. We recommend you begin this process early. WhatsApp can disable WhatsApp Business Accounts if the WhatsApp Business policy is violated or the business identity can't be verified.
Also, we strongly recommend reviewing [Best practices for AWS End User Messaging Social](https://docs.aws.amazon.com/social-messaging/latest/userguide/best-practices.html) and [WhatsApp Best Practices](https://business.whatsapp.com/policy#best_practices) before creating and linking WhatsApp resources.
After you create the account and phone number, complete the steps in the following sections in the order listed.
## Step 1: Enable Amazon Connect as the event destination
The following steps explain how to use AWS End User Messaging Social to enable Amazon Connect as the event destination for your linked WhatsApp Business Account. This enables the system to import your WhatsApp phone number.
You can use the [AWS End User Messaging Social console](https://console.aws.amazon.com/social-messaging/) or the AWS CLI to complete this task. To use the AWS CLI, see [https://docs.aws.amazon.com/connect/latest/APIReference/API_ImportPhoneNumber.html](https://docs.aws.amazon.com/connect/latest/APIReference/API_ImportPhoneNumber.html) in the *Amazon Connect API Reference*, and [https://docs.aws.amazon.com/social-messaging/latest/APIReference/API_PutWhatsAppBusinessAccountEventDestinations.html](https://docs.aws.amazon.com/social-messaging/latest/APIReference/API_PutWhatsAppBusinessAccountEventDestinations.html) in the *AWS End User Messaging Social API Reference*.
The following steps explain how to use the console.
**To use the console**
1. Sign in to the AWS End User Messaging Social console at [https://console.aws.amazon.com/social-messaging/](https://console.aws.amazon.com/social-messaging/).
1. In the navigation pane, choose **WhatsApp Business accounts**, then choose the desired account.
1. On the **Event destination** tab, choose **Edit destination**.
1. For **Destination type**, choose **Amazon Connect**.
1. For **Connect instance**, choose your Amazon Connect instance from the dropdown list.
1. For **Role ARN**, choose an IAM role that grants permission to deliver messages and events, and to import phone numbers. For example IAM policies, see [Add a message and event destination to AWS End User Messaging Social](https://docs.aws.amazon.com/social-messaging/latest/userguide/managing-event-destinations-add.html#managing-event-destinations-amazon-connect-policies) in the *AWS End User Messaging Social User Guide*.
1. Choose **Save changes**.
This starts the process of importing your phone number to Amazon Connect.
After the operation finishes, the number appears in the Amazon Connect admin website.
**To view the number**
+ In the navigation pane, choose **Channels**, then **Phone numbers**.
The **Active Channels** column displays **WhatsApp** for all WhatsApp numbers.
![\[The Phone numbers page showing a WhatsApp number.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/whats-app-imported-number.png)
## Step 2: Configure an inbound contact flow on your phone number
You can create an inbound contact flow for use with your WhatsApp phone number, or you can reuse an existing flow. If you reuse a flow, you can add a `CheckContactAttribute` block and enable branching for the flow. The block enables you to send WhatsApp contacts to a specific queue, or take another action.
For more information about building your contact flow, including interactive messages and rich link previews, see [WhatsApp Business messaging capabilities and limitations with Amazon Connect](whatsapp-messaging-capabilities.md) later in this section.
The following sets of steps explain how to configure an inbound contact flow and add a `CheckContactAttribute` block to the flow.
**To configure a flow**
1. Start the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/)
1. In the navigation pane, choose **Channels**, then **Phone numbers**.
1. Choose the WhatsApp number, then choose **Edit**.
1. Under **Flow/IVR**, choose the flow you updated.
![\[The Contact flow / IVR section of the Edit page showing a WhatsApp flow.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/whatsapp-flow-ivr.png)
1. Choose **Save**.
**To add the CheckContactAttribute block**
1. Follow steps 1–4 [in the previous section](#enable-connect-destination).
1. Open the **Properties** page for the flow.
1. In the **Attribute to check** section, set **Namespace** to **Segment attributes**, and **key** to **Subtype**. For more information about segment attributes, see [SegmentAttributes](ctr-data-model.md#segmentattributes), later in this guide.
1. In the **Conditions to check** section, set **condition** to **Equals** and **value** to **connect:WhatsApp**.
1. Choose **Save**.
## Step 3: Send and receive test messages
In this step, you use the Contact Control Panel (CCP) and a mobile phone to send and receive WhatsApp test messages.
**To test the integration**
1. In your CCP, set your status to **Available**.
1. Using WhatsApp on your mobile phone, start a conversation by entering the phone number you added previously.
The following image shows a message with **Options**, and the resulting list of options.
![\[Mobile phone screen showing an example message.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/whatsapp-options-results.png)
## Next steps: Prepare to go live
After you test your integration, we recommend adding the following features and capabilities to your WhatsApp messaging channel.
### Add Amazon Connect features
The links in the following list take you to information about Amazon Connect features that you can add to your customer and agent experiences.
+ Learn more about the [WhatsApp Business messaging capabilities and limitations with Amazon Connect](whatsapp-messaging-capabilities.md).
+ [Enable customers to resume chat conversations in Amazon Connect](chat-persistence.md) – Customers can resume previous conversations with the context, metadata, and transcripts carried forward. They don't need to repeat themselves when they return to a chat, and agents have access to the entire conversation history.
+ [Create quick responses for use with chat and email contacts in Amazon Connect](create-quick-responses.md) – Provide agents with pre-written responses to common customer inquiries that they can use while they chat with customers. Quick responses make it faster for agents to respond to customers.
### Add entry points
The links in the following list take you to information about adding different types of customer entry points.
+ Entry points: [5 ways to direct leads and customers to business messaging conversations](https://business.whatsapp.com/blog/messaging-app-entry-points) (WhatsApp blog post)
+ QR codes: [Manage your WhatsApp Business Platform QR code](https://business.facebook.com/business/help/890732351439459) (Meta help article)
+ Click-to-WhatsApp ads: [Create Ads that Click to WhatsApp in Ads Manager](https://business.facebook.com/business/help/447934475640650?id=371525583593535) (Meta help article)
### Add a display name to your phone number
To add a verified display name that customers see, [About WhatsApp Business display name](https://business.facebook.com/business/help/338047025165344) in the Meta help.
### Scale traffic
After you onboard live traffic to your WhatsApp integration, we recommend monitoring the following quotas.
**Amazon Connect quotas**
For more information about default quotas, and about raising them, see [Amazon Connect service quotas](amazon-connect-service-limits.md).
+ [Concurrent active chats per instance](amazon-connect-service-limits.md#concurrent-active-chats) quota. For information about monitoring this quota, see [Monitoring your Amazon Connect instance using CloudWatch](monitoring-cloudwatch.md),
+ [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) throttling quota.
+ [SendChatIntegrationEvent](https://docs.aws.amazon.com/connect/latest/APIReference/API_SendChatIntegrationEvent.html) throttling quota.
+ `SendIntegrationEvent` throttling quota. A permission only API used by AWS End User Messaging Social to publish inbound WhatsApp events.
**End User Messaging Social quotas**
AWS End User Messaging Social enforces rate limits on a number of messaging APIs. Monitor the following APIs to see if you need to change one or more quotas. The links take you to the *AWS End User Messaging Social API Reference*.
+ [SendWhatsAppMessage](https://docs.aws.amazon.com/social-messaging/latest/APIReference/API_SendWhatsAppMessage.html)
+ [PostWhatsAppMessageMedia](https://docs.aws.amazon.com/social-messaging/latest/APIReference/API_PostWhatsAppMessageMedia.html)
+ [GetWhatsAppMessageMedia](https://docs.aws.amazon.com/social-messaging/latest/APIReference/API_GetWhatsAppMessageMedia.html)
For more information about increasing AWS End User Messaging Social quotas, see the following topics in the *AWS End User Messaging Social User Guide*:
+ [Quotas for AWS End User Messaging Social](https://docs.aws.amazon.com/social-messaging/latest/userguide/quotas.html)
+ [Increase messaging conversation limits in WhatsApp](https://docs.aws.amazon.com/social-messaging/latest/userguide/increase-message-limit.html)
+ [Increase message throughput in WhatsApp](https://docs.aws.amazon.com/social-messaging/latest/userguide/increase-message-throughput.html)
## Troubleshoot common problems
Use the following information to troubleshoot common problems with a WhatsApp integration.
**Topics**
+ [
### Unable to see imported phone numbers in your Amazon Connect instance
](#no-imported-number)
+ [
### Inbound messages from customers are not delivered
](#whatsapp-messages-not-delivered)
### Unable to see imported phone numbers in your Amazon Connect instance
If your imported number fails to appear in the Amazon Connect admin website, follow these steps:
+ Ensure that the event destination IAM role has the necessary permissions. For more information, see [Step 1: Enable Amazon Connect as the event destination](#enable-connect-destination).
+ See if your *Phone numbers per instance* quota needs to be raised. For more information, see [Amazon Connect service quotas](amazon-connect-service-limits.md).
+ To reassign a linked WhatsApp Business Account to a different Amazon Connect instance, you must first release the imported phone numbers from the original Amazon Connect instance. After the phone numbers are released, you can update the event destination on your linked WhatsApp Business Account to another Amazon Connect instance.
**Important**
Do not release numbers that handle live customer traffic. Instead, [claim new phone numbers](https://docs.aws.amazon.com/connect/latest/adminguide/claim-and-manage-phonenumbers.html).
+ To help determine the cause of the import issue, search your CloudTrail logs for `ImportPhoneNumber` events and check for error details. If the `ImportPhoneNumber` call succeeds, you can call `DescribePhoneNumber` for other error details.
If you made a fix, you must import the phone numbers again. To do this, repeat [Step 1: Enable Amazon Connect as the event destination](#enable-connect-destination).
### Inbound messages from customers are not delivered
If WhatsApp inbound message delivery stops, search your AWS CloudTrail logs for `SendIntegrationEvent` and `SendChatIntegrationEvent` for error details.
You can also check these common scenarios:
+ Ensure that your linked WhatsApp Business Account in AWS End User Messaging Social has an Amazon Connect event destination enabled.
+ Ensure your event destination IAM role has the necessary permissions. For more information, see [Step 1: Enable Amazon Connect as the event destination](#enable-connect-destination) earlier in this section. You have a misconfigured role if CloudTrail throws `AccessDeniedException` errors from the `SendIntegrationEvent` API.
+ Ensure that your WhatsApp phone number imported successfully to your Amazon Connect instance, and that the number has an associated inbound contact flow. For more information, see [Step 2: Configure an inbound contact flow on your phone number](#inbound-contact-flow).
+ Inbound messages were dropped because they are not yet supported. For more information, see [WhatsApp Business messaging capabilities and limitations with Amazon Connect](whatsapp-messaging-capabilities.md).
# WhatsApp Business messaging capabilities and limitations with Amazon Connect
The WhatsApp Business messaging integration provides the following capabilities:
+ Text messages
+ Interactive messages. For more information, see [Add Amazon Lex interactive messages for customers in chat](interactive-messages.md).
+ Messages with rich link previews
+ Delivered and read receipts for business messages
+ Attachments
## Limitations
When integrating WhatsApp Business messaging with Amazon Connect, be aware of the following limitations:
**Delivery receipt limitations**
+ Read receipts for customer messages are not supported.
+ Delivery receipts for customer messages are not supported. The delivery receipts that appear in WhatsApp indicate that WhatsApp has received the message, not Amazon Connect.
**Text message limitations**
+ Inbound text messages from customers greater than 1024 characters are not supported.
**Unsupported message types**
+ Inbound contact messages sent by customers are not supported.
+ Inbound location messages sent by customers are not supported.
+ Reaction messages sent by customers are not supported.
+ Reply messages sent by customers are not supported. New message content is delivered without the reply context.
+ Receiving message statuses that a message was deleted by the customer is not supported.
**Attachment limitations**
+ All attachments from customers when initiating a new contact or conversation are not supported. Customers can only send attachments during an existing contact.
+ Attachments from customers greater than 20MB are not supported.
+ Attachments with captions are not supported. Amazon Connect removes any captions and delivers the attachment.
+ Sticker attachments are not supported.
# Set up in-app, web, video calling, and screen sharing capabilities
Set up in-app, web, video calling, and screen sharing capabilities
The Amazon Connect in-app, web, and video calling capabilities enable your customers to contact you without ever leaving your web or mobile application. You can use these capabilities to pass contextual information to Amazon Connect. This enables you to personalize the customer experience based on attributes such as the customer's profile or other information, like actions previously taken within the app.
## Important things to know
Important things to know
+ During a video call or screen sharing session, agents are able to see the customer's video or screen share even when the customer is on hold. It is the customer's responsibility to handle PII accordingly. If you want to change this behavior, you can build a custom CCP and communication widget. For more information, see [Integrate in-app, web, video calling, and screen sharing natively into your application](config-com-widget2.md).
## Communication widget: Configure chat, voice, and video all in one place
Communication widget
To set up in-app, web, and video calling, you use the **Communication widgets** page. It supports chat, voice, video, and screen sharing. The following image shows the **Communication options** section of the page when it's configured for all of these options.
![\[The Communication options section of the Create a communication widget page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/comm-widget-all.png)
## Multi-user in-app, web, and video calling
Multi-user in-app, web, and video calling
You can add up to four additional users to an ongoing or scheduled web, in-app or video call, for a total of six participants: the agent, the first user, and four other participants (users or agents).
For example, to help close a mortgage transaction, you can have the agent and the customer, the customer's spouse, a translator, and even a supervisor (that is, another agent) on the call to help resolve any issues quickly.
To learn how to enable multi-user web, in-app and video calling, see [Enable multi-user in-app, web, and video calling](enable-multiuser-inapp.md).
## How to set up in-app, web, video calling, and screen sharing
How to set up in-app, web, video calling, and screen sharing
There are two ways to embed Amazon Connect in-app, web, and video calling, and screen sharing onto your website or mobile application:
+ Option 1: [Configure an out-of-the-box communications widget](config-com-widget1.md). You can use the UI builder to customize the font and colors, and secure the widget so that it can be launched only from your website.
+ Option 2: [Integrate in-app, web, and video calling natively into your mobile application ](config-com-widget2.md). Choose this option to build a communications widget from scratch and integrate it with your mobile application or website. Use the Amazon Connect APIs and Amazon Chime SDK client APIs to integrate natively into your mobile application or website.
**Note**
If you have custom agent desktops, you don't need to make any changes for Amazon Connect in-app and web calling. However, you need to [integrate video calling and screen sharing](integrate-video-calling-for-agents.md).
# Configure an out-of-the-box communication widget in Amazon Connect
Configure an out-of-the-box communication widget
Use this option to create communication widgets for desktop and mobile [browsers](connect-supported-browsers.md#browsers-inapp). At the end of this procedure, Amazon Connect generates a custom HTML code snippet that you copy into your website's source code.
1. Log in to Amazon Connect admin website using an Admin account or a user account that has **Channels and flows**, **Communication widget - Create** permission in its security profile.
1. In Amazon Connect, on the left navigation menu, choose **Channels**, **Communication widgets**.
1. The wizard guides you through the next three steps.
## Step 1: Select communication channels
Step 1: Select communication channels
1. On the **Communication widgets** page, enter a **Name** and **Description** for the communications widget.
**Note**
The Name must be unique for each communications widget created in an Amazon Connect instance.
1. In the **Communications options** section, choose how your customers can engage with your widget. The following image shows options to allow web calling, video, and screen sharing for customers.
![\[The communication widget page configured for web calling, video, and screen sharing.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/comm-widget-page-call.png)
1. In the **Web calling** section, choose whether to enable video and screen sharing experiences for your customers. The previous image shows options that customers can see agent video, turn on their video, and allow agents and customers to share their screens. For information about setting restrictions on screen sharing, see [Enable URL restriction for screen sharing](screen-sharing-url-restriction.md).
1. Choose **Save and continue**.
## Step 2: Customize widget
Step 2: Customize widget
As you choose these options, the widget preview updates automatically so that you can see what the experience will look like for your customers.
![\[The preview of the communications widget.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/netra-call-preview.png)
**Define widget access button styles**
1. Choose the colors for the button background by entering hex values ([HTML color codes](https://htmlcolorcodes.com/)).
1. Choose **White** or **Black** for the icon color. The icon color can't be customized.
**Customize display names and styles**
1. Provide values for header message and color, and widget background color.
1. **Logo URL**: Insert a URL to your logo banner from an Amazon S3 bucket or another online source.
**Note**
The communications widget preview in the customization page will not display the logo if it's from an online source other than an Amazon S3 bucket. However, the logo will be displayed when the customized communications widget is implemented to your page.
The banner must be in .svg, .jpg or .png format. The image can be 280px (width) by 60px (height). Any image larger than those dimensions will be scaled to fit the 280x60 logo component space.
1. For instructions about how to upload a file such as your logo banner to S3, see [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) in the *Amazon Simple Storage Service User Guide*.
1. Make sure that the image permissions are properly set so that the communications widget has permissions to access the image. For information about how to make a S3 object publicly accessible, see [Step 2: Add a bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteAccessPermissionsReqd.html#bucket-policy-static-site) in the *Setting permissions for website access* topic.
## Step 3: Add your domain for the widget
Step 3: Add your domain
This step enables you to secure the communications widget so that it can be launched only from your website.
1. Enter the website domains where you want to place the communications widget. The communications widget loads only on websites that you select in this step.
Choose **Add domain** to add up to 50 domains.
![\[The add domain option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-add-domain.png)
**Important**
Double-check that your website URLs are valid and does not contain errors. Include the full URL starting with https://.
We recommend using https:// for your production websites and applications.
1. Under **Add security for your communications widget requests**, for the fastest setup experience choose **No - I will skip**.
We recommend choosing **Yes** for the ability to verify the user is authenticated. For more information, see [Personalize the customer experience for in-app, web, and video calling in Amazon Connect](optional-widget-steps.md).
1. Choose **Save and continue**.
Success\$1 Your widget has been created. Copy the generated code and paste it on each page of your website where you want the communications widget to appear.
## Enable your agents for in-app, web, and video-calling, and screen sharing
Enable your agents for in-app, web, and video-calling, and screen sharing
To enable agents to use video calling and screen sharing, assign the ** Contact Control Panel (CCP)**, **Video calls - Access** permissions to their security profile.
The Amazon Connect agent workspace supports Amazon Connect in-app, web, and video calling, and screen sharing. You can use the same configuration, routing, analytics, and agent application as with telephone calls and chats. To get started, the only step is to enable your agent's security profiles with the permissions to have video calls and screen sharing.
For custom agent desktops, there are no changes required for the Amazon Connect in-app and web calling. Enable your agent's security profiles with the permissions to have video calls and screen sharing, and follow the guide below on how to integrate video calling into your agent desktop.
## How a client device initiates an in-app or web call
How a client device initiates an in-app or web call
The following diagram shows the sequence of events for a client device (mobile application or browser) to initiate an in-app or web call.
![\[A conceptual diagram that shows how a client devices initiates a call.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/netra-gs-diagram-option1.png)
1. (Optional) You can pass attributes captured in the website and validate them with JSON web token (JWT).
1. The customer clicks on the communications widget in your website or mobile app.
1. The communications widget starts the web call to Amazon Connect by passing attributes contained in the JWT.
1. The contact reaches the flow, is routed, and placed in queue.
1. The agent accepts the contact.
1. (Optional) If video is enabled for customer and the agent, they are able to start their video.
## More information
More information
For additional information about requirements for in-app, web, and video calling capabilities, see the following topics:
+ [Agent workstation requirements for app, web, and video calling in Amazon Connect](videocalling-networking-requirements.md)
+ [Supported browsers and mobile OS for in-app, web, and video calling capabilities](connect-supported-browsers.md#browsers-inapp)
# Integrate in-app, web, video calling, and screen sharing natively into your application
Integrate in-app, web, video calling, and screen sharing natively into your application
To integrate Amazon Connect in-app, web, video calling, and screen sharing with your application:
1. Use the Amazon Connect [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) API to create the contact.
1. Then use the details returned by the API call to join the call using the Amazon Chime client library for [iOS](https://github.com/aws/amazon-chime-sdk-ios), [Android](https://github.com/aws/amazon-chime-sdk-android), or [JavaScript](https://github.com/aws/amazon-chime-sdk-js).
For information about creating additional participants, see [Enable multi-user in-app, web, and video calling](enable-multiuser-inapp.md).
See the following Github repository for sample applications: [amazon-connect-in-app-calling-examples](https://github.com/amazon-connect/amazon-connect-in-app-calling-examples).
**Topics**
+ [
## How a client device initiates an in-app or web call
](#diagram-option2)
+ [
## Get started
](#diagram-option2-gs)
+ [
## Optional steps
](#optional-steps)
## How a client device initiates an in-app or web call
How a client device initiates an in-app or web call
The following diagram shows the sequence of events for a client device (mobile application or browser) to initiate an in-app or web call.
![\[A conceptual diagram that shows how a client devices initiates a call.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/netra-gs-diagram.png)
1. Your customer uses the client application (website or application) to start an in-app or web call.
1. The client application (website or mobile application) or web server uses the Amazon Connect [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) API to start the contact passing any attributes or context to Amazon Connect.
1. The client application joins the call using the details returned from the [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) in step 2.
1. (Optional) Client uses the [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) API to receive a `ConnectionToken` that is used to send DTMF through the [SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html) API.
1. The contact reaches the flow and is routed based on the flow and placed in queue.
1. The agent accepts the contact.
1. (Optional) If video is enabled for customer and the agent, they are able to start their video.
1. (Optional - not shown in diagram) Additional participants can be added using the [CreateParticipant](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipant.html) and [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) APIs.
## Get started
Get started
Following are the high level steps to get started:
1. Use the [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) API to create the contact. The API returns the details needed for the Amazon Chime SDK client to join the call.
1. Instantiate the Amazon Chime SDK client `MeetingSessionConfiguration` object using the configurations returned by [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html).
1. Instantiate Amazon Chime SDK client `DefaultMeetingSession` with `MeetingSessionConfiguration`, which was created in step 2 to create a client meeting session.
+ iOS
```
let logger = ConsoleLogger(name: "logger")
let meetingSession = DefaultMeetingSession(
configuration: meetingSessionConfig,
logger: logger
)
```
+ Android
```
val logger = ConsoleLogger()
val meetingSession = DefaultMeetingSession(
configuration = meetingSessionConfig,
logger = logger,
context = applicationContext
)
```
+ JavaScript
```
const logger = new ConsoleLogger('MeetingLogs', LogLevel.INFO);
const deviceController = new DefaultDeviceController(logger);
const configuration = new MeetingSessionConfiguration(
meetingResponse,
attendeeResponse
);
const meetingSession = new DefaultMeetingSession(
configuration,
logger,
deviceController
);
```
1. Use the `meetingSession.audioVideo.start()` method to join the WebRTC contact with audio.
+ iOS/Android
```
meetingSession.audioVideo.start()
```
+ JavaScript
```
await meetingSession.audioVideo.start();
```
1. Use the `meetingSession.audioVideo.stop()` method to hangup the WebRTC contact.
+ iOS/Android
```
meetingSession.audioVideo.stop()
```
+ JavaScript
```
meetingSession.audioVideo.stop();
```
## Optional steps
Optional steps
For additional operations and comprehensive API documentation, refer to the platform-specific API overview guides:
+ **iOS**: [API Overview](https://aws.github.io/amazon-chime-sdk-ios/guides/api_overview.html)
+ **Android**: [API Overview](https://aws.github.io/amazon-chime-sdk-android/guides/api_overview.html)
+ **JavaScript**: [API Overview](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/03_API_Overview.md)
### Send DTMF tones
Send DTMF tones
To send DTMF to the call, two Amazon Connect Participant Service APIs are needed: [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) and [SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html) respectively.
**Note**
`contentType` for the SendMessage API must be `audio/dtmf`.
1. Invoke [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) to retrieve `ConnectionToken`. (`ParticipantToken` is needed for calling this API. You can find it in the [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) response.)
1. With the `ConnectionToken`, call [SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html) for sending DTMF digits.
### Select audio devices
Select audio devices
To select the audio input/output device, you can use the methods from the Amazon Chime SDK client for Android and iOS or the [native iOS capabilities](https://developer.apple.com/documentation/avkit/avroutepickerview) for iOS.
**iOS/Android**
```
meetingSession.audioVideo.listAudioDevices()
meetingSession.audioVideo.chooseAudioDevice(mediaDevice)
```
**JavaScript**
```
await meetingSession.audioVideo.listAudioInputDevices();
await meetingSession.audioVideo.listAudioOutputDevices();
await meetingSession.audioVideo.startAudioInput(device);
await meetingSession.audioVideo.chooseAudioOutput(deviceId);
```
### Mute and unmute audio
Mute and unmute audio
For mute and unmute, use `meetingSession.audioVideo.realtimeLocalMute()` and `meetingSession.audioVideo.realtimeLocalUnmute()`.
**iOS/Android**
```
meetingSession.audioVideo.realtimeLocalMute()
meetingSession.audioVideo.realtimeLocalUnmute()
```
**JavaScript**
```
meetingSession.audioVideo.realtimeMuteLocalAudio();
meetingSession.audioVideo.realtimeUnmuteLocalAudio();
```
### Start self video
Start self video
To start self video, use the `meetingSession.audioVideo.startLocalVideo()`. See the client library API guides for more information on how to enumerate and choose specific devices.
**iOS/Android**
```
meetingSession.audioVideo.startLocalVideo()
```
**JavaScript**
```
meetingSession.audioVideo.startLocalVideoTile();
```
### Stop self video
Stop self video
To stop self video, use the `meetingSession.audioVideo.stopLocalVideo()`.
**iOS/Android**
```
meetingSession.audioVideo.stopLocalVideo()
```
**JavaScript**
```
meetingSession.audioVideo.stopLocalVideoTile();
```
### Enable agent video
Enable agent video
To allow receiving and loading video of the agent inside application, use the `meetingSession.audioVideo.startRemoteVideo()`. You will also need to implement video tile observers and bind video tiles to display views.
**iOS/Android**
```
meetingSession.audioVideo.startRemoteVideo()
// Implement VideoTileObserver to handle video tiles
meetingSession.audioVideo.addVideoTileObserver(observer)
// In videoTileDidAdd callback:
meetingSession.audioVideo.bindVideoView(videoView, tileId: tileState.tileId)
```
**JavaScript**
```
// Remote video is received automatically when available
// Implement AudioVideoObserver to handle video tiles
meetingSession.audioVideo.addObserver(observer);
// In videoTileDidUpdate callback:
meetingSession.audioVideo.bindVideoElement(tileId, videoElement);
```
Reference the platform-specific SDK guides for complete video tile implementation details.
### Disable agent video
Disable agent video
To disallow receiving and loading video of the agent inside application, use the `meetingSession.audioVideo.stopRemoteVideo()`.
**iOS/Android**
```
meetingSession.audioVideo.stopRemoteVideo()
meetingSession.audioVideo.unbindVideoView(tileId)
```
**JavaScript**
```
meetingSession.audioVideo.unbindVideoElement(tileId);
```
### Use data messages
Use data messages
You can use [data messages](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/03_API_Overview.md#9-send-and-receive-data-messages-optional) if you need to send any status from the agent side to the end user. For example, when customers are on hold, you can send a data message to the customer's application to display a message letting them know they are on hold and their video/screen sharing is still being sent, or you can turn off the video/screen share.
**iOS/Android**
```
meetingSession.audioVideo.realtimeSendDataMessage(topic, data, lifetimeMs)
meetingSession.audioVideo.addRealtimeDataMessageObserver(topic, observer)
```
**JavaScript**
```
meetingSession.audioVideo.realtimeSendDataMessage(topic, data, lifetimeMs);
meetingSession.audioVideo.realtimeSubscribeToReceiveDataMessage(topic, callback);
```
### Listen for stop events
Listen for stop events
You can listen for events when a Contact's participation ends through the `audioVideoDidStop` observer. Specific status codes may vary by platform.
#### Call reaches capacity
Call reaches capacity
When more than 6 people attempt to join the call, additional participants will receive the following error and cannot join until others leave.
+ **iOS:** `MeetingSessionStatusCode.audioCallAtCapacity` or `MeetingSessionStatusCode.audioAuthenticationRejected`
+ **Android:** `MeetingSessionStatusCode.AudioCallAtCapacity` or `MeetingSessionStatusCode.AudioAuthenticationRejected`
+ **JavaScript:** `MeetingSessionStatusCode.AudioCallAtCapacity` or `MeetingSessionStatusCode.AudioAuthenticationRejected`
#### Participant removed from call
Participant removed from call
When a participant is removed from the call by the agent but the contact continues for other participants they will receive the following status code. Note that if the participant removal leads to the contact ending, they will receive either of this status or the contact end status.
+ **iOS:** `MeetingSessionStatusCode.audioServerHungup` or `MeetingSessionStatusCode.audioAuthenticationRejected`
+ **Android:** `MeetingSessionStatusCode.AudioServerHungup` or `MeetingSessionStatusCode.AudioAuthenticationRejected`
+ **JavaScript:** `MeetingSessionStatusCode.AudioAttendeeRemoved` or `MeetingSessionStatusCode.AudioAuthenticationRejected`
#### Contact ends
Contact ends
When the actual contact ends completely for all participants they will receive the following status code.
+ **iOS:** `MeetingSessionStatusCode.audioCallEnded`
+ **Android:** `MeetingSessionStatusCode.AudioCallEnded`
+ **JavaScript:** `MeetingSessionStatusCode.AudioCallEnded`
# Enable multi-user in-app, web, and video calling
Enable multi-user in-app, web, and video calling
Amazon Connect supports adding additional users to join the in-app, web, and video call in an existing call. You can add up to four additional users to an ongoing or scheduled in-app, web or video call, for a total of six participants: the agent, the first user, and four other participants (users or agents).
## How to add participants to a multi-user call
How to add participants
1. To enable multi user calling, you need to enable [enhanced multi-party contact monitoring](monitor-conversations.md) from the Amazon Connect console.
1. After this is complete, you can leverage the existing Amazon Connect [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) API to create a contact, and route this contact to an agent.
1. To add an additional participant, first create a participant passing in `ContactId` from the [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) API response to the [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) API. [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) will not succeed until the original caller has connected to the agent. The video and screenshare capabilities for the participant can be set in the `ParticipantDetails.ParticipantCapabilities` field.
1. When [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) completes successfully, it returns a [participant token](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html#connect-CreateParticipant-response-ParticipantCredentials). This token can be used in a request to [CreateParticipantConnection](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-participant_CreateParticipantConnection.html) with `Type` set to `WEBRTC_CONNECTION`. The response includes [ConnectionData](https://docs.aws.amazon.com/connect/latest/APIReference/API_ConnectionData.html#connect-Type-ConnectionData-Meeting) which can be used to join the meeting using the [Amazon Chime SDK Client Libraries](https://docs.aws.amazon.com/chime-sdk/latest/dg/mtgs-sdk-client-lib.html) for the additional participant created. Follow the [integration instructions](config-com-widget2.md) to allow your application end-user to join the meeting.
**Note**
[CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) returns a Bad Request error if the agent is not yet connected to the contact. For business applications where users may attempt to join before the agent is connected, see [Handling concurrent user joins](#handling-concurrent-joins).
1. The additional customers can connect at any time after [CreateParticipantConnection](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-participant_CreateParticipantConnection.html) returns. After participants join, [all additional voice and recording behavior is similar to the multi party capability](multi-party-calls.md). The new participants can enable their video and screen-share, if their capabilities have been enabled in the [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) request.
**Note**
A total of only 6 participants (customers and agents) can join an active call at any time. The Amazon Chime SDK Client Libraries returns a status code indicating the call is at capacity when an action is taken to add extra participants beyond the limit occurs during meeting join.
1. After the participants are connected to the call, and then are disconnected gracefully, or non-gracefully for a preconfigured time, their participant credentials are no longer be valid. If the client library `onAudioVideoDidStop` observer receives a status code indicating the attendee no longer is valid, applications can trigger a new call to [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) and [CreateParticipantConnection](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-participant_CreateParticipantConnection.html) from your business backend to rejoin the call.
1. For every additional user connection, Amazon Connect creates a new contact and [contact record](ctr-data-model.md). All additional contacts have PreviousContactId set to the InitialContactId (that is, the one that was created by the [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) API) in order to trace it to original contact. Each contact record:
+ Has an **"InitiationMethod": "WEBRTC\$1API"**
+ Has the following segment attributes:
```
"SegmentAttributes": {
"connect:Subtype": {
"ValueString": "connect:WebRTC"
}
},
```
Additionally, each contact record has the display name provided in `CreateParticipant`. Agent information is not populated for any additional user contact. This is to avoid the duplication of agent information.
The following diagram illustrates how previous and next contact IDs are mapped in a scenario where multiple participants and agents are added in a web, in-app or video call.
![\[Diagram showing how contact IDs are mapped for multi-party WebRTC calls\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/multiparty-webrtc-contact-mapping.png)
## Handling concurrent user joins
Handling concurrent joins
Businesses may want to create applications where users can join in any order, at any time. For example, your application may email a link with an external appointment ID to multiple users that should be used to join a call at a scheduled time. To achieve this behavior, business backends must ensure that:
+ The first user that joins triggers a StartWebRTCContact request.
+ All additional users use CreateParticipant and CreateParticipantConnection but **only after the first user has connected to an agent**.
This section describes a possible implementation, assuming that your business backend contains a store (like DynamoDB) that can hold metadata about scheduled appointments. Note that scheduled appointments is not a feature of Amazon Connect, but of the example implementation.
When the user navigates to the page, they should send a request to the backend. The backend checks:
+ Whether the user is able to start the appointment, and whether it is the correct time.
+ Whether the Amazon Connect contact already been created by calling [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html).
**If the contact has not already been created**, the customer should call [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) API with a custom [flow](connect-contact-flows.md), and an [Attribute](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html#connect-StartWebRTCContact-request-Attributes) indicating the agent queue of the corresponding agent who was expected to join the call. The flow should include a [Set working queue](set-working-queue.md) block that is configured to use the agent queue provided in attributes. The flow should then terminate with a [Transfer to queue](transfer-to-queue.md) block. Before the API is called, the backend should atomically update the store to move the call from 'None' to 'Creating' state, and handle any concurrent modification exceptions.
The credentials from [StartWebRTCContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartWebRTCContact.html) should be returned to the customer and they should immediately join the call. The contact should be marked as 'Created' in the business store, along with the Contact ID. **This business API needs to be synchronized between all possible attendees that join**. This can be done by using the atomic operations provided by a DB.
**If the contact is in creating state** the additional user should be returned this state, display relevant information, and retry after a short wait.
**If the contact is created**: They should retrieve the contact ID, and call the [DescribeContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeContact.html) API. The business backend should look for the **`Contact.AgentInfo.ConnectedToAgentTimestamp`** field. If it does not exist, the first user has not connected to the agent, and the additional user should display relevant information, and retry after a short wait.
If the field exists, the backend should call [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html), and then [CreateParticipantConnection](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-participant_CreateParticipantConnection.html), to get [ConnectionData](https://docs.aws.amazon.com/connect/latest/APIReference/API_ConnectionData.html#connect-Type-ConnectionData-Meeting), as described in previous sections.
The backend flow should look like the following.
![\[Backend flow diagram for handling concurrent user joins\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/multiparty-backend-flow.png)
You can refer to the [Amazon Connect in-app calling examples](https://github.com/amazon-connect/amazon-connect-in-app-calling-examples/tree/main/Web) on GitHub for implementation.
**The agent will not join using the same website**. The agent should set their status in the [Contact Control Panel](launch-ccp.md) to **Available**. When the first customer joins, the agent is called automatically.
## Billing
Billing
Billing for additional participants is equivalent to existing billing for the initial customer and any agents on the call. Audio, video, and screen-share all incur their own, participant specific charges.
## Hold behavior
Hold behavior
During a video call or screen sharing session, agents are able to see the participant's video or screen share even when the participant is on hold. It is the participant's responsibility to handle PII accordingly. If using the native CCP application, agent video is disabled if any non-agent participant is on hold. If you want to change this behavior, you can build a custom CCP and communication widget.
For more information, see [Integrate in-app, web, video calling, and screen sharing natively into your application](config-com-widget2.md).
## Limitation
Limitation
The following limitation exists when creating additional in-app, web, video calling, and screen sharing participants:
+ The additional participants cannot have video capabilities set to **Send**, if the original contact was created with customer video capabilities set to **None**.
# Personalize the customer experience for in-app, web, and video calling in Amazon Connect
Passing attributes
The steps in this topic are optional but recommended. They enable you to personalize the customer's experience based on their actions previously taken within your app. This option provides you more control when initiating new calls, including the ability to pass contextual information as attributes.
After doing these steps, you'll need to work with your website administrator to set up your web servers to issue JSON Web Tokens (JWTs) for new calls
1. If you've already created your communications widget, on the **Communication widgets** page, choose the widget to edit it.
1. In the **Domain & Security** section, choose **Edit**.
1. Under **Add security for your communications widget requests**, choose **Yes**.
![\[The Yes option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-choose-security.png)
1. Choose **Save and continue**. Amazon Connect creates the widget along with the following:
+ Amazon Connect provides a 44-character security key on the next page that you can use to create JWTs.
+ Amazon Connect adds a callback function within the communications widget embed script that checks for a JWT when a call is initiated.
You must implement the callback function in the embedded snippet, as shown in the following example.
```
amazon_connect('authenticate', function(callback) {
window.fetch('/token').then(res => {
res.json().then(data => {
callback(data.data);
});
});
});
```
In the next step you'll get a security key for all calls initiated on your websites. Ask your website administrator to set up your web servers to issue JWTs using this security key.
1. Choose **Save and continue**.
1. Copy the custom HTML code snippet and insert it into your website's source code.
## Alternate method: Pass contact attributes directly from snippet code
**Note**
Although these attributes are scoped with the `HostedWidget-` prefix, they are still mutable client-site. Use the JWT setup if you require PII or immutable data in your contact flow.
The following example shows how to pass contact attributes directly from snippet code without enabling widget security.
```
```
# Set up tasks in Amazon Connect
Set up tasks
1. [Update your agent's routing profile](routing-profiles.md) so they can manage and create tasks.
When you add tasks to their routing profile, you can specify that up to 10 tasks be assigned to them at a time.
An agent can pause the same number of tasks as the **Maximum tasks per agent** setting in their [routing profile](routing-profiles.md).
For example, an agent has a **Maximum tasks per agent** setting to handle 5 active tasks simultaneously. This means they can pause up to 5 tasks, which allows them to free up their active slots to take in new more critical tasks. However, it also means that agents can have twice the number of tasks in their workspace at any point in time. In our example, this agent can have 10 tasks in their workspace: 5 paused and 5 active.
The following image shows the **Tasks** option on the **Routing profile** page.
![\[The Tasks option, max tasks per agent set to 5, queue set to voice, chat, task.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-routing-profile-2.png)
1. [Create quick connects](quick-connects.md) so that agents can create/assign tasks to themselves, or other agents or shared queues.
1. Update your flows to route tasks.
1. Optionally, [create task templates](task-templates.md) to make it easy for agents to create tasks. All the fields they need to create a task are defined for them.
1. Optionally, [integrate with external applications](integrate-external-apps-tasks.md) and [set up rules to automatically create tasks](add-rules-task-creation.md) based on pre-defined conditions.
1. By default all agents can create tasks. If you want to block [permissions](task-template-permissions.md) for some agents, assign the **Contact Control Panel**, **Restrict task creation permission** in their security profile.
# The task channel in Amazon Connect
Task channel
Amazon Connect Tasks allows you to prioritize, assign, track, and even automate tasks across the disparate tools agents use to support customers. For example, using Tasks you can:
+ Follow-up on customer issues recorded in a customer relationship management (CRM) solution such as Salesforce.
+ Follow-up with a customer through a call.
+ Complete actions in a business-specific system, such as processing a customer claim in an insurance application.
Currently, Amazon Connect Tasks can be used in compliance with [GDPR](https://aws.amazon.com/compliance/gdpr-center) and is approved for SOC, PCI, HITRUST, ISO, and HIPAA.
## What is a task?
In a business a *task* is a unit of work that an agent must complete. This includes work that may have originated in external applications. In Amazon Connect this unit of work is a contact. It's routed, prioritized, assigned, and tracked just like a voice or chat contact. Everything that is applicable to a voice or chat contact is also applicable to a task contact.
Agents handle tasks in their Contact Control Panel (CCP), again just like any other contact. When assigned a task, agents see a notification with the description of the task, information associated with the tasks, and links to any applications that they might need to complete the task. The following image shows what an agent's CCP may look like when they manage tasks.
![\[A task in the Contact Control Panel.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-introduction.png)
## How to create tasks
Amazon Connect provides different ways for you to create tasks:
1. You can use pre-built connectors with CRM applications (for example, Salesforce and Zendesk) to automatically create tasks based on a set of pre-defined conditions, without any custom development.
For example, you can configure a rule in Amazon Connect to automatically create a task when a new case is created in Salesforce.
For more information, see [Set up application integration to create tasks in Amazon Connect](integrate-external-apps-tasks.md) and [Create rules that generate tasks for third-party integrations in Amazon Connect](add-rules-task-creation.md).
1. You can integrate with your homegrown or business-specific applications to create tasks using Amazon Connect APIs.
For more information, see the [StartTaskContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartTaskContact.html) API.
1. You can add a [Create task](create-task-block.md) block to your flows. This block enables you to create and orchestrate tasks directly from flows based on customer input (DTMF input), and contact and tasks information.
1. You can enable your agents to create tasks from the Contact Control Panel (CCP) without you doing any development work.
For example, agents can create tasks to ensure follow up work is not forgotten, such as calling a customer back to provide a status update on their issue.
For more information, see [Test voice, chat, and task experiences in Amazon Connect](chat-testing.md).
For more information on getting started with tasks, see [Set up tasks in Amazon Connect](concepts-getting-started-tasks.md).
**Important**
The [Default customer queue](default-customer-queue.md) flow does not support tasks. It will fail if you use it out-of-the-box without any changes. The **Default customer queue flow** flow contains a [Loop prompts](loop-prompts.md) block, and that block doesn't support tasks.
We recommend you create a new flow, and use it to check the channel and route tasks to the desired queue. For instructions, see [How to send tasks to a queue](#example-enqueue-task). Or, update the **Loop prompts** block in the default flow so the **Error** branch doesn't terminate; instead perform another action on the contact.
## Supported flow types
You can use tasks in the following flow types:
+ Inbound flow
+ Customer queue flow
+ Agent whisper flow
+ Transfer to queue flow
+ Transfer to agent flow
## Supported contact blocks
You can use tasks in the following flow blocks:
+ Change routing priority/age
+ Check contact attributes
+ Check hours of operation
+ Check queue status
+ Check staffing
+ Create task
+ Disconnect / hang up
+ Distribute by percentage
+ End flow / resume
+ Get queue metrics
+ Invoke AWS Lambda function
+ Loop
+ Set contact attributes
+ Set customer queue flow
+ Set disconnect flow
+ Set working queue
+ Transfer to flow
+ Transfer to queue
+ Wait
## Linked tasks
Linked tasks
When using tasks with the [StartTaskContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartTaskContact.html) API, a new contact can be associated with an existing contact through `PreviousContactID` or `RelatedContactId`. This new contact contains a copy of the [contact attributes](connect-attrib-list.md) from the linked contact.
The following code shows request syntax that includes `PreviousContactID` and `RelatedContactId`.
```
PUT /contact/task HTTP/1.1
Content-type: application/json
{
"Attributes": {
"string" : "string"
},
"ClientToken": "string",
"ContactFlowId": "string",
"Description": "string",
"InstanceId": "string",
"Name": "string",
"PreviousContactId": "string",
"QuickConnectId": "string",
"References": {
"string" : {
"Type": "string",
"Value": "string"
}
},
"RelatedContactId": "string",
"ScheduledTime": number,
"TaskTemplateId": "string"
}
```
When you use `PreviousContactID` or `RelatedContactID` to create tasks, note the following:
+ `PreviousContactID` - When contacts are linked using the `PreviousContactID`, updates that are made to contact attributes at any time in the chain will percolate through the entire chain.
+ `RelatedContactID` - When contacts are linked using the `RelatedContactID`, updates that are made to contact attributes will percolate only to the contactID that is referenced in the [UpdateContactAttributes](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateContactAttributes.html) API.
**Note**
You can specify only `PreviousContactID` or `RelatedContactID` in a request body, but not both. If you do specify both, Amazon Connect returns an `InvalidRequestException` error with a 400 status code.
For information about how `PreviousContactID` and `RelatedContactId` are modeled in contact records, see [ContactTraceRecord](ctr-data-model.md#ctr-ContactTraceRecord) in the contact records data model.
## Agents can link tasks to outbound contacts
Agents can link tasks to outbound contacts
While agents are **actively working on a task**, the **Number pad** appears on the Contact Control Panel (CCP). If they make an outbound call using the Number pad, the call is automatically linked to the task. Amazon Connect links the task and outbound call by using the `relatedContactID` parameter.
The following image of the CCP shows the **Number pad** is available while the agent works on a task.
![\[The number pad on the CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-linked-outboundcall.png)
## Link task to contact by using the Create task block
Link task to contact by using the Create task block
The Create task block enables you to automatically link the task to the current contact.
The following image of the Properties page of the **Create task** block shows the **Link to contact** option.
![\[The link to contact option on the Create task block properties page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-task-properties-manually.png)
## Track who created a task
Track who created a task
Agents who create tasks through CCP automatically have their agent resource ARN added onto the contact record as a [segment attribute](connect-attrib-list.md#attribs-segment-attributes) called `CreatedByUser`. This attribute enables you to track the originating agent for a task. However, you can't access `CreatedByUser` by using the Amazon Connect admin website; instead use the [DescribeContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeContact.html) API.
The `CreatedByUser` segment attribute is available to you on the [Create task](create-task-block.md) block. You can set the segment attribute of **Created By User**, which represents the ARN of the user who created the task. The following image shows a section of the **Create task** properties page where this attribute is available.
![\[The Create task properties page, the Create By User attribute.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-expiry.png)
You can also set this value manually for tasks that are created through the [StartTaskContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartTaskContact.html) API.
## Agents can assign tasks to themselves
Agents can self-assign tasks
When contact center supervisors create task templates, they can configure them to allow agents to self-assign tasks. Agents assign tasks to themselves by using the CCP.
Developers can specify the `assignmentType` on the [StartTaskContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartTaskContact.html) API with the value `SELF` and specify a valid `CreatedByUser` and a valid `TaskTemplateID`.
## Using IAM? Add Task permissions
If your organization is using custom [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) policies to manage access to the Amazon Connect console, make sure users have the appropriate permissions to set up applications for task creation. For a list of required permissions, see [Tasks page](security-iam-amazon-connect-permissions.md#tasks-page).
**Note**
If your instance was created before October 2018, for information about how to configure your service-linked roles (SLR), see [For instances created before October 2018](connect-slr.md#migrate-slr).
## Track tasks in real-time and historical metrics reports
You can track the status of all tasks in real-time and historical metrics reports, just like you track contacts in other channels. For example, you can track:
+ How long agents spent working on each task ([Agent contact time](metrics-definitions.md#agent-contact-time)).
+ The total time from when a task was created to when it was completed. ([Contact handle time](metrics-definitions.md#contact-handle-time)).
### Metrics
+ [Average active time](metrics-definitions.md#average-active-time)
+ [Average agent pause time](metrics-definitions.md#average-agent-pause-time)
### Contact metrics
The following data is captured in the contact data model.
### Metrics that don't apply to tasks and have a value of 0 on the report
+ [Average agent interaction time](metrics-definitions.md#average-agent-interaction-time)
+ [Average customer hold time](metrics-definitions.md#average-customer-hold-time)
+ [Agent interaction and hold time](metrics-definitions.md#agent-interaction-and-hold-time) - historical
+ [Agent interaction time](metrics-definitions.md#agent-interaction-time) - historical
+ [Average agent interaction time](metrics-definitions.md#average-agent-interaction-time)
+ [Average customer hold time](metrics-definitions.md#average-customer-hold-time)
### Manage tasks to custom service levels (SL)
While voice and chats may have short service level times based on seconds or minutes, you may have some tasks with service levels that are hours or days. You can create custom service level durations that are appropriate to each of your channels. For more information, see [custom service levels](metrics-definitions.md#custom-service-levels).
## When do tasks end?
The default total duration of a task can be up to 7 days. When you [create a task template](task-templates.md), you can extend the duration of the task up to 90 days.
A task ends when one of the following happens:
+ An agent completes the task.
+ A flow runs a [Disconnect / hang up](disconnect-hang-up.md) block, which ends the task.
+ A task reaches the default 7 day limit.
+ It reaches the **Expiry Duration In Minutes**, if this option is configured on the task template.
+ You end the task using the [StopContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StopContact.html) API.
You can also use the **Contact Expiry** setting on the [Create task](create-task-block.md) block.
## How to send tasks to a queue
How to send tasks to a queue
Since the [Default customer queue](default-customer-queue.md) flow is only for voice contacts, we recommend you create a new flow to send tasks (and other non-voice channels) to a queue.
Let's say you want an overall wait time of 10 minutes for a task, but want to check every minute to see if there are still agents who are working on the queue and could at some point pick up the task. For this use case you would do the following:
1. Add a [Loop](loop.md) block to your flow. Set **Number of loops** to 10.
1. For the **Looping** branch, a use [Check staffing](check-staffing.md) block to check agent availability for the queue.
1. If agents are available, transfer the contact to the queue by using a [Transfer to queue](transfer-to-queue.md) block.
1. Set the **Complete** branch to route the contact to a [Disconnect / hang up](disconnect-hang-up.md) block. This will be triggered if there are no agents during the 10 minute loop.
## Search and review completed tasks
Use the [Contact search](contact-search.md) page to search for and review completed tasks.
The following image is an example of what the **Contact Summary** and **References** look like in a contact record for a task.
![\[A contact record page for a task.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-sample-ctr.png)
The following data is appended to the contact record but not stored with it. The data is included in an export.
+ Flow ID
+ Potential attributes:
+ [ContactDetails](ctr-data-model.md#ctr-contact-details)
+ Name: the name of the task
+ Description: the description of the task
+ [References](ctr-data-model.md#ctr-contact-references): any links to forms or other sites
When task is scheduled for a future date and time, **Contact Summary** also displays **Scheduled time**.
## More information
+ [Amazon Connect feature specifications](feature-limits.md)
+ [Accept a task assigned in the Contact Control Panel (CCP)](accept-task.md)
+ [Create a new task in the Contact Control Panel (CCP)](create-task.md)
+ [Transfer a task to another agent or queue in the Amazon Connect Contact Control Panel (CCP)](transfer-task.md)
# Pause and resume tasks in Amazon Connect Tasks
Pause and resume tasks
You can pause and resume all tasks that aren't expired, disconnected, or scheduled for a later time. The benefit of pausing and resuming tasks is that it enables agents to free up an active slot so they can receive more critical tasks when their current task is stalled, for example, because of a missing approval or waiting on an external input.
You can also pause fully automated tasks to address force majeure events (natural disasters, infrastructure failures, invasions) that may require you to halt all business processes temporarily, and then resume them after the emergency has passed.
**Topics**
+ [How paused and resumed tasks are queued](#pause-tasks-queue)
+ [How agents pause and resume tasks](#pause-tasks-agent-experience)
+ [How many tasks an agent can pause](#pause-tasks-number)
+ [When can a paused task be resumed?](#when-resume-tasks)
+ [Programmatically pause and resume tasks](#programmatically-pause-and-resume-tasks)
+ [Configure a flow to pause and resume tasks](#pause-and-resume-flow)
+ [Contact event stream](#ces-pause-and-resume-tasks)
+ [Pause and resume task events in contact records](#ctr-pause-and-resume-tasks)
+ [Metrics](#metrics-pause-and-resume-tasks)
## How paused and resumed tasks are queued
How paused and resumed tasks are queued
+ All paused tasks that are in queue and not yet assigned to an agent are dequeued. This way they don't consume the queue limits for your instance and instead allow other more critical contacts to be assigned to agents.
+ After the task is resumed, it is re-queued and the flow continues running per your configuration.
+ When you design a flow to resume unassigned, paused tasks that are dequeued, be sure to add a [Transfer to queue](transfer-to-queue.md) block to the flow to queue the task after resuming. Otherwise, the task will stay in a de-queued state.
## How agents pause and resume tasks
How agents pause and resume tasks
Agents can pause a task from their Contact Control Panel (CCP) or agent workspace by using the **Pause** button. To update the task, the agent must choose **Resume**. The only actions the agent can take on a task that is in the Paused state are to end it or transfer it.
The following image shows the **Pause** button on the CCP.
![\[The Pause button on the CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-pause-button-ccp.png)
The following image shows the **Pause** button on the agent workspace.
![\[The Pause button on the agent workspace.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-pause-button-agentworkspace.png)
After an agent pauses or resumes a task, a banner is displayed that notifies them of the current status of the task. The following image of the CCP shows the Pause banner.
![\[Pause and Resume banners on the CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-paused-ccp.png)
The following image of the agent workspace shows the Resume banner.
![\[Pause and Resume banners on the agent workspace.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-resumed.png)
When an agent has multiple tasks open and they pause any one of them, the icon updates in the task list to notify them of the state of the task. The following image shows an example of a Paused icon.
![\[A task status icon.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-pause-agentworkspace.png)
## How many tasks an agent can pause
How many tasks an agent can pause
An agent can pause the up to twice the number tasks as the **Maximum tasks per agent** setting in their [routing profile](routing-profiles.md).
For example, an agent has a **Maximum tasks per agent** setting to handle 5 active tasks simultaneously. This means they can pause up to 5 tasks, which allows them to free up their active slots to take in new more critical tasks. However, it also means that agents can have twice the number of tasks in their workspace at any point in time. In our example, this agent can have 10 tasks in their workspace: 5 paused and 5 active.
## When can a paused task be resumed?
When can a paused task be resumed?
A paused task can be resumed at any time. As a result, it's possible for an agent to work temporarily on twice their concurrency limit of tasks.
For example, an agent has 10 tasks in their workspace: 5 paused and 5 active. They resume all of their paused tasks simultaneously. Now they have 10 active tasks. No new tasks are routed to them until the number of active tasks is lower than the **Maximum tasks per agent** limit in their routing profile.
## Programmatically pause and resume tasks
Programmatically pause and resume tasks
You can pause and resume tasks programmatically by using the [PauseContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_PauseContact.html) and [ResumeContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_ResumeContact.html) APIs.
When pausing and resuming a task, a corresponding flow can be configured to run at the pause and resume events. For example:
+ You may want to design a flow to automatically resume Paused tasks after a set period of time for agent lunch breaks.
+ You may want to create a resume flow to update attributes on the task that may have changed while the task was Paused.
## Configure a flow to pause and resume tasks
Configure a flow to pause and resume tasks
Configure a [Set event flow](set-event-flow.md) block to pause and resume tasks. The following image shows the **Properties** page of a **Set event flow** block configured to pause a flow.
![\[The properties page of the Set event flow block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-set-event-flow.png)
Following are a couple of scenarios you may want to configure in your flows:
+ For flows that run at contact pause, configure them to notify supervisors when a task has been paused.
+ When resuming a paused contact, configure the flow to update contact attributes to make sure that agents are always working on the latest version of attributes.
## New events in the contact event stream and agent event stream
Contact event stream
When tasks are paused and resumed, new events are generated for PAUSED and RESUMED in the contact event stream and agent event stream.
The following image shows an example of a PAUSED event in the contact event stream.
![\[A PAUSED event in the contact event stream.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-pause-ces.png)
The following image shows an example of a RESUMED event in the contact event stream.
![\[A RESUMED event in the contact event stream.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-resumed-ces.png)
The following image shows an example of PAUSED tasks in the agent event stream.
![\[PAUSED events in the agent event stream.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-aes.png)
## Pause and resume task events in contact records
Pause and resume task events in contact records
The following events are captured in the [ContactTraceRecord](ctr-data-model.md#ctr-ContactTraceRecord) section of the contact records data model. You can use the [DescribeContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeContact.html) API to return task events.
| Name in contact record | Name returned by DescribeContact API |
| --- | --- |
| TotalPauseDurationInSeconds | TOTAL\$1PAUSED\$1TIME |
| TotalPauseCount | TOTAL\$1NUMBER\$1OF\$1PAUSES |
| LastPausedTimestamp | LAST\$1PAUSED\$1TIMESTAMP |
| LastResumedTimestamp | LAST\$1RESUMED\$1TIMESTAMP |
The following values are available in near real time when you use the [DescribeContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeContact.html) API or view the **Contact details** page for an in progress contact.
+ TotalPauseCount
+ LastPausedTimestamp
+ LastResumedTimestamp
A completed contact has TotalPauseDurationInSeconds.
## Metrics
Metrics
The following metrics display active, paused, and resumed time.
| Real-time metrics | Description |
| --- | --- |
| **[UI]** Agent/Routing Profiles/Queue → Performance → **Average Active Time** | SUM(active\$1time)/Number of contacts |
| **[UI]** Agent/Routing Profiles/Queue → Performance → **Average Agent Pause Time** | SUM(agent\$1pause\$1time)/Number of contacts that were paused |
| **[UI]** Agent → Contacts → **Contact State** | Paused state of a task contact |
| Historical Metrics | Description |
| --- | --- |
| **[UI]** Agent → Agent activity audit → Support "PAUSED" state | Display paused state when the contact for an agent is in Paused state |
| **[[GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html)]** Query Average of AGENT\$1PAUSE\$1TIME for a queue/routing profile/task | SUM(total\$1agent\$1pause\$1time) for all contacts that were paused from queue/routing profile/TaskAVG = SUM(total\$1agent\$1pause\$1time)/number of paused contacts for queue/RP/Tasks |
| **[[GetMetricDataV2](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetMetricDataV2.html)]** Query Average of ACTIVE\$1TIME for a queue/routing profile | SUM(total\$1handle\$1time - total\$1agent\$1pause\$1time) for all contacts of queue/routing profile/tasks AVG = SUM(total\$1handle\$1time - total\$1agent\$1pause\$1time) / total number of contacts for queue/routing profile/tasks |
| Contact details page | Description |
| --- | --- |
| **[UI]** Contact Search → Contact Details → Contact Summary → Last Paused Time | Last Paused Time |
| **[UI]** Contact Search → Contact Details → Contact Summary → Last Resumed Time | Last Resumed Time |
| **[UI]** Contact Search → Contact Details → Contact Summary → Number of Pauses | Total number of Pauses including when the contact was not connected. |
| **[UI]** Contact Search → Contact Details → Contact Summary → Total Pause Duration | Total Pause duration includes before and after the agent was connected. |
### Real-time Metrics page
Real-time Metrics page
The following image of the **Real-time Metrics** page shows the task contact state as **Paused**.
![\[The real-time metrics page, task in paused contact state.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-paused-rtm.png)
The following image of the **Real-time Metrics** page shows **Avg Active Time**, **AHT** and **Avg Agent Pause Time**.
![\[The real-time metrics page, task in paused contact state.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-rtm-2.png)
### Agent Activity Audit report
Agent Activity Audit report
The following image of the **Agent Activity Audit report** shows the Paused status when a contact is paused by the agent.
![\[The agent activity audit report, paused status.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-agent-activity-report.png)
# Create task templates in Amazon Connect
Create task templates
Task templates make it easy for agents to capture the right information to create and complete a [task](tasks.md). All the fields they need to create a given type of task are provided for them.
## Important things to know before you create your first template
Important things to know
+ When you publish your first template, your agents will be prompted to select a template when they create a new task. Agents must select one of the templates you have published.
+ If you want to return to the standard task experience and not require agents to select a template, on the **Task templates** page, use the **Disable/Enable** toggle to disable all templates you published.
+ Verify your Amazon Connect account has [permissions to create task templates](task-template-permissions.md).
+ Review the list of quotas for task templates, such as the **Task templates per instance** and **Task template customized fields per instance**. See [Amazon Connect service quotas](amazon-connect-service-limits.md).
+ You can configure a task template to allow an agent to assign the tasks to themselves. The agent needs the security profile permission **Contact Control Panel - Allow self assigning of contacts** and the **Restrict Task Creation** permission must be disabled. The agent will then be able to check a box when they create a task from the CCP and assign it to themselves.
## How to create a task template
How to create a task template
### Step 1: Name the template
Step 1: Name the template
1. Log in to the Amazon Connect console with an **Admin** account, or an account assigned to a security profile that has [permissions to create task templates](task-template-permissions.md).
1. In the left navigation menu, choose **Channels**, **Task templates**.
1. On the **Task templates page**, choose **\$1 New template**.
1. On the **Create new template** page, in the **Template name** box, enter the name that will be displayed your agents.
1. In the **Description** box, describe the purpose of the template. This information is not displayed to agents; it's for your own use.
### Step 2: Add fields, task assignment, schedule, and expiry
Step 2: Add fields
1. In the **Fields** section, choose the **Add field** dropdown, and then select the type of field you want to add to your template.
![\[The Create new template page, the Fields section, the Add field dropdown list.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-field-type.png)
1. Use the up and down arrows as needed to change the order the field appears on the template.
1. In the **Validation and permissions** section, choose whether the field is required to be populated by the agent when they create a task, or add a default value to pre-populate the field when the agent opens the template.
The following image shows what this section looks like for a field that is type **Email**.
![\[The Validation and permissions section for an email field.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-field-permissions.png)
**Note**
It is not possible to use attributes in the task templates page.
1. In the **Task assignment** section:
1. **Assign to**: Choose **Yes** to allow agents to view and edit a task assignment when they create the task. Or, assign a default value, as shown in the following image. Choose a published flow that runs after the agent chooses **Create** to create the task. Agents don't see the name of the flow on the CCP.
**Note**
Only published flows are listed in the **Default value** dropdown.
![\[The task assignment section, the default value dropdown list.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-task-assigment.png)
1. **Self-assign**: Choose **Yes** to allow agents to assign tasks to themselves on the CCP. For **Default state**, choose **True** if you want the self-assigned checkbox selected by default in the CCP.
![\[The Self assign checkbox section, the Default state option set to True.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-task-selfassigment.png)
1. In the **Task schedule** section, choose whether you want agents to be able to schedule a future start date and time for tasks.
1. In the **Expiry** section, specify how long the task should exist before it expires. The default is 7 days. You can configure it for up to 90 days (129,600 minutes)
![\[The Task durations section of the template. list.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-expiry-duration.png)
### Step 3: Publish
Step 3: Publish
After you configure your template, choose **Publish** to create it and make it visible to your agents.
**Important**
If this is your first template, when you choose **Publish**, agents are automatically required to select a task template when they create a task.
If you want to maintain the standard task experience without selectable templates, disable all templates.
## What your agents experience
The agent experience
After you publish a template, agents are required to select a template to create a task.
For example, the following image shows two templates have published: **Customer Email Template** and **Billing Dispute**.
![\[The task templates page, the disable or enable toggle for each template.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-published.png)
In the Contact Control Panel, when agents choose **Create task** they must choose one of the templates: **Billing Dispute** or **Customer Email Template**.
![\[The create task button on the CCP, the two templates the agents can select.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-agent-experience.png)
Let's assume the agent chooses **Customer Email Template**. The following image shows the fields the agent must complete in order to create a task. Notice that there is no option for the agent to assign the task to others; this template has **Task assignment** set to a default value. However, the agent can opt to assign the task to themselves.
![\[The CCP, no option to assign a task to others, but agent can assign the task to themselves.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-create-task-ccp.png)
## "No data" message in the Assign to dropdown
"No data" message
Let's say that in the **Task assignment** section, you choose to allow agents to assign the task to another agent. To set up for this scenario, you must create a quick connect for the destination agent so it appears in the dropdown list of choices, as shown in the following image. For instructions about creating a quick connect for an agent, see [Test tasks](chat-testing.md#test-tasks).
![\[The CCP, create task page, the Assign to field set to John Doe's quick connect.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-choose-agent-quick-connect.png)
If no quick connects exist, then the message **No data** appears when you choose the **Assign to** dropdown menu, as shown in the following image.
![\[The CCP, create task page, Assign to blank, No data message at the bottom of page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-templates-no-data.png)
# Grant users permissions to create task templates in Amazon Connect
Assign permissions for creating task templates
Assign the **Routing**, **Task templates** permissions to enable a user to create task templates.
For information about how to add more permissions to an existing security profile, see [Update security profiles in Amazon Connect](update-security-profiles.md).
By default, the **Admin** security profile already has permissions to perform all task activities.
# Block agents from creating tasks in the Amazon Connect Contact Control Panel (CCP)
Block agents from creating tasks
To block agents from being able to create tasks, assign the **Contact Control Panel (CCP)**, **Restrict task creation** permission. By default this permissions is unchecked, which means all agents can create tasks.
For information about how to add more permissions to an existing security profile, see [Update security profiles in Amazon Connect](update-security-profiles.md).
By default, the **Admin** security profile already has permissions to perform all tasks activities.
# Set up application integration to create tasks in Amazon Connect
Set up applications for task creation
Set up application integration to create tasks, without needing to code.
**Tip**
If your organization is using custom [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) policies to manage access to the Amazon Connect console, make sure users have the appropriate permissions to set up applications for task creation. For a list of required permissions, see [Tasks page](security-iam-amazon-connect-permissions.md#tasks-page).
If your instance was created before October 2018, for information about how to configure your service-linked roles (SLR), see [For instances created before October 2018](connect-slr.md#migrate-slr).
**Topics**
+ [
# Set up application integration for Salesforce using Amazon AppFlow
](integrate-salesforce-tasks.md)
+ [
# Set up application integration for Zendesk using Amazon EventBridge
](integrate-zendesk-tasks.md)
+ [
# Monitor task creation in Amazon Connect
](monitor-task-creation.md)
+ [
# Disconnect Amazon Connect from a third-party connection
](disassociate-connection.md)
# Set up application integration for Salesforce using Amazon AppFlow
If you integrate with Salesforce for event creation, Amazon Connect also uses Amazon AppFlow to put the data into EventBridge. This is because of how Salesforce sends events through the Amazon AppFlow APIs. To learn more about how Amazon Connect uses EventBridge and Amazon AppFlow resources to power Salesforce integrations, see this blog post: [ Building Salesforce integrations with Amazon EventBridge and Amazon AppFlow](https://aws.amazon.com/blogs/compute/building-salesforce-integrations-with-amazon-eventbridge/).
**Note**
If you use custom AWS Identity and Access Management (IAM) policies, for a list of the required IAM permissions to set up Amazon Connect Tasks, see [Tasks page](security-iam-amazon-connect-permissions.md#tasks-page).
**To integrate Salesforce for task creation**
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. Choose **Tasks**, and then choose **Add an application**.
![\[The tasks page, the Add an application button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-add-an-application-button.png)
1. On the **Select application** page, choose **Salesforce**.
1. Review the application requirements that are listed on the **Select application** page.
The following image shows the requirements for Salesforce.
![\[The select application page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-choose-an-app-salesforce.png)
1. To verify that Salesforce is compatible with Amazon AppFlow, log in to Salesforce, for example, https://[instance\$1name].my.salesforce.com.
**Important**
Verify that you have enabled **Change Data Capture** in Salesforce. The following image shows an example **Change Data Capture** page in Salesforce where you select the Case entities:
![\[The change data capture page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-verify-app-salesforce.png)
1. After you verify Salesforce requirements, on the **Select application** page, choose **Next**.
1. On the **Establish connection** page, choose one of the following:
+ **Use an existing connection**. This allows you to reuse existing EventBridge resources that are linked to Amazon AppFlow flows that you may have created in your AWS account.
+ **Create a new connection**: Enter the information required by the external application.
1. Enter your application instance URL. This URL is used for deep-linking into the tasks created in your external application.
1. Provide a friendly name for your connection, for example, **Salesforce - Test instance**. Later, when you [add rules](add-rules-task-creation.md), you'll refer to this friendly name.
1. Specify whether this is a production or sandbox environment.
![\[The establish connection page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection.png)
1. Choose **Log in to Salesforce**.
1. In Salesforce, choose to allow access to Amazon Connect Embedded Login App [Region].
![\[The salesforce login page, the allow access prompt.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection-allow-access-salesforce.png)
1. After Amazon Connect has successfully connected with the Salesforce, go to Salesforce and verify that the refresh token policy for Amazon Connect Embedded Login App is set to **Refresh token is valid until revoked**. This grants Amazon AppFlow access to pull data from your Salesforce account without re-authenticating.
1. On the **Establish connection** page, select the box shown in the following image, and choose **Next**.
![\[The Establish connection page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection-successful.png)
1. On the **Review and integrate** page, check that the **Connection status** says **Connected**, and then choose **Complete integration**.
![\[The Review and integrate page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection-review-and-integrate.png)
1. On the **Tasks** page, the new connection is listed.
![\[The Tasks page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection-final.png)
You're done\$1 Next, add rules that tell Amazon Connect when to create a task and how to route it. For instructions, see [Create rules that generate tasks for third-party integrations in Amazon Connect](add-rules-task-creation.md).
## What to do when is a connection isn't successfully established
A connection might fail to be established for Salesforce if you didn’t follow the instructions next to the check boxes to verify that it's compatible with Amazon AppFlow.
A common error is not setting up the **Case** entity in the **Change Data Capture** settings to capture these events. To fix:
1. Log in to Salesforce, go to the **Change Data Capture**, and select the Case entity.
![\[The change data capture page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-verify-app-salesforce.png)
1. Open the Amazon AppFlow console at [https://console.aws.amazon.com/appflow)](https://console.aws.amazon.com/appflow) to select the flow that was just created, and then choose **Activate flow**.
![\[The flow in the Amazon AppFlow console.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-integration-activate-flow.png)
Alternatively, you might need to delete the Amazon AppFlow Salesforce connection and flow, and start again.
# Set up application integration for Zendesk using Amazon EventBridge
## Step 1: Enable the events connector for Amazon EventBridge
Enable the events connector for Amazon EventBridge
If you don't already have the EventBridge connector for Zendesk enabled, you need to set it up first. Otherwise, go to [Step 2: Integrate Zendesk with Amazon Connect for task creation](#steps-integrate-zendesk).
1. Copy your AWS account number:
1. In the Amazon EventBridge console, go to **Partner event sources**.
1. Search for or scroll to **Zendesk**, and choose **Set up**.
1. Choose **Copy** to copy your AWS account information.
1. Go to [Setting up the events connector for Amazon EventBridge](https://support.zendesk.com/hc/en-us/articles/360043496933-Setting-up-the-events-connector-for-Amazon-EventBridge) in the Zendesk Help and follow the instructions.
## Step 2: Integrate Zendesk with Amazon Connect for task creation
Integrate Zendesk with Amazon Connect for task creation
**Note**
If you use custom AWS Identity and Access Management (IAM) policies, for a list of the required IAM permissions to set up Amazon Connect Tasks, see [Tasks page](security-iam-amazon-connect-permissions.md#tasks-page).
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. Choose **Tasks**, and then choose **Add an application**.
![\[The tasks page, the add an application button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-add-an-application-button.png)
1. On the **Select application** page, choose **Zendesk**.
1. After you choose to integrate with Zendesk, the application requirements are listed on the page.
The following image shows the requirements for Zendesk. In this procedure, we walk you through the steps to select the "Support ticket" event type in Zendesk. Acknowledge the steps and choose **Next**.
![\[The select application page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-choose-an-app-zendesk.png)
1. On the **Establish connection** page, choose one of the following:
+ **Use an existing connection**. This allows you to reuse existing EventBridge resources you may have created in your AWS account.
+ **Create a new connection**: Enter the information required by the external application.
1. Enter your application instance URL. This URL is used for deep-linking into the tasks created in your external application.
1. Provide a friendly name for your connection, for example, **Zendesk - Test instance**. Later, when you [add rules](add-rules-task-creation.md), you'll refer to this friendly name.
![\[The Establish connection page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection-zendesk.png)
1. Choose **Copy** to copy your AWS account ID, and then choose **Login to Zendesk**. This takes you away from the **Establish connection** page for now, but you return to it shortly.
1. After you're logged in to Zendesk, choose **Connect** to connect the Events Connector for Amazon EventBridge.
![\[The integrations page in Zendesk.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-connect-zendesk-eventbridge.png)
1. In Zendesk, on the **Amazon Web Services** page, paste in your Amazon Web Service account ID, choose your Region, choose **Support ticket**, acknowledge the terms of use, and the choose **Connect**. Zendesk creates a resource in Amazon EventBridge.
![\[The Amazon Web Services page in Zendesk.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-connect-zendesk-support-ticket.png)
1. Return to the **Establish connection** page in Amazon Connect choose **Next**.
1. On the **Establish connection** page, you'll see the message that Amazon Connect has successfully connected with Zendesk. Choose **Next**.
![\[The Establish connection page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection-final-zendesk.png)
1. On the **Review and integrate** page, check that the **Connection status** says **Connected**, and then choose **Complete integration**.
This creates a connection that associates the EventBridge resource for Zendesk to Amazon Connect.
![\[The Review and integrate page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection-review-and-integrate-zendesk.png)
1. On the **Tasks** page, the new Zendesk connection is listed, as shown in the following image.
![\[The tasks page showing the new Zendesk connection.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-establish-connection-final2-zendesk.png)
You're done\$1 Next, add rules that tell Amazon Connect when to create a task and how to route it. For instructions, see [Create rules that generate tasks for third-party integrations in Amazon Connect](add-rules-task-creation.md).
## What to do when is a connection isn't successfully established
A connection might fail to create a task if you do not correctly select the **Support ticket** event type when setting up the connection in Zendesk, after being prompted to do so in the flow. To fix this, log in to Zendesk, and update that setting, as shown in the following image.
![\[The Amazon Web Services page, the support ticket option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/zendesk-support-ticket.png)
There is also another case where you may not have selected the correct AWS Region that the Amazon Connect instance is in, when setting up EventBridge. To fix:
1. Go to the EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. Disconnect your EventBridge connection.
1. In the Amazon Connect console, restart the flow.
# Monitor task creation in Amazon Connect
After your connection is established, if it stops working, in Amazon Connect disassociate the connection, and then re-establish it. If that doesn't solve the issue, do the following:
**Zendesk**
1. Go to the EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. Check the status of the event source connection to see if it is active.
**Salesforce**
1. Go to the Amazon AppFlow console at [https://console.aws.amazon.com/appflow)](https://console.aws.amazon.com/appflow).
1. Monitor the flow that was created for the account that was set up.
The following image shows what a flow looks like in the Amazon AppFlow console for Salesforce. It contains information about the status of the connection, and when it was last run.
![\[The Amazon AppFlow console for Salesforce.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/salesforce-appflow-flow.png)
For both Zendesk and Salesforce, you can go to the EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/) to see your connection state and see if it is active, pending, or deleted.
The following image shows an example EventBridge console.
![\[An example EventBridge console.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/eventbridge-zendesk-salesforce-connection-health.png)
# Disconnect Amazon Connect from a third-party connection
At any time you can disassociate a connection, and stop the automatic generation of tasks based on events from the external application.
**To stop the automatic generation of tasks**
1. Choose the application, and then choose **Remove connection**.
![\[The disconnect from Salesforce page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-disconnect-connection.png)
1. Type **Remove**, and then choose **Remove**.
If you need to debug, you are still able to go to Amazon AppFlow (Salesforce) or EventBridge.
![\[The disconnect from Salesforce option in Amazon AppFlow.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-disconnect-2.png)
**To remove the connection altogether from Zendesk**
1. Log in to Zendesk, and navigate to **https://[subdomain].zendesk.com/admin/platform/integrations**.
1. Disconnect the EventBridge connection.
**To remove the connection altogether from Salesforce**
+ Open the Amazon AppFlow console at [https://console.aws.amazon.com/appflow](https://console.aws.amazon.com/appflow), and delete the Salesforce connection and flow that were created in Amazon Connect.
Flows are created with the name pattern of amazon-connect-salesforce-to-eventbridge-[subdomain].
Connections are created with the name pattern of amazon-connect-salesforce-[subdomain]
To re-enable the automatic generation of tasks, repeat the setup steps.
# Create rules to automate tasks in Amazon Connect
Create rules
A rule is an action that Amazon Connect automatically performs, based on conditions you specify. Contact center managers, supervisors and QA analysts can quickly create rules from the Amazon Connect console. No coding is required.
## More information
More information
+ To create and manage rules programmatically, see [Rules actions](https://docs.aws.amazon.com/connect/latest/APIReference/rules-api.html) and the [Amazon Connect Rules Function language](https://docs.aws.amazon.com/connect/latest/APIReference/connect-rules-language.html) in the *Amazon Connect API Reference Guide*.
+ [Add real-time alerts to Contact Lens for supervisors based on keywords and phrases in a call](add-rules-for-alerts.md)
+ [Automatically categorize contacts by matching conversations with natural language statements, or specific words and phrases](rules.md)
+ [Create a rule that generates a task](contact-lens-rules-create-task.md)
+ [Create a rule that generates an EventBridge event](contact-lens-rules-eventbridge-event.md)
+ [Create rules that send email notifications](contact-lens-rules-email.md)
+ [Notify supervisors and agents about performance evaluations](create-evaluation-rules.md)
+ [Create alerts on real-time metrics in Amazon Connect](rule-real-time-metrics.md)
+ [Create rules that generate tasks for third-party integrations in Amazon Connect](add-rules-task-creation.md)
# Create rules that generate tasks for third-party integrations in Amazon Connect
Create rules for third-party integrations
After you set up an external application to generate tasks automatically, you need to build rules that tell Amazon Connect when to create tasks, and how to route them.
1. Log in to Amazon Connect with a user account that is assigned the **CallCenterManager** security profile, or that is enabled for **Rules** permissions.
1. In Amazon Connect, on the navigation menu, choose **Rules**.
1. On the **Rules** page, use the **Create a rule** dropdown list to choose **External application**.
1. At the **Trigger and conditions** page, assign a name to the rule. Spaces are not allowed in the name of a rule.
![\[The New rule page, spaces are not allowed in the name of a rule.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules.png)
1. Choose the event that will generate a task, and the instance of the external application where the event must occur. For example, the following image shows the trigger is when a new ticket is created in Zendesk. The condition that must be met is when the type equals a question. Then a task is generated.
![\[The When and Type dropdown menus.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-add-rule-for-zendesk.png)
1. Select the instance for the external application.
1. Choose the conditions that must be met to generate the task.
1. Choose **Next**.
1. On the **Action** page, specify the task to be generated when the rule is met, as shown in the following image
![\[The Action page, the task to be generated when the rule is met.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/task-rule-action-to-take.png)
1. The description of the task appears to the agent in their Contact Control Panel (CCP).
1. The task reference name appears to the agent as a link to the specified URL.
1. Choose **Save**.
## Test the rule
Test the rule
1. Go the external application and create the event that initiates the action. For example, in Zendesk, create a ticket that's type **Question**.
1. Go to **Analytics and optimization**, **Contact search**.
1. Under **Channel**, choose **Task**, and then choose **Search**.
1. Verify the task was created.
# Set up email in Amazon Connect
Set up email
Following is an overview of the steps to set up the email channel for your contact center.
+ [Enable email for your Amazon Connect instance](enable-email1.md). During this process you get an auto-generated email address. You also have the option of adding five custom addresses.
+ [Create email addresses](create-email-address1.md).
+ [Create or update queues](create-queue.md) for email: In the **Outbound email configuration** section:
+ **Default email address**: Specify the outbound email address that is pre-selected for agents when they reply to or initiate emails.
+ This must be a verified email address within Amazon Connect (an email address created in Amazon Connect under an Amazon SES verified domain).
+ This should be the most commonly used email address for this queue.
+ For agent-initiated outbound emails, agents can send emails using the default email address from the default outbound queue configured in their routing profile. Agents can also select from the **Additional email addresses** configured on the queue, giving you flexibility to control which email addresses agents can use based on their role or team.
+ This model is similar to outbound voice contacts, where you specify the outbound caller ID and flow per queue, and agents use the default outbound queue from their routing profile.
+ **Outbound email flow**: Select a flow to execute for outbound emails sent from this queue. You can select the [Default outbound flow in Amazon Connect: "This call is not being recorded"](default-outbound.md) or another flow that is type Outbound.
+ The outbound email flow you configure here applies to agent replies to inbound email contacts received on this queue, and agent-initiated outbound emails when this queue is selected as the default outbound queue in the agent's routing profile.
+ If you do not specify an outbound email flow, the [Default outbound flow in Amazon Connect: "This call is not being recorded"](default-outbound.md) is automatically used for all outbound emails from this queue.
+ Similar to outbound voice contacts, configuring different outbound email flows per queue gives you flexibility to execute different contact flows based on the queue. This allows you to customize the outbound email experience for different teams, brands, or business units.
In the **Additional email addresses** section:
+ **Search for email addresses**: Select up to 49 additional email addresses that agents can use when replying to or initiating emails. Agents can select from all configured email addresses (default plus additional) using a dropdown list in their workspace (see [Select a From email address](agent-select-from-email.md)). You can configure up to 50 total email addresses per queue (1 default \$1 49 additional).
The list of available email addresses respects [tag-based access control (TBAC)](https://docs.aws.amazon.com/connect/latest/adminguide/tag-based-access-control.html). Agents only see email addresses they have permission to use based on their assigned tags.
+ [Create or update routing profiles](routing-profiles.md) to specify that agents can handle email contacts.
**Important**
In the routing profile:
**Default outbound queue** defines the list of email addresses available to agents for any outbound emails they initiate. Agents can select from the email addresses configured on this queue.
**Maximum contacts per agent** defines how many emails agents can receive, and double that number is how many outbound emails agents can initiate. For example, if you set **Maximum contacts per agent** to 5, agents can receive up to 5 emails and create up to 10 agent-initiated outbound emails.
+ [Create message templates](create-message-templates1.md). Email templates can define the structure of the email for the agent, for example, for a signature or a disclaimer, or they can be a full response.
+ Configure flows with the [Send message](send-message.md) block. Use this block to send a message to your customer based on a template or custom message. In addition, you can specify:
+ The To and From email addresses and display names. You can specify them manually or dynamically by using [System attributes](connect-attrib-list.md#attribs-system-table) such as:
+ **Customer endpoint address**: This is the customer's email address that initiated the contact.
+ **System email address**: This is the email address that the customer sent the email to.
+ **Customer display name**: This is captured from the email the customer sent to you.
+ **System display name**: The display name of the email the customer sent to.
+ **CC Email Address List**: The full list of cc'ed email addresses on the customer's email.
+ **To Email Address List**: The full list of To email addresses on the customer's email.
For example, to send an automatic reply when a customer emails you, set **Email address** dynamically to **Customer endpoint address**, and **Display name** dynamically to **Customer display name**.
+ **Message**: Specify a template or enter plain text.
+ You can specify the **Subject** dynamically by using the **Segment attribute** - **Email Subject**.
+ You can specify the **Message** dynamically by choosing a **User-defined** attribute.
+ **Link to contact**: Choose if you want to link the inbound contact email to the outbound contact email. You may not want to choose this option for automatic reply emails.
+ Use the attributes in the [Check contact attributes](check-contact-attributes.md) block to check the channel of the contact. If it's an email, you can use the following [Segment attributes](connect-attrib-list.md#attribs-segment-attributes) to check:
+ **Email Subject**: You can check the subject for certain keywords, for example.
+ **Amazon SES Spam Verdict** and **Amazon SES Virus Verdict**: When the customer's email comes in, Amazon SES scans it for spam and viruses. For example, if the condition equals FAILED (that means, the email failed the check) you can disconnect the contact or send the email to a special queue for managers to review it.
+ Assign the following security profile permission to your agents who need to initiate outbound emails.
+ **Contact Control Panel (CCP)** - **Initiate email conversations**
# How Amazon Connect email works
How Amazon Connect email works
Amazon Connect Email provides built-in capabilities that make it easy for you to prioritize, assign, and automate the resolution of customer service emails, improving customer satisfaction and agent productivity. You can receive and respond to emails sent by customers to your [configured email addresses](create-email-address1.md), or submitted by using web forms on your website or mobile app by using the [StartEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartEmailContact.html) API.
Amazon Connect Email integrates with [Amazon Simple Email Service (SES)](https://docs.aws.amazon.com/ses/latest/dg/Welcome.html) to send, receive, and monitor emails for [content marked as spam or containing viruses](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-concepts.html#receiving-email-auth-and-scan), [delivery success rates](https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-activity.html), and [sender reputation results](https://docs.aws.amazon.com/ses/latest/dg/monitor-sender-reputation.html).
This topic explains how Amazon Connect Email, along with Amazon SES, work to enable a seamless customer experience.
**Topics**
+ [Receive emails](#email-capabilities-howreceived)
+ [Email contacts](#email-capabilities-howtranslated)
+ [Every email message is a unique email contact](#email-capabilities-howmanaged)
+ [Email threads](#email-capabilities-howthreadsmanaged)
+ [Send email](#email-capabilities-howemailssent)
## Receive emails
Receive emails
There are three main ways that Amazon Connect can receive emails:
+ **Method 1**: By an [email address](create-email-address1.md) defined in Amazon Connect (for example, support@*customer-domain*.com) using a [verified email domain from Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html#just-verify-domain-proc), such as the email domain provided with your Amazon Connect instance (for example, @*instance-alias*.email.connect.aws) or a custom verified domain that you own or is provided by your company (for example, @*customer-domain*.com). See [Step 3: Use your own custom email domains](enable-email1.md#use-custom-email) in [Enable email for your instance](enable-email1.md) for details about onboarding custom email domains.
+ **Method 2**: By using a routing rule on your email server (for example, [Microsoft 365 Connectors](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/use-connectors-to-configure-mail-flow/set-up-connectors-to-route-mail), [Google Workspace Mail Routes](https://support.google.com/a/answer/2614757?hl=en&ref_topic=2921034&sjid=9077065025577504786-NC)) to send the incoming email to one of [Amazon SES's SMTP endpoints](https://docs.aws.amazon.com/general/latest/gr/ses.html) using a verified email domain onboarded to Amazon SES (for example, @*customer-domain*.com).
+ **Method 3**: By using the [StartEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartEmailContact.html) API to start an email contact by using a webform on your website or in your mobile app. This starts inbound email contacts similar to customers sending emails to your email addresses.
The following diagram illustrates how emails sent from your customers are received by Amazon Connect using the [StartEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartEmailContact.html) API for each of the methods mentioned above.
![\[A diagram showing how a message is sent as a webform or email to the StartEmailContact API.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-ses-diagram.png)
To integrate Methods 1 or 2, you need to verify an email domain on Amazon SES before you can use the email domain in Amazon Connect. For instructions, see [Verifying a DKIM domain identity with your DNS provider](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html#just-verify-domain-proc).
To integrate Method 3, you use the [StartEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartEmailContact.html) API. This is the primary API of all integration methods for inbound email contacts. It functions similarly to [StartTaskContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartTaskContact.html). It requires you to do one of the following steps:
+ Include at least one email address from your Amazon Connect instance in either the To or CC attributes of the inbound email contact.
—OR—
+ Define an inbound flow from your Amazon Connect instance to route the inbound email contact created.
If both are defined, the default behavior prioritizes the inbound flow from your Amazon Connect instance to handle the inbound email contact created. If multiple email addresses from your Amazon Connect instance are included in the To or CC email address attributes, multiple inbound email contacts will be created in your Amazon Connect instance.
## How email messages become email contacts
Email contacts
For general email receiving in Amazon Connect, including webform based email, the [StartEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartEmailContact.html) API exposes basic email fields on the request object. This object is used to populate email information and start an email contact in Amazon Connect. The following fields are included:
+ A From email address
+ To email address(es)
+ CC email address(es)
+ A subject
+ A plain or HTML message body
+ Attachment(s)
For more information about how the email contact information is populated into the email contact, see the Amazon Connect email contact data model .
After the [StartEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartEmailContact.html) API has performed request parameter validation and ensured that at least one To or CC email address is valid and exists in the Amazon Connect instance, here's what happens:
1. A contact ID is generated and returned as part of the API response body.
1. An asynchronous workflow is triggered to perform additional email message processing.
1. The flow is started. This is the flow that's associated with the email address found in the Amazon Connect instance.
As part of this, you need to setup your email message and attachment storage for your Amazon Connect instance.
+ Both email messages and attachments are stored and accessed in your own Amazon SES S3 bucket.
+ The remaining email contact attributes such as To, CC, Subject, and other attributes are stored on the email contact; see [Data model for Amazon Connect contact records](ctr-data-model.md).
The following diagram illustrates the flow of the email message from the customer to Amazon SES and then to Amazon Connect. It shows the email message content stored in your S3 bucket, and then getting data from that bucket to display it to the agent.
![\[A diagram that shows email message content stored in your S3 bucket.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-concepts-translated.png)
## Every email message is a unique email contact
Every email message is a unique email contact
Amazon Connect email differs from voice, chat, and tasks.
+ Every email message, inbound to or outbound from Amazon Connect, is its own unique email contact.
+ Each email contact contains details specific to that email message such as From address, To address(es), CC address(es), subject, relatedContactId, links to email body and attachment(s) storage locations, and other details relevant to the individual email contact.
However, like other channels in Amazon Connect, an email contact has similar initiation methods, such as `INBOUND`, `OUTBOUND`, `TRANSFER`, `API`, `QUEUE_TRANSFER` and `END/DISCONNECT`. It also has similar states, such as `CREATED`, `QUEUED`, `CONNECTING`, `CONNECTED`, `MISSED`, `TRANSFERRED`, `ERROR`, `ENDED/DISCONNECTED`, `REJECTED`.
For information about how the email contact information is populated into the email contact, see [Data model for Amazon Connect contact records](ctr-data-model.md).
## Email threads
Email threads
Email threading ensures that outgoing emails and incoming responses related to a customer inquiry are associated with each other in a chronological and organized fashion.
In order to maintain the whole email conversation, Amazon Connect links the email contacts together using a few fields on the email contact such as the relatedContactId and a list of email headers that follow conventional email client standards (RFC 5256).
Most email clients such as Gmail, Apple Mail, and Outlook, support email threading. However, keep in mind that there are some that don't support it.
If your customer replies to the latest email message in the thread, the thread follows a straightforward pattern as shown in the following image:
![\[The email thread in a straightforward pattern.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-threading.png)
If the customer replies to an older message in the email thread, an email thread tree is formed, and the email thread pattern looks something like the example in the following image:
![\[The email thread in a tree pattern.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-threading-tree.png)
In both scenarios Amazon Connect keeps a record of each of the email messages that are related to a thread. Each email message can be accessed by the email that succeeded it.
## Send email
Send email
All email messages from Amazon Connect are sent from Amazon SES directly to your customer. Whether you're using the email domain provided with your Amazon Connect instance (for example, @*instance-alias*.email.connect.aws) or a custom verified domain (for example, @*customer*.com), Amazon SES is authorized by verifying a domain identity to send emails directly to your customers.
The following diagram shows that the [StartOutboundEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartOutboundEmailContact.html) API sends email to Amazon SES, and Amazon SES sends it to your customer.
![\[Diagram showing email flow from StartOutboundEmailContact API through SES to customer.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-concepts-sent.png)
The [StartOutboundEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartOutboundEmailContact.html) API is the primary API of all integration methods for outbound email contacts including agent replies to inbound contact and agent-initiated outbound email contacts.
+ It functions similarly to [StartEmailContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartEmailContact.html) API, however it is the inverse since it is outbound.
+ It requires at least one email address in either the To or CC email address attributes and it requires an outbound whisper flow for handling the outbound contact.
# Enable email for your Amazon Connect instance
Enable email for your instance
This topic is for administrators who have access to the Amazon Connect console. It explains how to enable email for your instance using the Amazon Connect admin website. For a list of the APIs to enable email programmatically, see [APIs to enable email](#apis-email-setup2).
When you enable email, you get an auto-generated email domain. Optionally, you can also use custom domains.
+ **Amazon Connect email domain**. The email domain is **instance-alias*.email.connect.aws*.
+ You can use this domain for testing.
+ Or, you can use this email domain to integrate with Amazon Connect and start receiving emails into Amazon Connect. For example, if you have an email address such as *support@example.com* you can forward email into Amazon Connect by using *support@example.email.connect.aws*.
+ **Custom domains**. You can specify up to 5 custom domains that have been [onboarded to Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html#just-verify-domain-proc).
## Step 1: Move Amazon SES into production mode
Step 1: Move Amazon SES into production mode
Amazon Connect uses Amazon SES for sending and receiving emails. If you have a new Amazon SES instance, you need to take it out of sandbox mode. For instructions, see [Request production access (Moving out of the Amazon SES sandbox)](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) in the *Amazon SES Developer Guide*.
After you move Amazon SES into production mode, if you already enabled email when you created your Amazon Connect instance, skip to these topics:
+ [(Optional) Step 3: Use your own custom email domains](#use-custom-email)
+ [Step 5: Configure a CORS policy on your attachments bucket](#config-email-attachments-cors1)
## Step 2: Get a default Amazon Connect email domain
Step 2: Get a default Amazon Connect email domain
These steps only apply if you already created an Amazon Connect instance but didn't enable email. Complete these steps to get a default email domain from Amazon Connect.
1. In the Amazon Connect console, on the left navigation menu, choose **Email**, and then choose **Create service role**. This role needs to be created only once for your account. It allows Amazon SES to route emails to Amazon Connect.
1. Choose **Add Domain** as shown in the following image.
![\[The Manage email page, the Add domain button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-aws-console1.png)
1. In the **Add email domain** box, choose **Amazon Connect email domain**, as shown in the following image. When you choose this option, the name of the domain is auto-generated: **instance-alias*.email.connect.aws*. You cannot change this email address.
![\[The Add email domain box, the Amazon Connect email domain option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-add-email-domain.png)
## (Optional) Step 3: Use your own custom email domains
(Optional) Step 3: Use custom email domains
You can import up to five custom domains that have been [onboarded to Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html#just-verify-domain-proc).
1. In the Amazon Connect console, on the left navigation menu, choose **Email**, and then choose **Add Domain** as shown in the following image.
![\[The Email channel on the Amazon Connect console.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-aws-console.png)
1. Choose **Use custom email domain**. Use the dropdown box to choose custom domains that have been [verified by Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html#just-verify-domain-proc).
![\[The Use custom email domain option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-add-custom-domain.png)
## Step 4: Enable email and create an Amazon S3 bucket for storing email and attachments
Step 4: Enable email and create an Amazon S3 bucket
These steps apply only if you already created an Amazon Connect instance but didn't enable email.
You need to update your **Data storage** settings to enable the email channel and specify the Amazon S3 bucket where email messages and attachments are to be stored. Email requires two Amazon S3 bucket pointers. They can be to the same Amazon S3 bucket or two different buckets.
**Important**
If you choose **Enable Attachments sharing** for your instance, you must create an Amazon S3 bucket and [configure a CORS policy on your attachments bucket](#config-email-attachments-cors1), as described in this topic. If you don't do this, **the email channel will not work for your instance**.
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. On the left navigation menu, choose **Data storage**, **Email messages**, **Edit**, **Enable exporting email messages to S3**, and then choose **Save**.
1. Complete the **Email messages** page to create or select an S3 bucket where email messages are stored. The following image shows an example of a completed page.
![\[The Data storage menu option, the Email messages page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-messages-export-to-s3.png)
1. If you want to allow email attachments, choose **Attachments** as well. The following image shows these options.
The following image of the **Data storage** page shows the Amazon S3 bucket for email messages and attachments.
![\[The Amazon S3 bucket to store emails and attachments.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-s3-bucket.png)
## Step 5: Configure a CORS policy on your attachments bucket
Step 5: Configure a CORS policy
To allow customers and agents to upload and download files, update your cross-origin resource sharing (CORS) policy to allow `PUT` and `GET` requests for the Amazon S3 bucket you are using for attachments. This is more secure than enabling public read/write on your Amazon S3 bucket, which we don't recommend.
**To configure CORS on the attachments bucket**
1. Find the name of the Amazon S3 bucket for storing attachments:
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. In the Amazon Connect console, choose **Data storage**, and locate the Amazon S3 bucket name.
1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. In the Amazon S3 console, select your Amazon S3 bucket.
1. Choose the **Permissions** tab, and then scroll down to the **Cross-origin resource sharing (CORS)** section.
1. Add a CORS policy that has one of the following rules on your attachments bucket. For example CORS policies, see [Cross-origin resource sharing: Use-case scenarios](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html#example-scenarios-cors) in the *Amazon S3 Developer Guide*.
+ Option 1: List the endpoints from where attachments will be sent and received, such as the name of your business web site. This rule allows cross-origin PUT and GET requests from your website (for example, http://www.example1.com).
Your CORS policy may look similar to the following example:
```
[
{
"AllowedHeaders": [
"*"
],
"AllowedMethods": [
"PUT",
"GET"
],
"AllowedOrigins": [
"*.my.connect.aws",
"*.awsapps.com"
],
"ExposeHeaders": []
}
]
```
+ Option 2: Add the `*` wildcard to `AllowedOrigin`. This rule allows cross-origin PUT and GET requests from all origins, so you don't have to list your endpoints.
Your CORS policy may look similar to the following example:
```
[
{
"AllowedMethods": [
"PUT",
"GET"
],
"AllowedOrigins": [
"*"
],
"AllowedHeaders": [
"*"
]
}
]
```
## Next steps
Next steps
+ [Set up attachment scanning in Amazon Connect](setup-attachment-scanning.md): This topic is for developers who are familiar with Lambda. You can configure Amazon Connect to scan email attachments by using your preferred scanning application.
## APIs to enable email
APIs to enable email
Use the following APIs to enable email programmatically:
+ [CreateIntegrationAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html)
+ [AssociateInstanceStorageConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociateInstanceStorageConfig.html)
+ [DescribeInstanceStorageConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeInstanceStorageConfig.html)
# Create email addresses
Create email addresses
This topic explains how to create email addresses by using the Amazon Connect admin website. You can create email addresses that customers can reply to, as well as outbound only (no-reply) email addresses.
For a list of the APIs used to create and manage email addresses programmatically, see [APIs to create and manage email addresses](#apis-manage-email-addresses1).
You can create up to 100 email addresses.
**To create email addresses**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an admin account, or an account with **Channels and Flows** - **Email addresses** - **Create** permission in it's security profile.
1. On the navigation menu, choose **Channels**, **Email addresses**.
1. Choose a domain from the dropdown list. The list contains the auto-generated domain that was created when you enabled the email channel for your instance. It may also display up to five custom domains if you added them.
1. Under **Additional information**, you can optionally add the following:
+ **Friendly sender name**
+ **Description**: This is for your use, not customer facing.
+ **Flow**: Choose a published flow for sending emails. Leave this blank for the email address to be used only for outbound communication. Customers will not be able to reply to it.
**Tip**
To create **No-reply** email addresses, that is, addresses that are only used for outbound mail, and cannot accept a reply don't select a flow to be used for the email address.
1. Under **Tags**, optionally add [tags](tagging.md) to manage who can view and access email addresses in Amazon Connect and the agent workspace.
1. Choose **Create**.
## APIs to create and manage email addresses
APIs to create and manage email addresses
For a list of all email address APIs, see [Email actions](https://docs.aws.amazon.com/connect/latest/APIReference/email-api.html) in the *Amazon Connect API Reference Guide*.
Use the following APIs to create addresses programmatically:
+ [CreateEmailAddress](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateEmailAddress.html)
+ [DescribeEmailAddress](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeEmailAddress.html)
+ [UpdateEmailAddressMetadata](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateEmailAddressMetadata.html)
# Create message templates
Create message templates
If you frequently design and send a certain type of message, such as a weekly email or an appointment reminder, you can create and save it as a message template. You can then use the template as a starting point each time you need to send that type of message, instead of designing and writing the message again.
This topic is for administrators and contact center managers who want to create message templates using the Amazon Connect admin website.
**Tip**
Even though message templates use the Connect AI agents APIs, message templates don't lead to additional billing. You only pay for the chat message price or email price. For more information, see [Amazon Connect Pricing](https://aws.amazon.com/connect/pricing/).
## What are message templates?
What are message templates?
A *message template* is a set of content and settings that you can create, save, and then reuse in messages that you send. In some businesses they are referred to as *email templates* and *SMS templates*. When you create a message template, you specify the content that you want to reuse in various components of messages that are based on the template.
When you create a message, you can choose a template to use for the message. If you choose a template, Amazon Connect populates the message with the content and settings in the template.
You can design the following types of message templates in Amazon Connect:
+ **Email templates** for email messages that you send in reply to customer emails to your contact sent, or that agents can use for frequently asked questions. Email templates can define the structure of the email for the agent, for example, for a signature, or they can be a full response.
+ **SMS templates** for SMS text messages that you send from campaigns, or to a limited audience as direct or test messages.
+ **WhatsApp templates** for WhatsApp messages that you send from campaigns, or to a limited audience as direct or test messages.
You can create templates that have the following features:
+ Rich text formatting (bold, italics, underline, strikethrough, superscript, subscript), rich text font styling (color, highlight, size, heading, family, block quote, code block), special characters, emojis, lists (bulleted, numbered), alignment and indentations, tables, hyperlinks, and embedded images
+ Attributes within the email template to define personalize details such as customer name, customer email, customer account number, customer phone number, customer address, and agent name.
+ Attachments up to 1 MB. For a list of supported attachment types, see [Amazon Connect feature specifications](feature-limits.md).
When you create an email message that's based on a template, Amazon Connect populates the message with the content and settings that you defined in the template.
## How to create message templates
How to create message templates
1. Log in to Amazon Connect admin website with an Admin account or a user account that has **Content Management** - **Message templates** - **Create** in it's security profile.
1. In the navigation pane, choose **Message templates**.
1. If this is the first time you've created templates, you are prompted to create a knowledge base, which is where the templates are stored.
Your business can have several knowledge bases, but only one of them can be associated with templates.
1. Choose **Create template**.
1. Under **Channel**, choose a channel.
1. For **Name** enter a name for the template. The name must begin with a letter or number. It can contain up to 128 characters.
1. For **Description - *optional***, enter a brief description of the template. The description can contain up to 255 characters.
1. For **Routing profiles - *optional***, enter the routing profiles for agents to be able to use this template from the agent workspace.
1. Depending on whether you are creating an **Email**, an **SMS** or **WhatsApp** template, do one of the following:
For email templates:
1. Under **Email details**, use the following options to specify the content for messages that use the template:
+ For **Subject**, enter the text that you want to display in the subject line of the message.
+ For **Body**, enter the content that you want to display in the body of the message.
+ **Editor**: Use the rich text editor to enter the content. Use the formatting toolbar to apply formatting, add links, and other content to the message. To add attachments, your IT admin needs to enable the attachments feature for this option.
+ **Code**: Manually enter HTML content, including formatting, links, and other features that you want to include in the message.
You can also include personalized content in the subject and body of the template by using attributes. To do this, add message variables that refer to specific attributes that you or Amazon Connect created, such as an attribute that stores a user's first name. By using message variables, you can display different content for each recipient of a message that uses the template.
To use a message variable, choose the name of an existing attribute from the **Attribute finder**. Amazon Connect drops it into your message. You can copy and paste it to the location that you want. For more information, see [Add personalized content to message templates](personalize-templates.md).
![\[The Attribute finder on the Message templates page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/message-template-attribute-finder.png)
1. Under **Headers - *optional***, you can add two static headers to the email message. For example, to add a one-click unsubscribe link, to a promotional email, add the following two headers:
+ **List-Unsubscribe**: Set to your organization's unsubscribe link. The link must support HTTP POST requests to process the recipients unsubscribe request.
+ **List-Unsubscribe-Post**: Set to `List-Unsubscribe=One-Click`.
Including an unsubscribe link in your email is a best practice, and in some countries it's a legal requirement. If your template includes a link with this attribute, you must have in place a system for handling opt-out requests.
1. When you finish entering content and settings for the template, choose **Save**.
1. Before making the template available to users, we recommend that you send a test email message to make sure the template works as intended.
1. When you are ready for the template to be available in flows, campaigns, and to agents using the agent workspace, complete the steps to [activate](#create-message-templates1) it.
**For SMS templates:**
1. Under **SMS details** in the **Body** write the message. Use the above instructions to personalize the message by adding attributes as needed.
1. When you finish entering content and settings for the template, choose **Create**.
1. Before making the template available to users we recommend that you send a test message to make sure the template works as intended.
1. When you're ready for the SMS template to be available in the **Send message** block, or for the Email template to be available for email campaigns, complete the steps to [activate](#create-message-templates1) it.
**For WhatsApp templates:**
1. Under **WhatsApp details**, select the template from dropdown. Please note only Meta approved templates can be used to create message templates. Ensure your imported templates are approved in Meta Business WhatsApp Manager before proceeding.
1. Define a name for the template and add descriptions if needed.
1. Once you selected Meta approved template, you will see the details displayed in **Body** and **Template Metadata (JSON)** format.
1. **Attribute mapping:** To enable personalized message delivery in Amazon Connect, you will need to map your imported Meta attributes to custom text. By combining your existing Connect attributes with plain text, you can create customized messages for your customers. For example, you might see Hello \$1\$11\$1\$1 in the **Body**, and you can choose to `Attributes.Customer.FirstName` from Connect attribute list to match.
1. There are a variety of button types that can be added into a content template. If your selected template includes buttons, such as a Website URL that includes attributes, you can either select Connect attributes to map or type in static text.
1. When you completed attributes mapping, choose **Save**.
1. Before making the template available to users we recommend that you send a test message to make sure the template works as intended.
# Activate a message template
Activate a message template
To help you manage the development and use of individual message templates, Amazon Connect supports versioning for all types of message templates. Versioning provides a way for you to create a history of changes to a template—each version is a snapshot of a template at a certain point in time. Versioning also provides a way for you to control the contents and settings of messages that use a template.
You can only activate message templates that have been **Saved as new version**. This is to prevent accidentally activating templates that are drafts.
When a template version is **Activated**, it is available to be added to the [Flow block in Amazon Connect: Send message](send-message.md) and may be available to agents through the agent workspace.
**To activate a messaging template**
Log in to Amazon Connect admin website with an Admin account or a user account that has **Content Management** - **Message templates** - **Create** in it's security profile.
1. On the left navigation menu, choose **Message templates**.
1. On the **Message templates** page, save the template using the **Save as new version** option.
1. On the **Messaging templates** page re-open the template you just saved.
1. Use the dropdown menu to choose the version of the template to activate.
![\[The Version number for a template.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/message-template-version.png)
1. Choose **Activate**.
![\[The Activate button on the message template page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/message-template-version-activate.png)
# About versioning message templates
About versioning message templates
Each time you change a template, you can specify whether you want to save your changes as a new draft of the template or as an update to the most recent, existing draft of the template. As you design, develop, and refine a template, each of these versions serves as a snapshot that can help you track the progress and status of the template. That is to say, you can use versioning to store, track, and manage a template as it changes over time. You can:
+ Track the history of a template – For each template, Amazon Connect provides a list of versions of the template. This list displays the name of each version. The list is sorted in descending chronological order with the most recent version listed first.
+ View and compare versions of a template – By using the version list, you can browse previous versions of a template. If you choose a version from the list, Amazon Connect displays the contents and settings that are stored in that version.
+ Restore a previous version of a template – If you find issues in the most recent version of a template, you can restore a previous version that doesn't contain the issues. You can then save that previous version as a new version of the template. The new version then becomes the most recent version of the template.
You can also use versioning to control which version of a template can be used in messages. You do this by designating a specific version as the active version of a template. The active version is typically the version that's been most recently reviewed and approved for use in messages, depending on your organization's workflow for developing and managing templates.
When you designate a version as the active version, you enable that version for use in messages. As a template changes over time, you can designate a different version as the active version, and you can change that designation multiple times.
# Add personalized content to message templates
Add personalized content to message templates
To deliver dynamic, personalized content in messages that use a template, add *message variables* to the message template. A *message variable* is a placeholder that refers to a specific attribute that you or Amazon Connect created to store information about your users. Each attribute typically corresponds to a characteristic of a user, such as a user's first name or the city where they live. By adding message variables to templates, you can use these attributes to deliver custom content to each recipient of a message that uses a template.
If a template contains message variables, Amazon Connect replaces each variable with the current, corresponding value of the attribute for each recipient. It does this each time it sends a message that uses the template. This means that you can send personalized content to each recipient without creating multiple, customized versions of a message or message template. You can also feel confident that the message contains the latest information that you have for a recipient.
For example, if your project is a fitness application for runners and it includes attributes for each user's first name, preferred activity, and personal record, you could use the following text and message variables in a template:
`Hi {{Attributes.Customer.FirstName}}, attached is information about the insurance plans we discussed.`
When you send a message that uses the template, Amazon Connect replaces the variables with the current value of each attribute for each recipient. The following examples show this.
**Example 1**
`Hi Sofia, attached is information about the insurance plans we discussed.`
**Example 2**
`Hi Alejandro, attached is information about the insurance plans we discussed.`
## Add message variables
You can add message attributes to a new template you create or to an existing template. If you add variables to an existing template, Amazon Connect doesn't necessarily apply the changes to messages that use the template and haven't been sent yet. This depends on the version of the template that you add variables to and how you configured the messages that use the template.
**To add a message variable to a message template**
1. In the navigation pane, choose **Message templates**.
1. On the **Message templates** page, do one of the following:
+ To create a new template and add a message variable to it, choose **Create template**. Then, on the template page, enter a name for the template and, optionally, a description of the template.
+ To add a message variable to an existing template, choose the template that you want to add a variable to. Then, on the template page, choose **Edit**. Under **Template details**, use the version selector to choose the version of the template that you want to use as a starting point. If you choose the most recent version, you can save your changes directly to that version of the template. Otherwise, you can save your changes as a new version of the template.
1. In the message details section, determine where you want to add a message variable. For email templates, you can add variables to the message subject or the body. For SMS templates, you can add variables to the body.
1. Place your cursor where you want the attribute to be in your message. Click or tap on the **Attribute finder**, and then scroll to the type of attribute that you want to add a message variable for.
![\[The Attribute finder on the Message templates page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/message-template-attribute-finder.png)
You can choose from the following types of attributes:
+ **System attributes**:
+ **CustomerEndpointAddress**: The customer's email address that initiated the contact.
+ **SystemEmailAddress**: The email address that the customer sent the email to.
+ **Name**: The display name in the email that the customer sent to your contact center.
+ **Agent attributes**:
+ **FirstName**
+ **LastName**
+ **Customer profile attributes**. For a complete list and descriptions, see [Customer Profiles attributes](connect-attrib-list.md#customer-profiles-attributes).
+ **Recommendation attributes**: When using Predictive Insights with outbound campaigns, you can include personalized product recommendations in your message templates. These attributes are available when you configure recommendations in an event-triggered campaign.
Each recommendation is accessed using an index, such as `{{Attributes.Customer.Recommendations.[0].CatalogItem.Name}}` for the first recommendation, `{{Attributes.Customer.Recommendations.[1].CatalogItem.Name}}` for the second, and so on.
![\[Email template editor showing recommendation attributes in the Attribute finder and personalized product recommendations in the message body.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/RecommendationAttributesInTemplate.png)
For more information about configuring recommendations in campaigns, see [Create an outbound campaign using event triggers](how-to-create-campaigns-using-event-triggers.md).
1. When you click an attribute in the Attribute finder, it is automatically placed in your message. You can copy and paste the attribute to another location.
After you paste attribute, Amazon Connect displays it enclosed in two sets of curly braces—for example, `{{Attributes.Agent.FirstName}}`. The following image shows an email message with three attributes: the customer's first and last name, and the agent's first name.
![\[An email message with message attributes.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/message-template-email-attributes.png)
1. When you finish, do one of the following:
+ If you added message variables to a new template, choose **Save**.
+ If you added message variables to an existing template and you want to save your changes as a new version of the template, choose **Save as new version**.
+ If you added message variables to an existing template and you want to save your changes as an update to the most recent draft of the template, choose **Save**. If you want to update the draft and create a new version off of the draft, choose **Save as new version**.
# Use message template helpers
Use message template helpers
With Amazon Connect message templates, customers can create reusable message templates based on the Handlebars.js language. Helpers provide a variety of features like formatting a price to a specific Region's currency or adding a time zone-based location. A helper can use a specific string or integer for the value or a specific Amazon Connect message variable.
These are the categories of helpers, described in the following sections.
## Default helpers
This section describes the **built-in** helpers provided by Handlebars.
**Important**
The built-in `with` helper provided by Handlebars is not supported. However, all other Handlebars helpers are fully supported. For a full list, see [Built-in Helpers](https://handlebarsjs.com/guide/builtin-helpers.html) at [handlebarsjs.com](https://handlebarsjs.com).
These are the built-in helpers:
+ `each` – Iterates a list.
**Note**
The maximum list size is 15 items.
+ `if` – Evaluates a statement.
*each*
Iterates a list. This helper uses only a block statement. You can optionally:
+ Pass `@index` in the request to reference the current loop index.
+ Use the `this` helper to reference the current element being iterated.
+ Return the helper response in a list, using the `
` tag.
**Usage**
`{{#each value}}`
Value at position `{{@index}}` is `{{this}}`.
`{{else}}`
Condition is false.
`{{/each}}`
`each` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/each}}` in the block statement.
**Example**
In this example, `each` is used to return a list of a user's favorite colors. For a `false`, an `else` statement is returned. If the request is this:
`{{#each User.UserAttributes.FavoriteColors}}`
`
{{this}}
`
`{{else}}`
*You have no favorite colors.*
`{{/each}}` returns
+ *red*
+ *blue*
+ *yellow*
for a true statement.
*if*
Evaluates whether something is true and returns a response based on the evaluation.
**Usage**
`{{#if value}}`
Value isn't undefined
`{{else}}`
Value is undefined
`{{/if}}`
`if` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/if}}` in the block statement.
**Example**
In this example, the `if` helper is used to evaluate whether a user's first name. If the name is found, a greeting is returned that passes the user's first name in the response. Otherwise, the `else` statement returns an alternative greeting.
`{{#if User.UserAttributes.FirstName.[0]}}`
`Hello {{User.UserAttributes.FirstName.[0]}},`
`{{else}}`
*Hello,*
`{{/if}}`
returns *Hello, Jane* if the `if` helper is true.
## Conditional helpers
This section describes the **conditional helpers**.
Conditional helpers can be used on either a single line or in a block statement. You can customize the response regardless of which helper method you use. You can pass additional conditional helpers within both single line and block statements. The following conditional helpers show usage first for a single line and then a block statement using an optional `else` clause. These are the conditional helpers:
+ `and` – Compares whether all passed elements are equal.
+ `eq` – Tests whether two elements are equal.
+ `gt` – Tests whether one element is greater than another.
+ `gte` – Tests whether one element is greater than or equal to another.
+ `if` – Evaluates whether something is true.
+ `lt` – Tests whether one element is less than another.
+ `lte` – Tests whether one element is less than or equal to another.
+ `neq` – Evaluates whether two elements are not equal.
+ `not` – Inverts the response of a Boolean operation.
+ `or` – Compares whether any of the elements in the argument are equal.
*and*
Compares whether *all* elements passed in an argument are equal, and then returns the response based on the result. This helper can be used for non-Boolean values. You must pass at least two elements for the condition.
**Usage**
+ `{{and valuea valueb valuec valued yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#and valuea valueb}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/and}}`
`and` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/and}}` in the block statement.
**Example**
In this example, `eq` is used within the `and` block statement to determine whether both strings passed for the `Location.City `and `Location.Country` attributes are true. If both conditions are equal, then a true statement is returned. If either of those attributes are false, then an `else` statement is returned.
`{{#and (eq Location.City "Los Angeles") (eq Location.Country "US")}}`
*You live in Los Angeles and the US.*
`{{else}}`
*You don’t live in Los Angeles and the US.*
`{{/and}}`
*eq*
Tests whether two elements are equal or if the value of one element is equal to a passed string.
**Usage**
+ `{{eq valuea valueb yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#eq valuea valueb}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/eq}}`
`eq` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/eq}}` in the block statement.
**Example**
In this example, `eq` is used to evaluate whether the value of `User.UserAttributes.FavoriteColors.[0]` is *Red*. If the response is `true`, a true statement is returned. If the response is `false`, then an `else` statement is returned.
`{{#eq User.UserAttributes.FavoriteColors.[0] "red"}}`
*Your favorite color is red.*
`{{else}}`
*You don't like red.*
`{{/eq}}`
*gt*
Tests whether the value of one element is greater than another.
**Usage**
+ `{{gt valuea valueb yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#gt valuea valueb}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/gt}}`
`gt` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/gt}}` in the block statement.
**Example**
In this example, the helper compares the value of `User.UserAttributes.UserAge.[0]` attribute against a string *17*, to verify whether the user's age is greater than 17. If the response is `true`, a true statement is returned. If the response is `false`, then an `else` statement is returned.
`{{#gt User.UserAttributes.UserAge.[0] "17"}}`
*You are old enough to rent a car.*
`{{else}}`
*You are not old enough to rent a car.*
`{{/gt}}`
*gte*
Tests whether the value of one element is greater than or equal to another.
`Usage`
+ `{{gte valuea valueb yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#gte valuea valueb}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/gte}}`
`get` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/gte}}` in the block statement.
**Example**
In this example, the helper compares the `User.UserAttributes.UserAge.[0]` attribute against a string *18*, to verify whether the user's age is greater than or equal to 18. If the response is `true`, a true statement is returned. If the response is `false`, then an `else` statement is returned.
`{{#gte User.UserAttributes.UserAge.[0] "18"}}`
*You are old enough to rent a car.*
`{{else}}`
*You are not old enough to rent a car.*
`{{/gte}}`
*if*
Evaluates whether something is true and returns a response based on the evaluation.
**Usage**
+ `{{#if value}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#if value}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/if}}`
`if` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/if}}` in the block statement.
**Example**
In this example, the helper is used to evaluate whether a user's first name. If the name is found, a greeting is returned that passes the user's first name in the response. Otherwise, the else statement returns an alternative greeting.
`{{#if User.UserAttributes.FirstName.[0]}}`
*Hello* `{{User.UserAttributes.FirstName.[0]}}`*,*
`{{else}}`
*Hello,*
`{{/if}}`
returns *Hello Jane,* if the helper is true.
*lt*
Tests whether the value of one element is less than the value of another.
**Usage**
+ `{{lt valuea valueb yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#lt valuea valueb}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/lt}}`
`lt` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/lt}}` in the block statement.
**Example**
In this example, the helper compares the `User.UserAttributes.UserAge.[0]` attribute against a string *18* , to verify whether the user's age is less than 18. If the response is `true`, a true statement is returned. If the response is `false`, then an `else` statement is returned.
`{{#lt User.UserAttributes.UserAge.[0] "18"}}`
*You are not old enough to rent a car.*
`{{else}}`
*You are old enough to rent a car.*
`{{/lt}}`
*lte*
Tests whether the value of an element is less than or equal to another.
**Usage**
+ `{{lte valuea valueb yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#lte valuea valueb}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/lte}}`
`lte` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/lte}}` in the block statement.
**Example**
In this block statement, the helper compares the `User.UserAttributes.UserAge.[0]` attribute against a string *17*, to verify whether the user's age is equal to 17 or younger. If the response is `true`, a true statement is returned. If the response is `false`, then an `else` statement is returned.
`{{#lte User.UserAttributes.Age.[0] "17"}}`
*You are not old enough to rent a car.*
`{{else}}`
*You are old enough to rent a car.*
`{{/lte}}`
*neq*
Test whether two elements are *not* equal.
**Usage**
+ `{{neq valuea valueb yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#neq valuea valueb}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/neq}}`
`neq` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/neq}}` in the block statement.
**Example**
In this block statement, the `User.UserAttributes.FavoriteColors.[0]` attribute is checked against a string `Red`. If the response is `true`, a true statement is returned. If the response is `false`, then an `else` statement is returned.
`{{#neq User.UserAttributes.Favorite.Colors.[0] "red"}}`
*You do not like red.*
`{{else}}`
*You like red.*
`{{/neq}}`
*not*
Inverts the response of a Boolean operation, so that if `not` is a positive comparison, then a `true` statement is returned. If the response is false, then an else statement is returned.
**Usage**
+ `{{not value yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition.
+ `{{#not value}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/not}}`
`not` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/not}}` in the block statement.
**Example**
In this block statement, the `User.UerAttributes.FavoriteColors.[0]` attribute is checked against a string *red*, using the `eq` helper. The `not` helper then returns the opposite of the `eq` helper. If the response returns any color other than *red*, a `true` a statement is returned. If the response returns *red*, then an `else` statement is returned indicating a false statement.
`{{#not (eq User.UserAttributes.Favorite.Colors.[0] "red")}}`
*You do not like red.*
`{{else}}`
*You like red.*
`{{/not}}`
**Example**
In this example,
`{{not (eq User.UserAttributes.FavoriteColors.[0] "red")}}`
returns false if `User.UserAttributes.FavoriteColors.[0]` is *red*.
*or*
Compares whether *any* of the elements in the argument are equal, and then returns a response based on the result. This helper can be used for non-Boolean values.
**Usage**
+ `{{or valuea valueb valuec valued yes='y' no='n'}}`
You can replace *y* and *n* with other values, such as *yes* and *no*, or any other string you want returned, depending on the condition. You must pass at least two elements for the condition.
+ `{{#or valuea valueb}}`
Condition is true.
`{{else}}`
Condition is false.
`{{/or}}`
`or` must be prefaced with a pound sign (`#`) and conclude with a closing `{{/or}}` in the block statement.
**Example**
In this `or` block statement, two strings for the `Location.City` attribute are compared additionally using the `eq` helper. If either of the attributes are `true`, then a true statement is returned. If one or more of the responses are `false`, then an `else` statement is returned.
`{{#or (eq Location.City "Los Angeles") (eq Location.City "Seattle")}}`
*You live on the West Coast of the United States.*
`{{else}}`
*You do not live on the West Coast of the United States.*
`{{/or}}`
## String helpers
This section describes the following **string** helpers:
+ `abbreviate` – Truncates a value.
+ `capitalize` – Capitalizes each word between white spaces.
+ `capitalizeFirst` – Capitalizes the first character of a value.
+ `center` – Centers a value.
+ `cut` – Cuts a value.
+ `dateFormat` – Sets the date style.
+ `inflect` – Returns a singular or plural string based on the count.
+ `join` – Joins an array, iterator, or an iterable object.
+ `ljust` – Justifies a value to the left margin.
+ `lower` – Converts a value to lower case.
+ `now` – Prints the current date.
+ `ordinalize` – Ordinalizes a numeric value.
+ `replace` – Replaces one string with another.
+ `rjust` – Justifies a value to the right margin.
+ `slugify` – Converts a value to lower case and removes non-word characters, converts spaces to hyphens, and removes trailing white space.
+ `stripTags` – Strips [X]HTML tags from a value.
+ `substring` – Returns a new string as a substring of a passed value.
+ `upper` – Converts the passed value to upper case.
+ `yesno` – Replaces true, false, and no with Yes, No, and Maybe.
*abbreviate*
Truncates a value if the value exceeds the number specified. White spaces are included in the length count. An ellipsis displays in the response to indicate a truncated value. The ellipsis counts towards the truncated value in the response. This type of helper is useful if you have a large table and minimal space. Truncating values in a cell allows you to have a more uniform look to the table.
**Usage**
`{{abbreviate value X}}`, replacing *X* with a numeric value indicating the number of characters to keep. Negative numbers are not supported.
**Example**
In this example, `abbreviate` is used to truncate `User.UserAttributes.LastName.[0]` to six (6) characters. The response includes an ellipsis, the dots of which count towards the six-character total.
`{{abbreviate User.UserAttributes.LastName.[0] 6}}` returns
*Ale...* if *Alejandro* is the value of `[0]`.
*capitalize*
Capitalizes each word between white spaces.
**Usage**
`{{capitalize value}}`
**Example**
In this example, initial capitalization is applied to each word for the `Attributes.description.[0]` entry.
`{{capitalize Attributes.description.[0]}}`
If `Attributes.description.[0]` returns
*My First Post*, if the value of `Attributes.description.[0]` is *my first post*.
*capitalizeFirst*
Capitalizes the first character in a value.
**Usage**
`{{capitalizeFirst value}}`
**Example**
In this example, capitalization is applied to the first character of the first word of the `Attributes.description.[0]` entry.
`{{capitalizeFirst Attributes.description.[0]}}` returns
*My first post*, if the value of `Attributes.description.[0]` is *my first post*.
**Example**
*center*
Centers the value in a field of a given width by the number specified. You can optionally pass a character to display for the padding or leave the field blank. If no character is passed a white space is used.
**Usage**
`{{center value size=X [pad=" "}}` , replacing *X* with a numeric value.
If `pad` is kept blank, white space is used as the padding in the response. If you pass a character, that character displays in each space of the padding. Negative numbers are not supported.
**Example**
In this example, the value of `Location.City `is centered with a size of *19*.
`{{center Location.City size=19}}` returns
*" Los Angeles "* If `Location.City` is *Los Angeles*. Note that the quotes displayed in the example output are provided for emphasis only.
*cut*
Removes the specified value from a string.
**Usage**
`{{cut value [" "]}}`, replacing the space within the quotes parameter with the value to cut. If no parameter value is passed, a white space is used.
**Example**
This example removes the letter *e* from the `Location.City` attribute.
`{{cut Location.City "e"}}` returns
*Los Angls* if `[Location.City` is *Los Angeles*.
*dateFormat*
Sets the default date style for the date in any response. For a list of the time zone IDs, see [https://en.wikipedia.org/wiki/List_of_tz_database_time_zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
**Usage**
`{{dateFormat date [inputFormat="format1"] [outputFormat="format2"] [tz=timeZoneId] [locale=localeID]}}`
The `format` parameter must be one of:
+ "`full`": full date format. For example: *Tuesday, September 19, 2020*
+ "`long`": long date format. For example: *September 19, 2020*
+ "`medium`": medium date format. For example: *Sept 19, 2020*
+ "`short`": short date format. For example: *9/19/20*
+ "`pattern`": uses a custom date pattern format. For more information about date patterns, see [https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html).
"`locale`": uses a date format based on a given locale. For more information about locales, see [https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/LocaleUtils.html#toLocale-java.lang.String-](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/LocaleUtils.html#toLocale-java.lang.String-).
If a format is not passed, then `medium` is used by default.
**Example**
In this example, the `[0]` entry for `User.UserAttributes.StartDate.[0]` is **09/19/2020** and a message is sent to a user using the `full` date format based on the *America/Los\$1Angeles* time zone.
`We can meet with you any time on ``{{dateFormat User.UserAttributes.StartDate.[0] inputFormat="MM/dd/yyyy" outputFormat="full" tz=America/Los_Angeles}}.` returns
*We can meet with you any time on Tuesday, September 19, 2020.*
*inflect*
Returns a singular or plural string based on the count value.
**Usage**
`{{inflect count singular plural [includeCount=false]}}`
+ Enter the singular and plural forms of the string you want to pass in the argument.
+ If `includeCount` is set to `false`, no count is returned in the response. If set to `true`, the `count` is included in the response.
**Example**
The following examples show the inflection for a purchase of apples, with and without `includeCount`.
`Thank you for your purchase of {{inflect 3 apple apples includeCount=false}}.` returns:
*Thank you for your purchase of apples.*
If `includeCount` is set to `true`, then the response is
*Thank you for your purchase of 3 apples.*
*join*
Joins an array, iterator, or an iterable object. The response returns a list, with each value in the list concatenated by the character you pass in the `join`. For example, you might separate values using a comma (`,`). The value in this helper must be a list without an attribute position index. For example, this might be `Attributes.custom_attribute`.
**Usage**
`{{join value " // " [prefix=""] [suffix=""]}}`
**Example**
In this example, a list of colors is returned, with the list separated by a comma and a space (`", "`):
`{{join Attributes.favorite_colors ", "}}` returns
*blue, red, green* if `Attributes.favorite_colors` is the list *blue,red,green*.
*ljust*
Justifies the value to the left margin and adds space to the right so that the length of the value matches the number. Negative numbers are not supported.
You can optionally pass a character to display for the `pad` or leave the field blank. If you leave the `pad` value blank, the default value is a white space.
**Usage**
`{{ljust value size=X [pad=" "]}}`, where *X* is the total length of the value, including white space.
**Example**
In this example, a left justification value of *15 *is applied to the Location.City.
`{{ljust Location.City size=15}}` returns
*"Los Angeles "* if the value of `Location.City` is *Los Angeles*. Note that the quotes displayed in the example output are provided for emphasis only.
*lower*
Converts a value to all lower case.
**Usage**
`{{lower value}}`
**Example**
In this example, the `[0]` entry for `User.UserAttributes.LastName.[0]` is changed to lower case.
`{{lower User.UserAttributes.LastName.[0]}}` returns
*santos* if *Santos* is the value of `[0]`.
*now*
Prints out the current date based on the passed time zone ID. For a list of the time zone IDs, see [https://en.wikipedia.org/wiki/List_of_tz_database_time_zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
**Usage**
`{{now ["format"] [tz=timeZoneId] [locale=localeID]}}`
The `format` parameter must be one of:
+ "`full`": full date format. For example: *Tuesday, September 19, 2020*
+ "`long`": long date format. For example: *September 19, 2020*
+ "`medium`": medium date format. For example: Sept 19, 2020
+ "`short`": short date format. For example: 9/19/20
+ "`pattern`": a date pattern. For more information about date patterns, see [https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html).
"`locale`": uses a date format based on a given locale. For more information about locales, see [https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/LocaleUtils.html#toLocale-java.lang.String-](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/LocaleUtils.html#toLocale-java.lang.String-).
If a format is not passed, then `medium` is used by default.
**Example**
In this example, the current date in Los Angeles is returned with a `medium` format.
`{{now "medium" tz=America/Los_Angeles}}` returns
*Sept 19, 2020*.
*ordinalize*
Ordinalizes the numeric value passed in the argument. For example, *1* is ordinalized as *1st* and *2* as *2nd*. Only numeric values are supported.
**Usage**
`{{ordinalize [number]}} `
**Example**
In this example, the `[0]` entry of `User.UserAttributes.UserAge` is ordinalized and returned, along with a message.
`Congratulations on your {{ordinalize User.UserAttributes.UserAge.[0]}} birthday!` returns *22* ordinalized as *22nd*.
*Congratulations on your 22nd birthday\$1*
*replace*
Replaces one string with another string. A string or numeric value must be literal. Wildcard characters are not supported.
**Usage**
`{{replace stringToReplace replacementValue}}`
**Example**
In this example, an underscore (\$1) replaces a white space.
`{{replace Location.City " " "_"}}` returns
*Los\$1Angeles* if the `Location.City `is *Los Angeles*.
*rjust*
Justifies the value to the right margin and adds space to the left so that the length of the value matches the number. Negative numbers are not supported.
You can optionally pass a character to display for the `pad` or keep the field blank. If you keep the `pad` value blank, the default value is a white space.
**Usage**
`{{rjust value size=X [pad=" "]}}`, where *X* is the total length of the value, including white space.
**Example**
In this example, a right justification value of *15* is applied to the `Location.City` attribute.
`{{rjust Location.City size=15}}` returns
*" Los Angeles" *. if the `Location.City` is *Los Angeles*. Note that the quotes displayed in the output are provided for emphasis only.
*slugify*
Converts the passed value to lowercase, removes non-word characters (alphanumeric and underscore), converts spaces to hyphens, and removes any leading or trailing white space.
**Usage**
`{{slugify value}}`
**Example**
In this example, slugify is performed for the `Location.City` attribute.
`{{slugify Location.City}}` returns
*los-angeles* if `Location.City` is *Los Angeles*.
*stripTags*
Strips [X]HTML tags from a value.
**Usage**
`{{stripTags value}}`
**Example**
In this example, the HTML tags for the User.UserAttributes.interest.[0] are removed.
`{{stripTags User.UserAttributes.interests.[0]}}` returns
*Art*, if `User.UserAttributes.interests.[0]` is `
Art
`.
*substring*
Returns a new string as a substring of the passed value. The length and position are determined by the `startOffset` and `endOffset` parameters, which must be integers. Negative numbers are not supported. If an `endOffset` is not passed, the substring uses the original ending value of the string.
**Usage**
`{{substring value startOffset [endOffset]}}`
**Example**
In this example, an offset of 4 and endOffset of 9 are applied to the Location.City attribute.
`{{substring Location.City 4 9}} `returns
`Angel` if Los Angeles is the value of `Location.City` is *Los Angeles*.
*upper*
Converts the passed value to upper case.
**Usage**
`{{upper value}}`
**Example**
In this example, the `[0] `entry for the `User.UserAttributes.LastName` attribute is converted to all upper case.
`{{upper User.UserAttributes.LastName.[0]}}`returns
*ROE* if the `User.UserAttributes.LastName.[0]` value is *Roe*.
*yesno*
Replaces `true`, `false`, and `NULL` with `Yes`, `No`, and `Maybe`.
**Usage**
`{{yesno value [yes="yes"] [no="no"] maybe=["maybe"]}}`
**Example**
In this example, the `IsUserSubscribed` attribute returns whether a user is subscribed to a particular list.
`{{yesno Attributes.IsUserSubscribed}}` returns
*yes* if `Attributes.IsUserSubscribed` is *true*.
## Math and encoding helpers
This section describes the **math and encoding** helpers.
+ `add` – Returns the sum of two numbers.
+ `ceiling` – Rounds an integer to its mathematical ceiling.
+ `decode64` – Decodes a base64 encoded value to a string.
+ `divide` – Returns the quotient of two numbers.
+ `encode64` – Encodes a string using base64.
+ `floor` – Rounds an integer to its mathematical floor.
+ `md5` – Hashes a passed string using the MD5 algorithm.
+ `modulo` – Returns the remainder of two numbers using floating points.
+ `multiply` – Returns the product of two numbers.
+ `round` – Rounds a decimal to the nearest whole number.
+ `sha256` – Hashes a passed string using SHA-256.
+ `sha512` – Hashes a passed string using SHA-512.
+ `subtract` – Returns the difference of two numbers.
+ `uuid` – Randomly generates a UUID in a 128-bit format.
*add*
Returns the sum of two numbers along with floating points.
**Usage**
`{{add arg1 arg2}}`
**Example**
`{{add 5 2.3}} `returns
*7.3*
*ceiling*
Rounds an integer to its mathematical ceiling, which is the highest whole number closest to the passed value.
**Usage**
`{{ceiling value}}`
**Example**
`{{ceiling 5.23}}` returns
*6*
*decode64*
Decodes a base64 encoded value to a string.
**Usage**
`{{decode64 "string"}}`
**Example**
`{{decode64 "SGVsbG8gd29ybGQ="}}` returns
*Hello World*
*divide*
Returns the quotient of two numbers, including floating points.
**Usage**
`{{divide arg1 arg2}}`
**Example**
`{{divide 5 2.3}}` returns
*2.17391304*
*encode64*
Encodes the string passed in the argument using base64.
**Usage**
`{{encode64 "string"}}`
**Example**
`{{encode64 "Hello World"}}`
*SGVsbG8gd29ybGQ=*
*floor*
Rounds an integer to its mathematical floor, which is the lowest whole number closest to the passed value.
**Usage**
`{{floor value}}`
**Example**
`{{floor 5.23}}` returns
*5*
*md5*
Hashes a passed string using the MD5 algorithm.
**Usage**
`{{md5 "string"}}`
**Example**
`{{md5 "Hello World"}}`
*3e25960a79dbc69b674cd4ec67a72c62*
*modulo*
Returns the remainder of two numbers using floating points.
**Usage**
`{{modulo arg1 arg2}}`
**Example**
`{{modulo 7 2}}` returns
*1*
*multiply*
Returns the product of two numbers, with any floating points.
**Usage**
`{{multiply arg1 arg2}}`
**Example**
`{{multiply 5 2.3}}` returns
*11.5*
*round*
Rounds a decimal place up or down to the nearest whole number.
**Usage**
`{{round value}}`
**Example**
`You spent an average of {{round 19.21}} minutes on our website each day.` returns:
*You spent an average of 19 minutes on our website each day.*
*sha256*
Hashes a passed string using SHA-256 cryptographic security.
**Usage**
`{{sha256 "string"}}`
**Example**
`{{sha256 "Hello World"}}` returns
*a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e*
*sha512*
Hashes a passed string using SHA-512 cryptographic security.
**Usage**
`{{sha512 "string"}}`
**Example**
`{{sha512 "Hello World"}}` returns
*2c74fd17edafd80e8447b0d46741ee243b7eb74dd2149a0ab1b9246fb30382f27e853d8585719e0e67cbda0daa8f51671064615d645ae27acb15bfb1447f459b*
*subtract*
Returns the difference of two numbers, with any floating points.
**Usage**
`{{subtract arg1 arg2}}`
**Example**
`{{subtract 5 2.3}} ` returns
*2.7*
*uuid*
Randomly generates a UUID in a standard 128-bit format. No value needs to be passed in the argument.
**Usage**
`{{uuid}}`
**Example**
`{{uuid}} ` returns
**95f36680-152c-4052-99ec-cc3cdf7ca594**
## Inline partials
While technically not a helper, inline partials are Handlebars way to streamline templates that include repeated strings, which is better for reuse. For more information, see [Inline partials](https://handlebarsjs.com/guide/partials.html#inline-partials) at [handlebarsjs.com](https://handlebarsjs.com).
**Usage**
`{{#* inline "inlineName"}}Content to reuse{{/inline}}`
To reference the content of the inline partial elsewhere, use:
` {{> inlineName}}`
**Example**
The following example creates an inline partial that includes the recipient's first name, and, if it's available, last name, by adding the following code to the beginning of the template:
`{{#* inline "fullName"}}`
`{{User.UserAttributes.FirstName.[0]}} {{#if User.UserAttributes.LastName.[0]}} {{User.UserAttributes.LastName.[0]}} {{/if}}`
`{{/inline}}`
After creating the `fullName` partial, you can include it anywhere in your template by preceding the name of the partial with a `>` (greater than) symbol, followed by a space, as in the following example: `{{> fullName}}`.
*` Hello {{> fullName}}`*
returns the user's first and last name if true – for example, *Hello Jane Doe*. Otherwise, if no last name is found, *Hello Jane* is returned.
Handlebars include additional features beyond those documented here. For more information, see [handlebarsjs.com](https://handlebarsjs.com/).
## Use variables with message template helpers
Amazon Connect custom attribute names support spaces. To have a custom attribute named `"Last Name"`, you must format the attribute as `Attributes.[Last Name]`.
## Use nested helpers
You can nest multiple message template helpers within each other. The following example shows how to format two helpers: `{{ first helper (second helper)}}`. The second helper is processed first, followed by the first helper. Remember that the first helper always determines the output. Subsequent helpers must be nested within the previous helper as follows: `{{ first helper (second helper (third helper) )}}`.
The following example shows how to nest two helpers to change **JANE** to **Jane**: `{{capitalizeFirst (lower "JANE")}}`. `lower` first converts **JANE** to **jane**. Then `capitalizeFirst` converts **jane** to **Jane**.
# Security profiles do not affect agent authorization for viewing an email thread
Security profiles do not affect viewing an email thread
Any user with the following permission in their security profile has access to read emails that they handle or emails that are part of a thread where they are a participant: **Contact Control Panel (CCP)** - **Access Contact Control Panel** - **Access**.
![\[The Access Contact Control Panel option on the Security profiles page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/access-ccp-perm.png)
This authorization behavior is enabled by default. It does not require setting up any additional permission or configuration.
This behavior is driven by the following context keys:
1. `connect:UserArn`: Represents the user that has access to an individual contact.
1. `connect:ContactAssociationId`: Represents the contact association the user has access to. For the email channel, a contact association always represents an email thread.
1. `connect:Channel`: Represents the contact channel the user has access to. For the email channel, this contextKey is always `EMAIL`.
We don't recommend using `connect:ContactAssociationId` in the same policy as `connect:UserArn` because it might result in a no-op. Because the `connect:UserArn` condition key is more restrictive, it will `Deny` access for all contacts not handled by the corresponding user, regardless of the access they have to email threads.
You can use `connect:Channel` in isolation to restrict access to specific channels. Accepted values are: `VOICE`, `CHAT`, `TASK`, or `EMAIL`. See the [Contact](https://docs.aws.amazon.com/connect/latest/APIReference/API_Contact.html) API.
Following are the contact-related APIs that support these context keys:
1. [DescribeContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeContact.html)
1. [UpdateContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateContact.html)
1. [ListContactReferences](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListContactReferences.html)
1. [TagContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_TagContact.html)
1. [UntagContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_UntagContact.html)
1. [UpdateContactRoutingData](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateContactRoutingData.html)
1. [GetContactAttributes](https://docs.aws.amazon.com/connect/latest/APIReference/API_GetContactAttributes.html)
1. [UpdateContactAttributes](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateContactAttributes.html)
1. [StopContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StopContact.html)
1. [StartContactRecording](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactRecording.html)
1. [StopContactRecording](https://docs.aws.amazon.com/connect/latest/APIReference/API_StopContactRecording.html)
1. [ResumeContactRecording](https://docs.aws.amazon.com/connect/latest/APIReference/API_ResumeContactRecording.html)
1. [SuspendContactRecording](https://docs.aws.amazon.com/connect/latest/APIReference/API_SuspendContactRecording.html)
1. [UpdateContactSchedule](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateContactSchedule.html)
1. [TransferContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_TransferContact.html)
1. [StartScreenSharing](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartScreenSharing.html)
# Create quick responses for use with chat and email contacts in Amazon Connect
Create quick responses
Quick responses provide contact center agents with pre-written responses in English that they can use during chat and email contacts. Quick responses are especially useful for answering common customer inquiries. They help improve agent productivity, reduce handle times, and improve customer satisfaction scores. Quick responses are available in English only.
You can use the Amazon Connect admin website or [Connect AI agents actions](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_Operations.html) to create quick responses. You can add single quick responses or import many of them at the same time. You can also personalize responses with [user-defined attributes](add-attributes.md). In addition, you can assign shortcut keys to quick responses, and associate them with [routing profiles](https://docs.aws.amazon.com/connect/latest/adminguide/about-routing.html) so that agents can quickly access relevant content.
By default, CCP enables agents to search quick responses. Custom builders can use [Amazon Connect Streams](https://github.com/aws/amazon-connect-streams) to programmatically implement quick response search in their implementations of CCP.
For information about how agents search for quick responses, see [Search for quick responses to customers in the Contact Control Panel (CCP)](search-qr-ccp.md).
**Tip**
Even though quick responses use the Connect AI agents APIs, quick responses don't lead to additional billing. You only pay for the chat message price or email price. For more information, see [Amazon Connect Pricing](https://aws.amazon.com/connect/pricing/).
**Topics**
+ [Assign security profile permissions](quick-response-permissions.md)
+ [Set up an Amazon Connect knowledge base](setup-knowledgebase.md)
+ [Add quick responses for use with chat and email contacts](quick-responses.md)
+ [Add attributes for personalizing quick responses](add-attributes.md)
+ [Edit quick responses](edit-quick-responses.md)
+ [Delete quick responses in Amazon Connect](delete-qr.md)
+ [Import quick responses](add-data.md)
+ [View the import history for your quick responses](view-import-history.md)
+ [Enable quick responses in a custom CCP](enable-qr-search.md)
# Assign permissions to manage quick responses in Amazon Connect
Assign security profile permissions
To create and manage quick responses in the Amazon Connect admin website, users need the Content Management security profile permissions. The following image shows these permissions on the **Security profiles** page.
![\[The various quick response permissions, all with green check marks.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/content-mgmt-qr.png)
Following is a description of the Content Management permissions.
+ **All** – Enables all permissions, but you must have a custom view to enable **Access**.
+ **Access** – Grants users access to custom views. This checkbox remains unavailable until you create a custom view.
+ **Create** – Enables users to create Connect AI agents knowledge bases and quick responses in the Amazon Connect admin website. This setting also enables users to View and Edit. It does not grant permission to delete quick responses.
+ **View** – Enables users to view quick responses in the Amazon Connect admin website.
+ **Edit** – Enables users to edit quick responses in the Amazon Connect admin website.
+ **Delete** – Enables users to delete quick responses in the Amazon Connect admin website.
If you want the same users to add personalized attributes to quick responses, they will also need the **Channels and flows**, **Flows - Publish** permission.
For information about adding permissions to an existing security profile, see [Update security profiles in Amazon Connect](update-security-profiles.md).
# Set up an Amazon Connect knowledge base to store quick responses
Set up an Amazon Connect knowledge base
You must create an [Amazon Connect knowledge base](connect-ai-agent.md) to store quick responses. You can use the Amazon Connect admin website to create the knowledge base with a single click. The site uses AWS owned keys to encrypt data.
**Note**
You can create your own key by providing a custom [ ServerSideEncryptionConfiguration](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_ServerSideEncryptionConfiguration.html#wisdom-Type-ServerSideEncryptionConfiguration-kmsKeyId) in an [CreateKnowledgeBase](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_CreateKnowledgeBase.html) API call. For more information, see [Initial set-up for AI agents](ai-agent-initial-setup.md), in this guide.
The following steps explain how to use the Amazon Connect admin website to create an Amazon Connect knowledge base.
**To create a knowledge base**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an admin account, or an account with **Content Management - Quick responses - Create** permission in its security profile.
1. On the navigation bar, choose **Content Management**, then **Quick responses**.
1. On the **Quick responses** page, choose **Get started**.
**Note**
If the **Get started** button isn't available, sign in with an account that has the admin security profile, or ask another admin for help.
1. Remain on the page until the process ends. Do not refresh the page until the process ends. An indicator shows the status.
![\[A horizontal green status bar.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-application-3.png)
The finished knowledge base provides two sample quick responses.
+ The sample responses are associated with the [basic routing profile](https://docs.aws.amazon.com/connect/latest/adminguide/concepts-routing.html), if that exists in your Amazon Connect instance.
+ The sample responses are set to **Inactive**, meaning agents can't see or search for them. Activating a sample quick response makes it visible and searchable by agents assigned to the basic routing profile.
+ If the basic routing profile is not present in your Amazon Connect instance, the sample quick responses are associated with **All** routing profiles. After you activate a sample quick response, all agents can see and search for that response, regardless of their assigned routing profiles.
**Note**
Quick responses are only available in the **Chat** and **Email** channels.
# Add quick responses for use with chat and email contacts in Amazon Connect
Add quick responses for use with chat and email contacts
This topic explains how to add a quick response by using the Amazon Connect admin website. For the APIs used to create and manage quick responses programmatically, see [APIs to create and manage quick responses](#apis-quick-responses).
**To add responses**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Content Management - Quick responses - Create** permission.
1. On the navigation bar, choose **Content Management**, then **Quick responses**.
![\[Menu showing "Content Management" and "Quick responses."\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-application-1.png)
1. On the **Quick responses** page, choose **Add response**.
**Note**
If the **Add response** button isn't available, sign in with an account that has the admin security profile, or ask another admin for help.
1. On the **Add response** page, choose whether the response is for chat, email, or both channels.
1. On the **Add response** page, enter a name, description, and shortcut key for the quick response. You must enter a unique name and shortcut key because agents will search on those values.
1. Open the **Routing profiles** list and select one or more profiles. You can select a maximum of 20 profiles, or choose **All**. Only the agents assigned to a given profile can see the quick responses associated with that profile.
1. (Optional) Choose **Activate: Make this response visible for agents** if you want agents to see and search for the response.
1. In the **Content** section, enter the response, then choose **Save**.
**Note**
If you configured user-defined attributes in the flow block, those attributes, such as customer name, appear when an [agent searches for a response in CCP](search-qr-ccp.md). For more information, see [Set contact attributes](set-contact-attributes.md).
## APIs to create and manage quick responses
APIs to create and manage quick responses
Use the following APIs to create and manage quick responses programmatically:
+ [CreateQuickResponse](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_CreateQuickResponse.html)
+ [UpdateQuickResponse](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_UpdateQuickResponse.html)
+ [DeleteQuickResponse](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_DeleteQuickResponse.html)
+ [GetQuickResponse](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_GetQuickResponse.html)
+ [ListQuickResponses](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListQuickResponses.html)
+ [SearchQuickResponses](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_SearchQuickResponses.html)
+ [UpdateQuickResponse](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_UpdateQuickResponse.html)
# Add attributes for personalizing quick responses in Amazon Connect
Add attributes for personalizing quick responses
You can personalize quick responses by adding user-defined attributes. To do so, you use the Amazon Connect admin website to create responses that include [Amazon Connect contact attributes](https://docs.aws.amazon.com/connect/latest/adminguide/connect-contact-attributes.html). You can also use the [Set contact attributes](set-contact-attributes.md) block to create user-defined attributes in flows.
When quick responses contain user-defined attributes, the value of those attributes, such as customer name, appear when an [agent searches for a response in CCP](search-qr-ccp.md).
The following steps explain how to add user-defined attributes to quick responses. You first create a set-contact attribute, and then you add the attribute to a quick response.
**To create a set-contact attribute**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Flows - Edit or Create** permissions.
1. On the navigation bar, choose **Routing**, then **Flows**.
![\[Menu showing "Routing" and "Flows".\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/routing-flows.png)
1. On the **Flows** page, the **Type** column lists each type of flow. Choose the flow that you want to add attributes to.
1. Follow the steps in [Creating a set contact attribute](set-contact-attributes.md).
**Note**
In the contact attribute configuration, select the **User defined** namespace, then save and publish the flow.
1. When finished, complete the next set of steps.
You can follow these steps when creating or updating a quick response.
**To add an attribute to a quick response**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Content Management - Quick responses - Create or Edit** permission.
1. On the left navigation bar, choose **Content Management**, then **Quick responses**.
![\[Menu showing "Content Management" and "Quick responses."\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-application-1.png)
1. Choose **Add response** to create a response.
—or—
Select the checkbox next to the quick response that you want to personalize, then choose **Edit**.
1. Choose the content section, enter the quick response content, then use handlebar syntax to enter a user-defined attribute. Make sure you include the `Attributes` namespace prefix. For example, **\$1\$1Attributes.Customer\$1\$1**.
The following image shows a quick response for an email.
![\[A quick response with an attribute for the customer name.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/email-quick-response-attributes.png)
1. Choose **Save**.
The following steps explain how to test attributes in CCP.
**To test attributes**
1. Log in to the Amazon Connect admin website chat testing page at https://*instance name*.my.connect.aws/test-chat.
1. Choose the flow with the user-defined attribute.
1. Start a chat and enter **/\$1*searchText***, where *searchText* is the assigned shortcut key.
**Note**
For more information, see [Test voice, chat, and task experiences in Amazon Connect](chat-testing.md).
# Edit quick responses in Amazon Connect
Edit quick responses
This topic explains how to use the Amazon Connect admin website to edit a quick response. To edit a quick response programmatically, see [UpdateQuickResponse](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_UpdateQuickResponse.html) in the *Connect AI agents API Reference*.
**To edit a response**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Content Management - Quick responses - Edit** permission.
1. On the navigation bar, choose **Content Management**, then **Quick responses**.
![\[Menu showing "Content Management" and "Quick responses."\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-application-1.png)
1. On the **Quick responses** page, choose the name of the quick response that you want to edit. You can also select the checkbox next to the response, then choose **Edit**.
1. As needed, change the following fields:
+ **Name**
+ **Description**
+ **Shortcut key**
+ **Routing Profiles**
+ **Activate/Deactivate quick response**
+ **Content**
+ **Channel**
1. Choose **Save**.
# Delete quick responses in Amazon Connect
Delete quick responses in Amazon Connect
This topic explains how to use the Amazon Connect admin website to delete a quick response. To delete a quick response programmatically, see [DeleteQuickResponse](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_DeleteQuickResponse.html) in the *Connect AI agents API Reference Guide*.
**Important**
You can't undo a deletion.
Agents can't see or use deleted quick responses.
**To delete a response**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Content Management - Quick responses - Delete** permission.
1. On the navigation bar, choose **Content Management**, then **Quick responses**.
![\[Menu showing "Content Management" and "Quick responses."\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-application-1.png)
1. On the **Quick responses** page, select the checkbox next to the response that you want to delete. You can select a maximum of 20 responses.
1. Choose **Delete**.
A success message appears:
![\[A green checkmark and the words "Successfully Deleted selected Quick response."\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/deletion-success-message.png)
**Note**
If the **Delete** button is inactive, sign in to an Amazon Connect an account that has the required security profile, or ask another admin for help.
Remain on the page until the delete operation finishes.
# Import quick responses to Amazon Connect
Import quick responses
You can import a maximum of 100 quick responses at a time from a .csv file. This topic explains how to use the Amazon Connect admin website to import quick responses. To import quick responses programmatically, see [StartImportJob](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_StartImportJob.html) in the *Connect AI agents API Reference*.
**To import responses**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Content Management - Quick responses - Create** permission.
1. On the navigation bar, choose **Content Management**, then **Quick responses**.
![\[Menu showing "Content Management" and "Quick responses."\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-application-1.png)
1. On the **Quick responses** page, choose **Import**.
1. In the **Import** dialog box, choose the **Responses Import Template.csv** link, then save the resulting **Response Import Template.csv** file to your desktop. The file opens in Microsoft Excel or a similar spreadsheet program.
1. In the .csv file, enter values in each column. Remember the following:
+ The **Name** and **Shortcut key** values must be unique across all the quick responses in your Amazon Connect instance.
+ Values in the **Routing Profile** column are case sensitive and must match the name of your routing profile exactly.
+ Do not rename or change the values in the first row of the .csv file. Those header keys are reserved and used to generate payloads for the [CreateQuickResponse](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_CreateQuickResponse.html) API.
+ Remove all instances of **<\$1Required field>** from the .csv file. They're only for information.
1. Save the .csv file, return to the Amazon Connect admin website, and in the **Import** dialog box, choose **Upload file**.
1. Locate and open the .csv file, then choose **Import**.
Success or failure messages appear when the import operation finishes. If the operation fails, choose the **Download failed imports link** in the message. Check the .csv file for leading or trailing spaces, and for any messages about the error.
You can navigate away from the **Quick response** page before the import job finishes. Choose the **View import history** link, located below the list of responses, to view status of your import jobs.
# View the import history for your Amazon Connect quick responses
View the import history for your quick responses
Amazon Connect retains import history for the lifetime of your knowledge base. To delete that history, you must use the [DeleteKnowledgeBase](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_DeleteKnowledgeBase.html) action to delete the knowledge base.
This topic explains how to use the Amazon Connect admin website to view import histories. To view import histories programmatically, see [ListImportJobs](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_ListImportJobs.html) in the *Connect AI agents API Reference*.
**To view import history**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Content Management - Quick responses - View** permission.
1. On the left navigation bar, choose **Content Management**, then **Quick responses**.
![\[Menu showing "Content Management" and "Quick responses."\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-application-1.png)
1. On the **Quick responses** page, choose the **View import** history link.
# Enable Amazon Connect quick responses in a custom Contact Control Panel (CCP)
Enable quick responses in a custom CCP
To enable your agents to use quick responses for an embedded or custom CCP, you use the [ Amazon Connect Streams library](https://github.com/amazon-connect/amazon-connect-streams) on GitHub to call the [SearchQuickResponse](https://docs.aws.amazon.com/amazon-q-connect/latest/APIReference/API_SearchQuickResponses.html) API and return a list of quick response search results to CCP. For more information, see [Amazon Connect Streams Documentation](https://github.com/amazon-connect/amazon-connect-streams/blob/master/Documentation.md#quick-responses-apis) on Github.
**Note**
To prevent search API misuse, we implemented default values for the following request parameters:
`debounceTime` – 250ms between subsequent `SearchQuickResponse` API calls
`maxSearchResults` – 25
Search priority order:
`shortcut key`
`name`
`content`
`description`
For information about the agent's experience using quick responses, see [Search for quick responses to customers](search-qr-ccp.md).
# Set up outbound calling in Amazon Connect
Set up outbound calling
You can send outbound calls to customers for a variety of reasons, such as appointment reminders, subscription renewals, and debt collection. Amazon Connect provides both normal and outbound campaign capabilities. For more information about campaigns, see [Set up Amazon Connect outbound campaigns](enable-outbound-campaigns.md) in this guide.
**Topics**
+ [Set up outbound caller ID](queues-callerid.md)
+ [Set up US emergency calling](setup-us-emergency-calling.md)
+ [Enable outbound calls](enable-outbound-calls.md)
+ [Outbound calling restrictions](outbound-calling-restrictions.md)
+ [Optimize your reputation for outbound calling](optimize-outbound-calling.md)
# Set up outbound caller ID in Amazon Connect
Set up outbound caller ID
This topic explains how to set up your outbound caller ID name and number.
**Topics**
+ [
## Outbound parameters: Set in queue
](#set-callerID-name)
+ [How outbound parameters are selected](#how-outbound-parameters-selected)
+ [
## How to set the caller ID number dynamically
](#using-dynamic-caller-id)
+ [
## Use E.164 format for international phone numbers
](#international-calls-ccp)
+ [
## How to specify a custom caller ID number using a [Call phone number](call-phone-number.md) block
](#call-number-block-how-it-works)
+ [CNAM](#CNAM)
+ [Avoid labels like "spam"](#enroll-in-CNAM-services)
## Outbound parameters: Set in queue
You set the outbound caller ID name (such as the name of your company) and caller ID number in the queue settings. To edit queue settings, on the navigation menu choose **Routing**, **Queues**, and then choose the queue you want to edit.
The following image shows an **Edit queue** page with an arrow pointing to the **Outbound caller ID name** and **Outbound caller ID number**.
![\[The Edit queue page, the Outbound caller ID name and number boxes.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/set-callerID-callerName.png)
### Outbound caller ID name
The **Outbound caller ID name** is set to the value that is passed from the SIP header. For example, `Alice`.
**Important**
Per SIP protocol RFC3261, the following characters are reserved: **; / ? : @ & = \$1 \$1 ,**. Do not use these characters in the caller ID name. When these characters are included, outbound calls may fail or the caller ID name may display inaccurately.
Amazon Connect runs on a SIP-only infrastructure through our carrier partners. However, the caller ID name can be delivered to your customers only if the call path across the public telephony network is all on SIP. Because your customers are on many different networks outside of what Amazon Connect controls, the caller ID name is not guaranteed to be delivered to your customers. Depending on the country this will be up to 75% effective.
To guarantee your caller ID name is delivered to customers, see [Optimize your reputation for outbound calling in Amazon Connect](optimize-outbound-calling.md) for information about achieving it by using partner solutions.
### Outbound caller ID number
Only phone numbers that you've [claimed](get-connect-number.md) or [ported to Amazon Connect](port-phone-number.md) can be used as your caller ID number. Outbound calls without proper identification may be blocked in certain countries such as UK and Australia.
To use an external phone number as your outbound caller ID number, contact Support to see if it's possible. The phone number needs to be in a [ country we support](https://d1v2gagwb6hfe1.cloudfront.net/Amazon_Connect_Telecoms_Coverage.pdf) for custom caller ID and you'll need to provide [proof of ownership](phone-number-requirements.md).
1. Choose [Account and billing](https://console.aws.amazon.com/support/home#/case/create?issueType=customer-service&serviceCode=service-connect-number-management) to access a pre-populated form in the Support console. You must be signed in to your AWS account to access the form.
1. For **Service**, *Connect (Number Management)* should be selected.
1. For **Category**, *Custom Outbound Called ID* should be selected.
1. Select the required severity.
1. Choose **Next step: Additional information**
1. On the **Additional information** page:
1. Enter the subject.
1. Under **Description**, include as much information as possible about your request. If you don't know all of these details, you can leave information out.
**Important**
Do not attach any documents that contain personal information. After we review your case, we'll send you a link to our secured storage (Amazon S3) so you can submit the required documents. This is described later in step 10 below.
1. Choose **Next step: Solve now or contact us**.
1. On the **Solve now or contact us** page:
1. Choose the **Contact us** tab and select your **Preferred contact language** and your preferred contact method.
1. Choose **Submit**.
1. The Amazon Connect team will review your ticket and get back to you. They will provide a link to our secured storage (Amazon S3) so you can submit required documents.
You can set the caller ID number as follows:
+ **[Call phone number](call-phone-number.md) block**: Use this block in an [Outbound whisper flow](create-contact-flow.md#contact-flow-types) to initiate an outbound call to a customer and, optionally, specify a custom caller ID number that is displayed to call recipients.
This block is useful when you have multiple telephone numbers used to make outbound calls, but want to consistently display the same company phone number for the caller ID for calls made from your contact center.
You can also use this block with the [Set contact attributes](set-contact-attributes.md) block to set the callback number dynamically. For example, you can display a certain caller ID number based on the customer's account type.
+ **Queue:** If no caller ID number is specified in the [Call phone number](call-phone-number.md) block, then the caller ID in the queue settings is used.
**Important**
Telecom regulations in various countries limit the telephone numbers that you can use to make outbound calls. If you set up a number and you can't make outbound calls, check the [Amazon Connect Telecoms Country Coverage Guide](https://d1v2gagwb6hfe1.cloudfront.net/Amazon_Connect_Telecoms_Coverage.pdf) and [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md) to ensure that you have correct type of number.
Telecom regulations in certain countries require the carrier to identify the caller and block unidentifiable outbound calls. Make sure you set the Caller ID in your configurations to avoid call failures.
For example:
**In Australia**: The caller ID must be an Amazon Connect provided DID (Direct Inward Dialing) phone number. If a toll free number or a number not provided by Amazon Connect is used in the caller ID, local telephony suppliers may reject outbound calls due to local anti-fraud requirements.
**In the UK**: The caller ID must be a valid E164 phone number. If the phone number is not provided in the caller ID, local telephony suppliers may reject outbound calls due to local anti-fraud requirements.
### Anonymous caller ID
Anonymous caller ID
Anonymous calls (calls without caller ID) will be blocked by most carriers and may fail to connect.
**Why anonymous calls fail:**
+ Most phone carriers now block anonymous calls as anti-spam measures.
+ Many countries prohibit anonymous calls through regulation.
+ Call success rates are unpredictable and unreliable.
**Prevention:** Always configure a valid phone number in the **Outbound caller ID** number field for every queue used for outbound calling. Use only numbers you've claimed or ported to Amazon Connect.
### Toll-free numbers for caller ID
Toll-free numbers for caller ID
Toll-free numbers for outbound communications have a number of limitations. For example, using a toll-free number to dial other toll-free numbers in the United States can result in the number being filtered, blocked, or not properly routed to the destination by carriers. Toll-free numbers may be terminated at a higher than expected rate. If you know you need to call toll-free numbers in the United States you must use DIDs to guarantee call delivery.
If you use toll-free numbers outside of the US, refer to the [Amazon Connect Telecoms Country Coverage Guide](https://d1v2gagwb6hfe1.cloudfront.net/Amazon_Connect_Telecoms_Coverage.pdf) to see which countries support toll-free numbers as outbound. For example, for Australia the **National Outbound** column indicates that toll-free numbers are not supported.
**Important**
Toll-free products are designed to be national products and used within a country. We do not guarantee international reachability of any of these services, as access to the numbers is controlled by a caller's network access.
## How outbound parameters are selected
How outbound parameters are selected
If the call is placed with an external quick connect or quick connect number pad, the outbound caller ID and caller name depends on if the agent is on an active call or not.
+ If the agent is on an active call, the original queue that the call is serviced from provides the outbound caller ID and caller name.
+ If the agent isn't on an active call, the outbound queue of the agent's [routing profile](routing-profiles.md) provides the outbound caller ID and caller name.
**Note**
You can override the outbound caller IDs in your agents' routing profiles by using the [Call phone number](call-phone-number.md) block in a [custom outbound whisper flow](https://repost.aws/knowledge-center/connect-custom-outbound-whisper-flows).
## How to set the caller ID number dynamically
Use an attribute in the [Call phone number](call-phone-number.md) block to set the caller ID number dynamically during the flow.
The attribute can be one you define in the [Set contact attributes](set-contact-attributes.md) block in the flow. Or, it can be an external attribute returned from an AWS Lambda function.
The value of the attribute must be a phone number from your instance in [ E.164](https://www.itu.int/rec/T-REC-E.164/en) format.
+ If the number is not in E.164 format, the number from the queue associated with the [Outbound whisper flow](create-contact-flow.md#contact-flow-types) is used for the caller ID number.
+ If no number is set for the outbound caller ID number for the queue, the call attempt will fail.
For more information about setting the caller ID dynamically, see this AWS Support Knowledge Center article: [How can I set my Amazon Connect outbound caller ID dynamically based on country?](https://aws.amazon.com/premiumsupport/knowledge-center/connect-dynamic-outbound-caller-id/)
## Use E.164 format for international phone numbers
Amazon Connect requires phone numbers in [E.164](https://www.itu.int/rec/T-REC-E.164/en) format.
To express a US phone number in E.164 format, add the '\$1' prefix and the country code in front of the number. For example, for a US number:
+ \$11-800-555-1212
In the UK and many other countries internationally, local dialing requires the addition of a 0 in front of the subscriber number. However, to use E.164 formatting, this 0 must be removed. A number such as 020 718 xxxxx in the UK would be formatted as \$144 20 718 xxxxx. When you place calls from the CCP using Amazon Connect the CCP provides the correct formatting for numbers automatically.
**Important**
Phone numbers must be formatted in E.164 or they will not work. They will also result in a breach of [Amazon Connect Service Terms and conditions](https://aws.amazon.com/service-terms/) for acceptable use which may result in your service being suspended.
## How to specify a custom caller ID number using a [Call phone number](call-phone-number.md) block
1. On the left navigation menu, choose **Routing**, **Flows**.
1. Choose the down arrow next to **Create flow**, and then choose **Create outbound whisper flow**.
1. Add a [Call phone number](call-phone-number.md) block to the flow, and connect the **Entry point** block to it.
The [Call phone number](call-phone-number.md) block must be placed before a **Play prompt** block if one is included in your flow.
1. Select the [Call phone number](call-phone-number.md) block, and then select **Caller ID number to display**.
1. Do one of the following:
+ To use a number from your instance, choose **Select a number from your instance**, and then search for or select the number to use from the drop-down.
+ Choose **Use attribute** to use a contact attribute to provide the value for the caller ID number. You can use either a **User Defined** attribute you create using a [Set contact attributes](set-contact-attributes.md) block, or an **External** attribute returned from an AWS Lambda function. The value of any attribute you use must be a phone number claimed for your instance and be in E.164 format. If the number used from an attribute is not in E.164 format, the number set for the **Outbound caller ID number** for the queue is used.
**Important**
The value of any attribute you use must be a phone number claimed for your instance. The number must be in E.164 format. If the number used from an attribute is not in E.164 format, calls may be terminated by the destination networks.
It is your responsibility to ensure the numbers you are using are legally permissible. Certain numbers, such as \$144870 numbers in the UK, are not legally permissible. You must ensure you're not using them.
1. Add any additional blocks to complete your flow, and connect the **Success** branch of the [Call phone number](call-phone-number.md) block to the next block in the flow.
There is no error branch for the block. If a call is not successfully initiated, the flow ends and the agent is placed in an **AfterContactWork** (ACW) state.
## CNAM
CNAM
As part of changes within the US Public Telephone network and a move to alternative reputation mechanisms described in [Optimize your reputation for outbound calling in Amazon Connect](optimize-outbound-calling.md), as of March 31, 2023, Amazon Connect no longer sets CNAM configurations.
We conducted research between January and March 2023, that showed CNAM was seen by fewer than 7% of users. This is due to changes within support for mobile providers and due to the migration to app-based reputation mechanisms.
All existing CNAM configurations set up before March 2023, are still in place. We will continue to focus on supporting modern replacement mechanisms added to our marketplace, for example, [First Orion](https://firstorion.com/amazon-connect-integration/) and Neustar.
## How to avoid labels like "spam" and "telemarketer"
Avoid labels like "spam"
See the recommended steps in [Optimize your reputation for outbound calling in Amazon Connect](optimize-outbound-calling.md).
# Set up US emergency calling in Amazon Connect
Set up US emergency calling
By default 911 is enabled for all users in the following North America Regions: US East (N. Virginia), US West (Oregon), and AWS GovCloud (US-West). If a user calls 911, the call is routed through to emergency services.
Amazon Connect only supports direct calls from the agent CCP to 911. It does not support call transfers to 911, or dialing 911 while on a call.
**What is Enhanced 911 (E911)?** For agents who are physically located in the US, E911 enables location information to be sent to 911 dispatch when a 911 call is placed.
There are two steps to set up E911:
+ [Get and store an agent's validated physical address in your Amazon Connect instance](get-and-store-agent-address-e911.md)
+ [Retrieve an agent's address from Amazon Connect when they call 911](retrieve-agent-address-e911.md)
## Place 911 calls from your Test Environment
Place 911 calls from your Test Environment
**Important**
Calling 911 for a non-emergency situation carries a penalty of \$1100 per occurrence. To help you avoid penalties, we have set up 933 so you can test this capability. Calls placed from an Amazon Connect Contact Control Panel (CCP) to 933 have an audio playback message confirming:
The number the call originated from.
The physical address that was sent along with the call.
For more information about calling 911, see this [FAQ](https://www.911.gov/calling-911/frequently-asked-questions/) about the national 911 program.
# Get and store an agent's validated physical address in your Amazon Connect instance
Get and store an agent's validated physical address
The first step in setting up E911 for your Amazon Connect instance is to get and store the agent's validated physical address. The following illustration shows the process for storing addresses.
![\[Amazon Connect E911 address storage process.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/e911-workflow.png)
1. Since agents may be working from different locations (for example, office building, home, or coffee shop), it's critical that the most recently validated address is passed along with the emergency outbound call.
1. Store a validated address when you first set up an agent on Amazon Connect, based on the agent's usual location.
1. Prompt the agent to update their address at the start of their shift to help ensure that the emergency outbound call has their latest address.
1. Check addresses against a database of valid street addresses (Master Street Address Guide).
1. Use the Amazon Chime API [ValidateE911Address](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_ValidateE911Address.html). This API validates and returns the validated physical address.
1. Use the [CreateProfile](https://docs.aws.amazon.com/customerprofiles/latest/APIReference/API_CreateProfile.html) or [UpdateProfile](https://docs.aws.amazon.com/customerprofiles/latest/APIReference/API_UpdateProfile.html) APIs to store the validated address in Amazon Connect Customer Profiles.
**Note**
We recommend using `CreateProfile` when it is required to add a validated address the first time. After that, use `UpdateProfile`.
# Retrieve an agent's address from Amazon Connect when they call 911
Retrieve an agent's address when they call 911
To retrieve an agent's validated address from the Amazon Connect, create an outbound whisper flow that calls a Lambda function. Code the Lambda function to retrieve the address from the agent's customer profile, as shown in the following illustration:
![\[Amazon Connect E911 address retrieval process.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/e911-workflow-2.png)
1. Create an AWS Lambda function that uses the [SearchProfiles](https://docs.aws.amazon.com/customerprofiles/latest/APIReference/API_SearchProfiles.html) API to retrieve the physical address for a given agent from Customer Profiles.
1. [Create an outbound whisper flow that relays this physical address as part of the emergency out dial](#connect-detect-911-dial).
1. [Add a task that sends notifications when an E911 call is placed](#connect-e911-notifications).
## Create an outbound whisper flow that relays the physical address
Create an outbound whisper flow
For outbound voice calls within Amazon Connect, an [outbound whisper flow](create-contact-flow.md#contact-flow-types) usually specifies the whisper to be played to customer. However, in this case you need to configure an [outbound whisper flow](create-contact-flow.md#contact-flow-types) to do the following:
1. Inspect the outbound call string from an agent.
1. If the string equals **911** (or **933** in a test environment), then retrieve the agent's stored location/physical address from Customer Profiles by using a Lambda function to call the [SearchProfiles](https://docs.aws.amazon.com/customerprofiles/latest/APIReference/API_SearchProfiles.html) API .
1. Attach the physical address to a contact attribute and proceed with the 911 (or 933) outbound call.
The following illustration shows an example [outbound whisper flow](create-contact-flow.md#contact-flow-types). It is configured to inspect the outbound call string from an agent, and retrieve the stored physical address for that agent by using a Lambda function. It includes the following blocks in sequence: [AWS Lambda function](invoke-lambda-function-block.md), [Set contact attributes](set-contact-attributes.md), and [Call phone number](call-phone-number.md).
![\[An outbound whisper flow to detect a 911 or 933 call.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/e911-example-outbound-whisper.png)
+ Step 1: Call a Lambda function that retrieves the location for an agent (Input parameter = Agent User Name). The following image shows how to configure an [AWS Lambda function](invoke-lambda-function-block.md) block is so the agent **username** is passed to the Lambda function.
![\[The properties page of an Invoke AWS Lambda function block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/e911-invoke-lambda-block.png)
+ Step 2: Attach the location received to a contact attribute (see [Format a physical address for E911 to pass to Amazon Connect](connect-format-physical-address-e911.md) for the required format).
+ Step 3: Update the call origination to the agent's phone number and continue with the outbound call.
**Note**
The origination number is the caller ID that is passed along with the 911 outbound call. If the origination phone number supports inbound calls, emergency responders will be able to call back the agent in case the initial phone call was disconnected.
The 911 call is specific to United States. As a result, the origination phone number must be a valid US phone number.
For example, when an agent places an outbound call, if an invalid US phone number is passed to the carrier network, the carrier can reject the call. To avoid this situation, if the agent uses an invalid number from Amazon Connect, Amazon Connect defaults to the Caller ID that is assigned to the queue in the agent's routing profile.
The capability does not place any other rules on this number. For example, the origination number can the phone number of the security front desk.
## Add a task that sends notifications when an E911 call is placed
Add a task that sends notifications when an E911 call is placed
When an agent calls 911 it is important to notify in real time the appropriate people in your organization, such as corporate security or a human resources administrator, that someone from the contact center has placed an E911 call. To do this, create an Amazon Connect task in the [outbound whisper flow](create-contact-flow.md#contact-flow-types). Then add custom notification logic to the task.
The following image shows an example of a [Create task](create-task-block.md) block in an [outbound whisper flow](create-contact-flow.md#contact-flow-types). It is located after the **Set contact attributes** block and before the **Call phone number** block.
![\[C create task block in an outbound whisper flow.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/e911-create-task-flow.png)
The following image shows the **Properties** page for a [Create task](create-task-block.md) block. It is configured to notify corporate security that an agent from the contact center has placed an E911 call.
![\[The properties page of a create task block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/e911-create-task-config.png)
# Format a physical address for E911 to pass to Amazon Connect
Format a physical address for E911
This topic explains how to format a physical address so it can be passed to Amazon Connect.
E911 outbound calls require a physical address to be passed to Amazon Connect as a JSON string with keys and values that represent the various fields in the address. For example, consider the following US address:
+ 2121 7th Ave, Seattle, WA, 98121, USA
The address must be attached as a JSON string against the key `CivicAddress`, as shown in the following example. Every address field is attached to a specific coded key.
`CivicAddress: {"country":"USA","RD":"7th","A3":"Seattle","PC":"98121","HNO":"2121","STS":"Ave","A1":"WA"}`
The following illustration shows how an example input address maps to [PSAP](https://en.wikipedia.org/wiki/Public_safety_answering_point) address keys:
![\[The mapping of a physical address to PSAP address keys.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/e911-example-mapping-scheme.png)
The following table shows a complete list of keys.
| Attribute name | Description | Example | Required | Character limit | Recommended character limit |
| --- | --- | --- | --- | --- | --- |
| country | The country is identified by the two-letter ISO 3166 code. | US | Required | 2 | |
| A1 | National subdivisions (state, region, province, prefecture) | NY | Required | 2 | |
| A3 | City, township, shi (JP) | New York | Required | 32 | |
| PRD | Leading street direction | N, W | Required only if applicable to address | 2 | |
| POD | Trailing street suffix | SW | Required only if applicable to address | 2 | |
| STS | Street suffix | Avenue, Platz | Required only if applicable to address | 5 | |
| HNO | House number (numeric part only) | 2121 | Required | 10 | |
| HNS | House number suffix | A, 1/2 | Required only if applicable to address | 4 | |
| LOC | Additional location information | Room 543 | Optional | 60 | 20 or less |
| NAM | Name (residence, business or office occupant) | Example Corp | Optional | 32 | |
| PC | Postal code | 10027 | Required | 5 | |
| RD | Primary road or street | Broadway | Required | 40 | |
**Note**
It is your responsibility to validate the address against a standard repository such as the Master Street Address Guide (MSAG).
## Programming notes
Programming notes
Currently it isn't possible to pass a JSON structure as an `Attribute` to Amazon Connect. Therefore, the location retrieved by the Lambda function needs to be converted to a JSON string before it is passed to Amazon Connect. For example, using the Python programming language, if the location retrieved is stored in a JSON structure `json_agent_location` then it can be passed to Amazon Connect (from the Lambda function) as follows:
`return { ,'CivicAddress': json.dumps(json_agent_location) ,'agent_did_number': '+15555551212' }`
For an address such as the following example:
+ 2121 7th Ave, Seattle, WA, 98121, USA
The key-value pair:
`CivicAddress: {"country": "USA", "RD": "7th", "A3": "Seattle", "PC": "98121", "HNO": "2121", "STS": "Ave", "A1": "WA"}`
And the corresponding JSON string that is actually passed to Amazon Connect:
`CivicAddress: {\"country\": \"USA\", \"RD\": \"7th\", \"A3"\: \"Seattle\", \"PC\": \"98121\", \"HNO\": \"2121\", \"STS\": \"Ave\", \"A1\": \"WA\"}`
**Note**
Using `json.dumps` adds an escape character **\$1** to each quotation mark (**"**).
# Enable outbound calls in your Amazon Connect instance
Enable outbound calls
Before your agents can make outbound calls to customers, you need to set up your Amazon Connect instance for outbound communications.
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. In the navigation pane, choose **Telephony under Channels and communications**.
1. To enable outbound calling from your contact center, choose **Make outbound calls with Amazon Connect**.
1. To enable outbound campaigns, choose **Enable outbound campaigns**.
1. By enabling early media audio, your agents can hear pre-connection audio such as busy signals, failure-to-connect errors, or other informational messages from telephony providers, when making outbound calls. Choose **Enable early media**.
1. Choose **Save**.
1. Ensure agents have the **Contact Control Panel (CCP) - Make outbound calls** permission in their security profile. For instructions, see [Assign a security profile for Amazon Connect to a contact center user](assign-security-profile.md).
**Note**
For a list of countries you can call **by default** based on the Region of your instance, see [Countries that call centers using Amazon Connect can call by default](country-code-allow-list.md).
For a list of all countries available for outbound calls based on the Region of your instance, see [Amazon Connect pricing](https://aws.amazon.com/connect/pricing/). If a country is not available in your dropdown menu, open a ticket to add it to your allowlist.
# Outbound calling restrictions in Amazon Connect
Outbound calling restrictions
This topic explains restrictions that are in place for outbound calling with Amazon Connect.
**Topics**
+ [Use of toll-free numbers outside the country of origin](#restriction1)
+ [Use of UIFN numbers for outbound dialing](#restriction2)
+ [Redirection of calls](#restriction3)
+ [International calling restrictions](#restriction4)
## Use of toll-free numbers outside the country of origin
Use of toll-free numbers outside the country of origin
Amazon Connect does not support the use of toll-free numbers for international calling. International calls from toll-free numbers can be flagged as spam by downstream providers, resulting in negative reputation scores. They can also generate unexpected fees for call recipients.
## Use of UIFN numbers for outbound dialing
Use of UIFN numbers for outbound dialing
UIFN numbers are designed to be used for inbound calls only. They cannot be used for outbound calling. If you attempt to use UIFN for outbound calling, the calls will be blocked.
## Redirection of calls
Redirection of calls
If you are using Amazon Connect to redirect calls: If you are receiving calls with Anonymous (withheld CLI), you must use an Amazon Connect number for the transfer.
**Important:** Anonymous calls (calls without caller ID) are increasingly blocked by carriers as anti-spam measures and may violate telecommunications regulations in many countries. Always configure a valid caller ID number from your Amazon Connect instance to ensure reliable call delivery.
See [Set up outbound caller ID in Amazon Connect](queues-callerid.md).
## International calling restrictions
International calling restrictions
Amazon Connect has several restrictions on international calling. These are based on requirements in the following specific jurisdictions.
### South Africa
South Africa
South African mobile numbers available under the DID option are designed to be national-only services and are not supported for international calling.
### Taiwan
Taiwan
Taiwan DID's are set up to be in-country only services and are not internationally reachable.
### Vietnam
Vietnam
Vietnamese carriers are implementing enhanced fraud prevention measures with stricter limitations for calling activities. Amazon Connect requires that all customers calling Vietnamese numbers comply with additional requirements for continued use.
#### Eligibility criteria
Eligibility criteria
+ **Unsupported use cases**
+ Short calls and alerting (less than 15 seconds).
+ Any form of cold calling, marketing or advertising.
+ Any calls to invalid phone numbers. All numbers called must be validated as accurate.
+ Repeated calls using the same FROM / TO numbers (no more than 3 per day)
+ Any calls from a number that cannot be called back.
+ **Supported use cases**
+ Direct calls to known business entities. For example, calling a hotel or IT support function.
+ Calling users who attempted to engage with your business. For example, university placement schemes or product purchases.
+ Customer care activities, for example calling a customer to provide hardware support.
### China
China
Chinese carriers are increasingly blocking international routes into China unilaterally. Amazon Connect has taken steps to continue to support our existing customers but require that all customers comply with additional requirements for continued use. Starting October 14, 2023 all customers approved to call China are required to follow these conditions.
#### Eligibility criteria
Eligibility criteria
+ **Unsupported use cases**
+ Short calls and alerting (less than 15 seconds).
+ High volume of calls, especially when done over a short period of time, using the same outbound caller ID (more than 5 calls per minute).
+ Any form of cold calling.
+ Any calls to invalid phone numbers. All numbers called must be validated as accurate.
+ Repeated calls using the same FROM / TO numbers.
+ Attempts to call China FROM any number that has not been pre-approved.
+ **Supported use cases**
+ Direct calls to known business entities. For example, calling a hotel or IT support function.
+ Calling users who attempted to engage with your business. For example, university placement schemes or product purchases.
#### Data required for setup
Data required for setup
To request the ability to call Chinese telephone numbers (\$186), perform the following steps:
+ You must provide an exact list of telephony numbers you will use to phone China.
+ The number must be a DID provided by Amazon Connect. No other number is acceptable.
+ The number cannot be a DID provided by Hong Kong, Macau, Taiwan, China, or Singapore.
**Note**
The above list may change at any time.
+ Any number used to call Chinese telephone numbers must be able to called back. You must also implement a call back message that clearly states the name of the company that is associated with the phone number.
+ You must provide a detailed description of your use case, and confirm that you meet the [eligibility criteria](#criteria-cr) described in this topic.
#### Consequences for violating the calling criteria for China
Consequences for violating the calling criteria for China
Amazon Connect has a zero tolerance policy for calling into China. Amazon will suspend your use of Amazon Connect if you use the service for any of the restricted use cases identified in this topic. It is essential that the administrators of your Amazon Connect service focus on ensuring the members of your organization are aware of these restrictions, as ignorance of the rules is not an acceptable reason for breach.
#### Service assurance
Service assurance
In the event of further incidents where Chinese carriers block major international routes without prior warning and impact the ability to call China, the exemptions in the [Amazon Connect Service Level Agreement](https://aws.amazon.com/connect/sla/) will take effect.
# Optimize your reputation for outbound calling in Amazon Connect
Optimize your reputation for outbound calling
In the contact center industry one of the most difficult tasks is understanding why customers don't answer calls when you dial out. Is the customer deliberately not answering, or are they busy on a work call or answering the door? For contact centers it's impossible to know but there are things you can do about it.
This topic provides recommended steps you can take to improve your call answer rates for outbound calling.
## Step 1: Know your customer's preferred contact method
Step 1: Know your customer's preferred contact method
One of the biggest mistakes that contact centers make is not knowing whether the customer wants to be contacted by telephone call. When the customer engaged with you, did you check whether they want to be reached by phone, e-mail, or text?
Businesses with multi-channel engagement outperform 70% on average compared to business without multi-channel engagement.
## Step 2: Brand your calls
Step 2: Brand your calls
By using call branding solutions, you can provide enhanced call displays that include your business name, logos, reason for the call, and your service. Branding your calls increases the call answer rate by 30%.
Amazon Connect partners with solutions providers like [First Orion](https://firstorion.com/amazon-connect-branded-calling-now-available/) and Neustar to offer branded calling services.
## Step 3: Select caller IDs that mean something to your customer
Step 3: Select caller IDs that mean something to your customer
Not every contact center is the same. What works for some might not work for others. But there are correlations in how successful outbound campaigns are based on your caller ID. Following are a few suggestions to try creating meaningful caller IDs:
+ **Area localization**. Use a caller ID in the same area as the prospect.
+ **City localization**. Use a caller ID in the same city as the prospect.
+ **Recognizable golden toll free number** such as 0800 123 0000.
+ **Mobile numbers**. Where countries permit this, it may be possible to use a virtual mobile number to dial out from a contact center. For a list of countries where Amazon Connect supports mobile numbers, see [Region requirements for ordering and porting phone numbers in Amazon Connect](phone-number-requirements.md).
## Step 4: Make sure your campaign is calling valid numbers
Step 4: Make sure your campaign is calling valid numbers
Maintaining accurate customer contact information is essential for successful outbound calling operations. Amazon Connect's detailed disconnect reasons help identify invalid phone numbers in your contact lists. If more than 0.5% of your calls are failing due to invalid numbers, we recommend implementing regular contact list maintenance through update campaigns or using services like Amazon Pinpoint for phone number validation.
## Step 5: Make outbound calls at optimal times
Step 5: Make outbound calls at optimal times
Another strategy for outbound call campaigns is making sure that calls are placed at the best times. It is critical to never harass your customers or prospects—no one wants to be contacted multiple times by the same company. Generally speaking, it is never a good idea to call before 10:00AM or after 5:00PM as people are at their busiest or need their quiet time. Customers should be called when it's a good for them, depending on their profile. This may mean that one customer should be called around noon, while another is more accessible in the afternoon.
In addition, there are regulations such as TCPA (in the US) and OFCOM (in the UK) that provide guidance on when not to call end customers. We strongly recommend that you abide by such regulations.
## Step 6: Manage and monitor the reputation of your caller IDs
Step 6: Manage and monitor the reputation of your caller IDs
For US-based operations, registering your business numbers with services like Free Caller Registry is essential for managing your caller ID reputation. Amazon Connect's Contact Trace Record disconnect reasons help you identify when your numbers are experiencing carrier-level blocking.
We recommend assigning dedicated resources to monitor your number reputation and address blocking issues from carriers or third-party websites. Consider these important factors:
1. Third-party blocking services like Hiya.com can implement automatic blocks based on user report thresholds
1. On specific devices, such as Samsung phones, blocking can make up to 20% of your prospects unreachable
1. Online complaints about specific caller IDs can significantly impact answer rates, as prospects often search numbers before answering
If your caller ID has been flagged, switching to a new phone number is typically the fastest way to restore connectivity.
## Step 7: Use multiple numbers as a callerID
Step 7: Use multiple numbers as a callerID
Today, outbound contact centers typically embrace an intelligent, more efficient manner of dialing.
For example, one method is to use multiple phone numbers when placing outbound calls. Customers are more likely to answer a call if they feel that they are not being called repeatedly by the same number. In fact, using the same phone number repeatedly is a sure way to annoy customers and prospects who may feel they are being contacted too often.
## Step 8: Engage with App Vendors
Step 8: Engage with App Vendors
Apps that provide on-device call blocking are common across all major handsets. Many apps use blocking services from other commercial entities, some allow users to crowdsource spam numbers, and others partner with major carriers. Unblocking your numbers across geographies and app providers is often challenging and sometimes requires payment of fees. Some providers offer free business registration programs, while others provide no opportunities for redress. You might need to research the common apps in your region or those used by your customer base and work with these services directly.
## Step 9: Add messaging to your outreach strategy to let customers know who you are
Step 9: Add messaging to your outreach strategy to let customers know who you are
It's inevitable that you'll end up with a list of unanswered calls that you weren't able to connect. There are a variety of creative ways to use SMS with prospects. Here are some ideas to increase answer rates with your prospects.
1. Send an SMS before calling, letting them know who you are and when you will be calling, optionally allowing them to reschedule to a more convenient time.
1. If the prospect doesn't answer, send an SMS to allow them to reschedule the call or request a call back.
1. Re-engage with prospects with promotional offers or discounts that resonates with your prospects.
## Step 10: Validate your outbound calling strategy
Step 10: Validate your outbound calling strategy
Data-driven decisions and continuous improvement are key to delivering business value through your outbound calling strategy. Treat each operational change as an experiment, ensuring you can measure and compare its effectiveness.
We recommend creating custom reports that track both customer reachability and specific business outcomes. You can combine Contact Trace Record data with your own metrics using Amazon Connect's data lake or AWS services like QuickSight. Once you establish a baseline, you can evaluate changes and optimize for success.
# Manage users that you add to Amazon Connect
Add users
As the admin one of your key responsibilities is to manage users, add users to Amazon Connect, give them their credentials, and assign the appropriate permissions so they can access the features needed to do their job.
The topics in this section explain how to add users using the Amazon Connect admin website. To manage users programmatically, see [User management actions](https://docs.aws.amazon.com/connect/latest/APIReference/users-api.html) in the *Amazon Connect API Reference Guide*.
**Topics**
+ [Add users](user-management.md)
+ [Edit users in bulk](edit-users-in-bulk.md)
+ [View historical changes](view-historical-changes-user-records.md)
+ [Download users](download-user-records.md)
+ [Delete users](delete-users.md)
+ [Reset passwords](password-reset.md)
+ [Security profiles](connect-security-profiles.md)
# Add users to Amazon Connect
Add users
When you add users to Amazon Connect, you can configure them with information appropriate to their roles. For example, you specify their [security profile](connect-security-profiles.md), which indicates the tasks they can perform in Amazon Connect admin website. For agents you specify their [routing profile](routing-profiles.md), which indicates the contacts that can be routed to them.
This topic explains how to add users using the Amazon Connect admin website. To add users programmatically, see [CreateUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateUser.html) in the *Amazon Connect API Reference Guide*. To use the CLI, see [create-user](https://docs.aws.amazon.com/cli/latest/reference/connect/create-user.html).
## Add a user individually
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Users - Create** permission.
1. In Amazon Connect, on the left navigation menu, choose **Users**, **User management**.
1. Choose **Add new users**.
1. Choose **Create and set up a new user** and then choose **Next**.
1. Enter the name, email address, secondary email address, mobile number, and password for the user.
**Note**
SAML users don't have primary email addresses, they have username logins. A username login is typically an email address but it doesn't have to be. For these users the field label **Email address** is empty inside Amazon Connect. When email notifications are sent for SAML users, they must have a secondary email configured in order to get it. If a secondary email is not configured, the user won't receive the email.
**Tip**
Mobile number is not currently used by Amazon Connect.
1. Choose a routing profile and a security profile.
1. Optionally, add tags to identify, organize, search for, filter, and control who can access this hours of operation record. For more information, see [Add tags to resources in Amazon Connect](tagging.md).
1. Choose **Save**. If the Save button isn't active, it means you're logged in with an Amazon Connect account that doesn't have the required security profile permissions.
To fix this issue, log in with an account that is assigned to the Amazon Connect Admin security profile. Or, ask another Admin to help.
1. For information about adding agents, see [Configure agent settings in Amazon Connect](configure-agents.md).
## Add users in bulk from a .csv file
Add users in bulk
You can add up to 1000 users at a time by using a .csv file.
**Note**
Avoid adding too many unique resources in the .csv file. For example, don't add more than 100 different routing profiles. This may cause a timeout or failure during the validation process.
Bulk upload is for adding new records, not for editing existing records. To edit user records in bulk, see [Edit users in bulk in Amazon Connect](edit-users-in-bulk.md).
Use these steps to add several users from a .csv file such as an Excel spreadsheet.
1. Log in to Amazon Connect with an **Admin** account, or an account assigned to a security profile that has **Users - Create** permission.
1. In Amazon Connect, on the left navigation menu, choose **Users**, **User management**.
1. Choose **Add new users**.
1. Choose **Import users using a .csv template** and then choose **.csv template**.
The .csv template has the following columns in the first row:
+ first name
+ last name
+ user login
+ agent hierarchy
+ routing profile name
+ security\$1profile\$1name\$11\$1security\$1profile\$1name\$12
+ user\$1hierarchy\$11\$1user\$1hierarchy\$12
+ phone type (soft/desk)
+ phone number
+ tags
+ persistent connection
+ audio enhancement(none/isolate voice/suppress noise)
The following image shows a sample of what the .csv template looks like in an Excel spreadsheet. The first row in the spreadsheet contains the column headings, and the second row contains sample user data.
![\[The csv template in an Excel spreadsheet.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/add-bulk-users-2.png)
1. Add your users to the template and upload it to Amazon Connect. Choose **Upload file and verify**.
1. Amazon Connect validates the data in the file. Choose **Save** to create the new user records.
![\[The uploaded users and Save button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/save-bulk-users.png)
If you get a validation error message, it usually indicates that one of the required columns is missing information, or there's a typo in one of the cells.
The following image shows an example validation error message. In this case, the security profile was misspelled and a password didn't meet requirements.
![\[A sample error message when the csv file is not valid.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/error-message-uploaded-csv-file.png)
1. To upload only the validated user records, choose **Save**. A dialog box prompts you for confirmation.
![\[A dialog box to create a user.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-save-1.png)
1. A banner displays the status of the upload and confirms when it's complete.
**Tip**
While a batch of additions is being processed, you can continue working on the **User management** page, choosing another batch of user records to create, edit, or delete, in bulk or individually. This is useful for quickly updating settings such as routing profiles for groups of agents.
Amazon Connect sequentially processes the records in bulk.
1. Choose **Refresh** to update the **User management** page with the users that have been created.
![\[A banner that users have been created.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/save-bulk-users-banner.png)
## Required permissions for adding users
Before you can add users to Amazon Connect, you need the following permissions assigned to your security profile: **Users - Create**. The following image shows that this security profile permission is in the **Users and permissions** section of the **Add/Edit security profile** page.
![\[The Users and permissions section of the security profile page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/security-profile-create-user-accounts.png)
By default, the Amazon Connect **Admin** security profile has these permissions.
For information about how to add more permissions to an existing security profile, see [Update security profiles in Amazon Connect](update-security-profiles.md).
# Edit users in bulk in Amazon Connect
Edit users in bulk
Bulk edit mode enables you to quickly edit the attributes that are common across user records, such as routing profiles, security profiles, and tags.
**Tip**
While a batch of bulk edits is being processed, you can continue working on the **User management** page, such as selecting more records to edit or delete, in bulk or individually. This is useful for quickly updating settings, such as routing profiles for groups of agents.
1. Log in to Amazon Connect with an Admin account, or an account assigned to a security profile that has **Users - Edit** permission.
1. In Amazon Connect, on the left navigation menu, choose **Users**, **User management**.
1. If needed, choose **Add filter** to specify a subset of users, such as users with a specific **Routing profile**. This option is shown in the following image.
![\[The add filter option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-filter.png)
1. To quickly update a large number of users, at the bottom of the table choose to display **100** rows per page, as shown in the following image.
![\[The rows per page dropdown box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-rows-per-page.png)
1. To edit all the records on the page, choose the top box. Otherwise, select one or more records you want to edit at the same time. Choose **Edit**.
![\[The User management page, emphasizing the top box, which selects all user records.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-edit-select.png)
1. On the **Bulk edit** page, in the **Settings** section, you can choose the following settings for all of the selected users:
+ Security profile
+ Routing profile
+ Phone type
+ Auto accept per channel
+ After Call Work (ACW) timeout per channel
+ Agent hierarchy, if this has been set up
+ Tags
1. Choose **Save** to apply your changes to the selected records.
1. While that batch of user records is being updated, you can continue working on the **User management** page, performing other create, edit, and delete tasks on user records.
## Perform other edit tasks while a batch of bulk edits is being processed
Perform other edit tasks while a batch of bulk edits is being processed
After saving an update for a group of users, you can either make additional changes on the **Bulk edit** page (for example, [edit other user details](#edit-other-user-details) such as contact information) or you can choose different user records to edit.
**Important**
As long as you remain on the **User management** page, your update request will continue to be processed. Review the messages at the top of the page for the status of the update.
The following image shows an example of message at the top of the **User management** page that Amazon Connect is updating a batch of user records.
![\[A banner showing Amazon Connect in the process of updating a batch of user records.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-bulk-edit-banner3.png)
When you perform additional tasks on the **User management** page, Amazon Connect appends the next request to create, edit, or delete user records to the existing status message at the top of the page. Amazon Connect sequentially processes them in bulk.
Following are some tips about how Amazon Connect processes bulk edit requests.
+ If you choose **Cancel** during a bulk create, edit, or delete, **only those requests not yet processed are canceled**.
+ A message displays how many users were successfully updated. Choose **Refresh** to refresh the page with the list of the updated users.
![\[The button to refresh the results of Amazon Connect processing bulk edit requests.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-bulk-cancel-refresh.png)
+ If some user records fail to be updated, a message similar to the following image is displayed:
![\[A message showing that users failed to be updated.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-failed-edit.png)
You have the following options:
+ Choose **download the CSV** to discover the reason changes weren't updated. In the following example, the agent hierarchy was deleted before the user records were saved.
![\[A diagram showing why edits failed and the failed fields.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-failed-edit-reason.png)
+ Choose **Try again** to resubmit only those user records that failed. The others were already successfully updated.
+ Choose **Edit** to be directed to the **Bulk edit** page so you can change the input for the user records that failed.
![\[A diagram showing the Bulk edit option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-bulk-edit-fail-input.png)
+ Choose **Cancel** to not do anything with the 3 user records that weren't updated.
## Edit other user details
Edit other user details
You can page through selected user records to make updates to contact information, rather than choosing and opening each record individually.
1. On the **Bulk edit** page, select the user records you want to edit.
1. Choose the **Edit** (pencil) icon next to individual users to make updates.
1. A dialog box opens for the individual user. Make your changes, and choose **Submit**.
1. If needed, choose **Previous** and **Next** to open the next user record in the list. The following image shows the **Edit** dialog box for a single user while in bulk edit mode.
![\[The edit dialog box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-bulk-single-edit.png)
## Edit user settings programmatically
Edit user settings programmatically
You can change the following values programmatically across selected users. The users are changed to the same value.
| Property | API | CLI |
| --- | --- | --- |
| Routing profiles | [UpdateUserRoutingProfile](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateUserRoutingProfile.html) | [update-user-routing-profiles](https://docs.aws.amazon.com/cli/latest/reference/connect/update-user-routing-profiles.html) |
| Security profiles | [UpdateUserSecurityProfiles](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateUserSecurityProfiles.html) | [update-user-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/connect/update-user-security-profiles.html) |
| Tags | [TagResource](https://docs.aws.amazon.com/connect/latest/APIReference/API_TagResource.html) [UntagResource](https://docs.aws.amazon.com/connect/latest/APIReference/API_UntagResource.html) | [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/connect/tag-resource.html) [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/connect/untag-resource.html) |
| User hierarchies | [UpdateUserHierarchy](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateUserHierarchy.html) | [update-user-hierarchy](https://docs.aws.amazon.com/cli/latest/reference/connect/update-user-hierarchy.html) |
| User configuration | [UpdateUserConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateUserConfig.html) | [update-user-config](https://docs.aws.amazon.com/cli/latest/reference/connect/update-user-config.html) |
You can edit the following identity and contact information programmatically for an individual user: first name, last name, email address, mobile number, secondary email address. Use the following API or CLI:
| Property | API | CLI |
| --- | --- | --- |
| Identify and contact information | [UpdateUserIdentityInfo](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateUserIdentityInfo.html) | [update-user-identity-info](https://docs.aws.amazon.com/cli/latest/reference/connect/update-user-identity-info.html) |
# View historical changes to user records
View historical changes
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Users and permissions - Users - View** permissions.
1. In Amazon Connect, on the left navigation menu, choose **Users**, **User management**.
1. On the **User management** page, choose **View historical changes**, as shown in the following image.
![\[The user management page, with an arrow pointing to the View historical changes link.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-view-historical-changes.png)
1. On the **View recent changes for agent** page, there is one row for each time a user record was changed. In the following image, there are multiple rows for **johndoe** because that user record has been updated multiple times.
To view the past changes for a specific user, choose their user name.
![\[The View recent changes for agent page, with an arrow pointing to the Resource name.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-view-recent-changes.png)
1. On the **View recent changes for [resource name]** page, you can view details about what has been changed in the user record, when, and who made the change, as shown in the following image.
![\[The View recent change page, a list of recent changes to the user record for John Doe.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-view-recent-changes-johndoe.png)
# Download a user list from your Amazon Connect instance
Download users
You can export a list of users from Amazon Connect to a .csv file. The output is limited to the results that appear on the page; it does not include all the users, if you have more users than appear on the page.
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account assigned to a security profile that has **Users and permissions - Users - View** permissions.
1. In Amazon Connect, on the left navigation menu, choose **Users**, **User management**.
1. Choose **Download CSV**.
# Delete users from your Amazon Connect instance
Delete users
**Important**
You can't undo a deletion.
When a user is deleted from Amazon Connect, you won't be able to configure their agent settings any more. For example, you won't be able to assign a routing profile to them.
If you delete a user record that has an associated quick connect, you need to [delete the quick connect](quick-connects-delete.md), too. Otherwise it will be orphaned. When agents attempt to transfer calls to it, no one is there to answer the call.
Orphaned quick connects can disrupt other Amazon Connect processes such as instance replication and syncing processes that are done as part of [Amazon Connect Global Resiliency](setup-connect-global-resiliency.md).
This topic explains how to delete user records using the Amazon Connect admin website. To delete user records programmatically, see [DeleteUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeleteUser.html) in the *Amazon Connect API Reference Guide*. To use the CLI, see [delete-user](https://docs.aws.amazon.com/cli/latest/reference/connect/delete-user.html).
## What happens to the user's metrics?
The user's data in contact records and reports is retained. The data is preserved for the consistency of the historical metrics. For example, when you search for contact records, you'll still see the agent's username, any contact recordings involving the agent, etc.
In the historical metrics reports, the agent's data will be included in the **Agent performance** metrics report. However, you won't be able to see an **Agent activity audit** of the deleted agent because their name won't appear in the drop-down list.
## How to delete users
**Tip**
While a batch of deletions is being processed, you can continue working on the **User management** page, choosing another batch of user records to create, edit, or delete, in bulk or individually. This is useful for quickly updating settings such as routing profiles.
1. Log in to Amazon Connect using an **Admin** account, or an account assigned to a security profile that has **Users - Remove** permission.
1. In Amazon Connect, on the left navigation menu, choose **Users**, **User management**. Choose one or more users you want to delete, and then choose **Delete**.
![\[The User management page, Delete option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/delete-users-how-to.png)
1. Confirm you want to delete the users.
![\[The delete user page, Delete button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/delete-users-confirm.png)
1. The following image shows and example of the message when a user is deleted successfully. Choose **Refresh** to update the list of users on the **User management** page.
![\[The delete user page, the refresh button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/delete-users-refresh.png)
1. If Amazon Connect fails to delete one or more user records, it displays a message similar to the following image.
![\[A banner that record was not deleted.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/delete-users-error.png)
When you get a failed to delete message, you have the following options:
+ Choose **download the CSV** to view the error details. The following details show the user records had already been deleted. In this case, I hadn't refreshed the **User management** page and tried to delete the records again.
![\[A list of reasons for records not being deleted.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/user-management-bulk-delete-fail-reasons.png)
+ Choose **Try again** to resubmit those records that failed to be deleted. The other records were successfully deleted.
+ Choose **Cancel** to not do anything with the user records that weren't deleted.
## Required permissions to delete users
Before you can update permissions in a security profile, you must be logged in with an Amazon Connect account that has the following permissions: **Users - Remove**.
![\[The users and permissions section of the security profiles page, Users option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/delete-users-required-permissions.png)
By default, the Amazon Connect **Admin** security profile has these permissions.
# Reset a user's password for Amazon Connect
Reset passwords
**To reset a user's Amazon Connect password**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an Admin account, or a user account that has [security profile permissions](security-profile-list.md) to reset passwords.
1. In Amazon Connect, on the left navigation menu, choose **Users**, **User management**.
1. Select the user and choose **Edit**.
1. Choose **reset password**. Specify a new password and then choose **Submit**.
Resetting the user's password will immediately log them out of the Contact Control Panel.
1. Communicate the new password to the user.
## Reset your own lost or forgotten Amazon Connect admin password
+ See [Emergency login to the Amazon Connect admin website](emergency-admin-login.md).
## Reset your own agent or manager password
Use the following steps if you want to change your password, or if you forgot it and need a new one.
1. If you're an Amazon Connect agent or manager, at the Amazon Connect login page, choose **Forgot Password**.
1. Type the characters you see in the image, and then choose **Recover Password**.
1. A message will be sent to your email address with a link that you can use to reset your password.
## Reset your own lost or forgotten AWS password
+ To reset the password you used when you first created your AWS account, see [Resetting a Lost or Forgotten Root User Password](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys_retrieve.html#reset-root-password) in the *IAM User Guide*.
# Security profiles for Amazon Connect and Contact Control Panel (CCP) access
Security profiles
A security profile is a group of permissions that map to a common role in a contact center. For example, the Agent security profile contains permissions needed to access the Contact Control Panel (CCP).
Security profiles help you manage who can access the Amazon Connect dashboard and Contact Control Panel (CCP), and who can perform specific tasks.
**Topics**
+ [
# Best practices for Amazon Connect and Contact Control Panel (CCP) security profiles
](security-profile-best-practices.md)
+ [
# Inherited permissions for Amazon Connect and Contact Control Panel (CCP) security profiles
](inherited-permissions.md)
+ [List of security profile permissions](security-profile-list.md)
+ [
# Default security profiles in Amazon Connect
](default-security-profiles.md)
+ [
# Assign a security profile for Amazon Connect to a contact center user
](assign-security-profile.md)
+ [
# Create a security profile in Amazon Connect
](create-security-profile.md)
+ [
# Update security profiles in Amazon Connect
](update-security-profiles.md)
+ [Apply tag-based access control](tag-based-access-control.md)
+ [Apply hierarchy-based access control](hierarchy-based-access-control.md)
# Best practices for Amazon Connect and Contact Control Panel (CCP) security profiles
+ Limit who has **Users - Edit or Create** permissions
People with these permissions pose a risk to your contact center because they can do the following:
+ Reset passwords, including that of the administrator.
+ Grant other users permission to the Admin security profile. People assigned to the Admin security profile have full access to your contact center.
Doing these things would enable someone to lock out those who need to access Amazon Connect, and allow in others who can steal customer data and damage your business.
To reduce the risk, as a best practice we recommend limiting the number of people who have **Users - Edit or Create** permissions.
+ [Use AWS CloudTrail](logging-using-cloudtrail.md) to log the requests and responses of [UpdateUserIdentityInfo](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateUserIdentityInfo.html). This enables you to track changes made to user information. Someone who has the ability to call the `UpdateUserIdentityInfo` API can change a user's email address to one owned by an attacker, and then reset the password through email.
+ [Understand inherited permissions](inherited-permissions.md)
Some security profiles included inherited permissions: when you assign dedicated permissions to one object, by default permissions are granted to sub-objects. For example, when you grant dedicated permission to edit users, you also grant them permission to list all security profiles for your Amazon Connect instance. This is because to edit users, the person has access to the drop-down list of security profiles.
Before assigning security profiles, review the list of inherited permissions.
+ **Understand the implications of [access control tags](https://docs.aws.amazon.com/connect/latest/adminguide/tag-based-access-control.html) before applying them to a security profile.** Applying access control tags is an advanced configuration feature that is supported by Amazon Connect and that follows the AWS shared responsibility model. Ensure that you have read the documentation and understand the implications of applying granular permission configurations. For more information, review the [AWS shared responsibilities model](https://aws.amazon.com/compliance/shared-responsibility-model/).
+ Track who accesses recordings.
In the **Analytics and Optimization** permission group, you can enable a download icon for recorded conversations. When members of this group go to **Analytics and optimization**, **Contact search**, and then search contacts, they will see an icon to download recordings.
**Important**
This setting isn't a security feature. **Users who don't have this permission can still download recordings using other less-discoverable ways**.
We recommend that you track who in your organization accesses recordings.
# Inherited permissions for Amazon Connect and Contact Control Panel (CCP) security profiles
Some security profiles included inherited permissions: when you give a user explicit permissions to **View** or **Edit** one resource type, such as queues, they implicitly inherit permissions to **View** another resource type, such as phone numbers.
For example, assume you explicitly grant someone permission to **Edit/View** queues, as shown in the following image:
![\[The security profile permissions section of the security profiles page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/inherited-permissions.png)
By doing this you also implicitly grant them permissions to **View** a list of all phone numbers and hours of operation in your Amazon Connect instance, **when they add them to the queue**. On the **Add new queue** page, the available phone numbers and hours of operation appear in dropdown lists, as shown in the following image.
![\[The add new queue page, the hours of operation dropdown list, the outbound caller id number dropdown list.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/drop-down-permissions.png)
However, the user doesn't have permissions to **Edit** the phone numbers and hours of operation.
In this case, they also don't inherit permissions to **View** contact flows (the outbound whisper flow) and quick connects because those resources are optional.
## List of inherited permissions
The following table lists permissions that are implicitly inherited when you assign dedicated permissions to a user.
**Tip**
When a user has only explicit **View** permissions and not also **Edit** permissions, the objects are retrieved but Amazon Connect doesn't surface them in drop-down lists for the user to peruse.
| Dedicated permission | Inherited permissions |
| --- | --- |
| Users - View or Edit | When someone edits a user's information in the Amazon Connect console, they can **view** the following information in drop-down boxes when they add it to the user's account: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/inherited-permissions.html) |
| Queues - View or Edit | When someone edits queues in the Amazon Connect console, they can **view** the following information in drop-down and search boxes when they add it to the queue: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/inherited-permissions.html) |
| Quick connects - View | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/inherited-permissions.html) |
| Quick connects - Edit | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/inherited-permissions.html) |
| Phone numbers - View or Edit | When someone edits phone numbers in the Amazon Connect console (not the CCP), they can **view** the following information in a drop-down box when they associate it with the phone number: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/inherited-permissions.html) |
# List of security profile permissions in Amazon Connect
List of security profile permissions
This topic is for administrators and contact center managers who assign and manage security profile permissions in Amazon Connect.
Security profile permissions allow users access to perform specific tasks in the Amazon Connect admin website.
The following tables list:
+ **UI name**: The name of the permission as it appears on the **Security profiles** page in Amazon Connect.
+ **API name**: The name of the permission when it is returned by the [ListSecurityProfilePermissions](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListSecurityProfilePermissions.html) API.
For a list of all APIs that you can use manage security profile permissions, see [Security profile actions](https://docs.aws.amazon.com/connect/latest/APIReference/security-profiles-api.html).
+ **Use**: The functionality granted by the permission.
## Amazon Q
| UI name | API name | Use |
| --- | --- | --- |
| AI agents | QConnectAIAgents.View QConnectAIAgents.Edit QConnectAIAgents.Create QConnectAIAgents.Delete | [Create and manage AI agents](create-ai-agents.md). |
| AI prompts | QConnectAIPrompts.View QConnectAIPrompts.Edit QConnectAIPrompts.Create QConnectAIPrompts.Delete | [Create and manage AI prompts](create-ai-prompts.md). |
| AI guardrails | QConnectGuardrails.View QConnectGuardrails.Edit QConnectGuardrails.Create QConnectGuardrails.Delete | [Create and manage AI guardrails](create-ai-guardrails.md). |
## Routing
| UI name | API name | Use |
| --- | --- | --- |
| Routing profiles - Create | RoutingPolicies.Create | [Create routing profiles](routing-profiles.md). |
| Routing profiles - Edit | RoutingPolicies.Edit | Edit routing profiles. |
| Routing profiles - View | RoutingPolicies.View | View routing profiles. |
| Quick connects - Create | TransferDestinations.Create | [Create quick connects](quick-connects.md). |
| Quick connects - Delete | TransferDestinations.Delete | [Delete quick connects](quick-connects-delete.md). |
| Quick connects - Edit | TransferDestinations.Edit | Edit quick connects. |
| Quick connects - View | TransferDestinations.View | View quick connects. Agents need this permission so they can view quick connects in the agent application to transfer calls. |
| Hours of operation - Create | HoursOfOperation.Create | [Set hours of operation and timezone for a queue](set-hours-operation.md). |
| HoursOfOperation - Delete | HoursOfOperation.Delete | Delete hours of operation and timezone for a queue. |
| HoursOfOperation - Edit | HoursOfOperation.Edit | Edit hours of operation and timezone for a queue. |
| HoursOfOperation - View | HoursOfOperation.View | View hours of operation and timezone for a queue. |
| Queues - Create | Queues.Create | [Create queues](create-queue.md). |
| Queues - Edit | Queues.Edit | Edit information for a queue, such as name, description, and hours of operation. |
| Queues - Enable / Disable | Queues.EnableAndDisable | [Enable and disable queues](disable-a-queue.md) to quickly control the flow of contacts to queues temporarily. |
| Queues - View | Queues.View | View a list of queues in your Amazon Connect instance. |
| Task templates - Create | TaskTemplates.Create | [Create task templates](task-templates.md). |
| Task templates - Delete | TaskTemplates.Delete | Delete task templates. |
| Task templates - Edit | TaskTemplates.Edit | Edit task templates. |
| Task templates - View | TaskTemplates.View | View task templates. |
| Predefined attributes - View | PredefinedAttributes.View | View predefined attributes. |
| Predefined attributes - Edit | PredefinedAttributes.Edit | Edit predefined attributes. |
| Predefined attributes - Create | PredefinedAttributes.Create | [Create predefined attributes for routing contacts to agents](predefined-attributes.md). |
| Predefined attributes - Delete | PredefinedAttributes.Delete | Delete predefined attributes. |
| Data tables - Create | DataTables.Create | [Create and configure data tables](data-tables.md). |
| Data tables - Delete | DataTables.Delete | Delete data tables. |
| Data tables - Edit | DataTables.Edit | Edit metadata and values for data tables. |
| Data tables - View | DataTables.View | View data tables. |
| Data tables - Manage values | DataTables.ManageValues | Manage data table values. |
| Data tables - Edit expressions | DataTables.EditExpressionValues | Edit data table value expressions. |
## Channels and flows
| UI name | API name | Use |
| --- | --- | --- |
| Prompts - Create | Prompts.Create | [Create prompts](prompts.md). |
| Prompts - Delete | Prompts.Delete | Delete prompts. |
| Prompts - Edit | Prompts.Edit | Edit prompts. |
| Prompts - View | Prompts.View | View a list of available prompts. |
| Flows - Create | ContactFlows.Create | [Create flows](create-contact-flow.md). |
| Flows - Remove | ContactFlows.Delete | [Delete flows](delete-contact-flow.md). |
| Flows - Edit | ContactFlows.Edit | Edit flows. |
| Flows - Publish | ContactFlows.Publish | Publish flows. |
| Flows - View | ContactFlows.View | View flows. |
| Flow modules - Create | ContactFlowModules.Create | [Create flow modules for reusable functions](contact-flow-modules.md). |
| Flow modules - Remove | ContactFlowModules.Delete | Delete flow modules. |
| Flow modules - Edit | ContactFlowModules.Edit | Edit flow modules. |
| Flow modules - Publish | ContactFlowModules.Publish | Publish flow modules. |
| Flow modules - View | ContactFlowModules.View | View flow modules. |
| Bots | Bots.Create | [Create a bot by using the Amazon Connect admin website](work-bot-building-experience.md). |
| Bots | Bots.View Bots.Edit | [Evaluate the performance of your conversational AI bot in Amazon Connect](lex-bot-analytics.md). |
| Bots | Bots.Delete | Remove a bot. |
| Phone numbers - Claim | PhoneNumbers.Claim | [Claim phone numbers](get-connect-number.md). |
| Phone numbers - Edit | PhoneNumbers.Edit | Edit phone numbers. [Attach a claimed or ported phone number to a flow in Amazon Connect](associate-claimed-ported-phone-number-to-flow.md). |
| Phone numbers - Release | PhoneNumbers.Release | [Release phone numbers back to inventory](release-phone-number.md). |
| Phone numbers - View | PhoneNumbers.View | View a list of phone numbers that have been claimed or ported to your Amazon Connect instance. |
| Communication widget - Enable/Disable | ChatTestMode | Access a simulated web page so users can [test the chat experience](chat-testing.md#test-chat). Also grant users the **Contactflow.View** permission so they can view and choose from a list of available flows in the **Test settings** option. |
| Email addresses | | View |
| Email addresses | | Edit |
| Email addresses | | Create |
| Email addresses | | Remove |
| Views - View | Views.View | Allow access to [Views](view-resources-sg.md). |
| Views - Edit | Views.Edit | Allow access to edit [Views](view-resources-sg.md). |
| Views - Create | Views.Create | Create custom [view](view-resources-custom-view.md) resources. |
| Views - Remove | Views.Remove | Remove View resources. |
| AnalyticsConnectors -Edit | AnalyticsConnectors.Edit | [Edit existing analytics connectors](contact-lens-integration.md). |
| AnalyticsConnectors - View | AnalyticsConnectors.View | [View existing analytics connectors](contact-lens-integration.md). |
## Users and permissions
| UI name | API name | Use |
| --- | --- | --- |
| Users - Create | Users.Create | [Add users to Amazon Connect](user-management.md). We recommend you limit who has these permissions. They pose a risk to your contact center because they can do the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) Doing these things would enable someone to lock out those who need to access Amazon Connect, and allow in others who can steal customer data and damage your business. You can limit this risk by adding [tag-based access control](tag-based-access-control.md) on the security profile. For example, you can apply tag-based access control to deny access to administrators and the Admin security profile. |
| Users - Delete | Users.Delete | [Delete users from Amazon Connect](delete-users.md). |
| Users - Edit | Users.Edit | View and edit all user identity information *except* for security profiles. As with **Users - Create**, limit who has these permissions because they pose a risk to your contact center. |
| Users - Edit permission | Users.EditPermission | View and edit user security profiles. As with **Users - Create**, limit who has these permissions because they pose a risk to your contact center. |
| Users - View | Users.View | View user records. [Download or export a list of users](download-user-records.md) from your Amazon Connect instance to a CSV file. |
| Agent hierarchy - Create | AgentGrouping.Create | [Create agent hierarchies](agent-hierarchy.md). Add groups, teams, and agents. |
| Agent hierarchy - Edit | AgentGrouping.Edit | Edit agent hierarchies and the hierarchy level structure. |
| Agent hierarchy - Enable/Disable | AgentGrouping.EnableAndDisable | View or edit agent hierarchy information. |
| Agent hierarchy - View | AgentGrouping.View | View the agent's hierarchy information in a real-time metrics report, which can include their location and skill set data. |
| Security profiles - Create | SecurityProfiles.Create | [Create security profiles](create-security-profile.md). |
| Security profiles - Delete | SecurityProfiles.Delete | Delete security profiles. |
| Security profiles - Edit | SecurityProfiles.Edit | [Update security profiles](update-security-profiles.md). |
| Security profiles - View | SecurityProfiles.View | View security profiles. |
| Agent status - Create | AgentStates.Create | [Create an custom agent status](agent-custom.md). The status appears in the Contact Control Panel (CCP), such as Break, Lunch, or Training. |
| Agent status - Edit | AgentStates.Edit | Edit a custom agent status. |
| Agent status - Enable/Disable | AgentStates.EnableAndDisable | View and edit custom agent states. |
| Agent status - View | AgentStates.View | [View an agent's status in the real-time metrics report](rtm-change-agent-activity-state.md) and historical metrics report. For example, if they are **Available**, **Offline**, or in a custom state. View their status in the [Agent activity report](agent-activity-audit-report.md). |
| Workspaces - Create | Workspaces.Create | [Set up workspaces for your admin website users](amazon-connect-workspaces.md). |
| Workspaces - Delete | Workspaces.Delete | Delete workspaces. |
| Workspaces - Edit | Workspaces.Edit | Edit workspaces. |
| Workspaces - View | Workspaces.View | View workspaces. |
| Workspaces - Assign | Workspaces.Assign | Assign workspaces to users and routing profiles. |
| Workspaces - Edit visibility | Workspaces.EditVisibility | Edit workspaces to be visible to all users, no users, or based on assignments. |
## Contact Control Panel (CCP)
| UI name | API name | Use |
| --- | --- | --- |
| Access Contact Control Panel | BasicAgentAccess | Manages access to the Contact Control Panel (CCP). Assign this permission to agents as well as managers who need to monitor live conversations. |
| Contact Lens data | RealtimeContactLens.View | Enables users to view real-time analytics provided by Contact Lens. |
| Make outbound calls | OutboundCallAccess | Grants users permissions to make outbound calls. For more information about setting up outbound calling, see [Set up outbound calling in Amazon Connect](outbound-communications.md). |
| Voice ID | VoiceId.Access | Enables controls in the Contact Control Panel so agents can: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) |
| Restrict task creation | RestrictTaskCreation.Access | Block agents from being able to create tasks. |
| Audio device settings | AudioDeviceSettings.Access | [Choose your preferred device for speaker, microphone, and ringer in the Contact Control Panel (CCP) or agent workspace](audio-device-settings.md). |
| Video calls | VideoContact.Access | [Enable agents to use video calling and screen sharing](config-com-widget1.md#agent-cx-cw). |
| Initiate email conversation | OutboundEmail.Create | Allows agents to initiate an outbound email from the Contact Control Panel / Agent workspace without first receiving an email contact from a customer. Allows agents to forward email contacts to external email addresses or distribution lists. Allows agents to reply to closed email contacts. |
| Allow self assigning of contacts | SelfAssignContacts.Access | To self assign tasks, agents also need to have the **Restrict Task Creation** permission disabled and have tasks enabled as a channel within their assigned routing profile. |
## Analytics and Optimization
| UI name | API name | Use |
| --- | --- | --- |
| Access metrics | AccessMetrics | [Assign permissions to view dashboards and reports](dashboard-required-permissions.md). |
| Real-time metrics | AccessMetrics.RealTimeMetrics.Access | Manage access to the real-time metrics page. |
| Historical metrics | AccessMetrics.HistoricalMetrics.Access | Manage access to the historical metrics page. |
| Agent activity audit | AccessMetrics.AgentActivityAudit.Access | Manage access to the agent activity audit within the historical metrics page. |
| Dashboards | AccessMetrics.Dashboards.Access | [Dashboards in Amazon Connect for getting contact center performance data](dashboards.md) |
| View my own data in dashboards - View | AccessMetrics.DashboardsWithMyData.View | Grants access to the Dashboards to view individual agent performance metrics and the metrics of queues in the agent's routing profile. For more information, see [Agent workspace performance dashboard](performance-dashboard-aw.md). |
| Custom metrics | CustomMetrics.Create CustomMetrics.View CustomMetrics.Edit CustomMetrics.Delete CustomMetrics.Publish | Grants access to [create and manage custom service level metric calculations](dashboard-customize-widgets.md#dashboard-custom-sl) for any widget on a dashboard. |
| Contact Search | ContactSearch.View | Access the **Contact search** page, which is where users can [search for contacts](contact-search.md) and see results on the **Contact details** page. |
| View my contacts | MyContacts.View | Allows agents to view contacts that they themselves had handled, on **Contact search** and **Contact details** pages. |
| Sample contacts | ContactSearchSampleContacts.View | Find a [random sample of contacts](random-sampling-of-contacts-for-evaluation.md) for evaluating agent performance and contact quality, e.g. 5 contacts per agent from last month. |
| Search contacts by conversation characteristics | ContactSearchWithCharacteristics.Access | Access to the Contact Lens filters that enable users to search by sentiment scores, non-talk time, and category. |
| Search contacts by conversation characteristics - View | ContactSearchWithCharacteristics.View | View the Contact Lens filters that enable users to search by sentiment scores, non-talk time, and category. |
| Search contacts by keywords | ContactSearchWithKeywords.Access | Search for contacts by keyword. On the **Contact Search** page, users can access additional filters that allow them to search Contact Lens transcripts by keywords or phrases, such as "thank you for your business." |
| Search contacts by keywords - View | ContactSearchWithKeywords.View | Search for contacts by keyword. On the **Contact Search** page, users can access additional filters that allow them to search Contact Lens transcripts by keywords or phrases, such as "thank you for your business." |
| Configure searchable contact attributes - View | ConfigureContactAttributes.View | Determine what custom attribute data will be searchable (by people who have the **Contact attributes** permission). It allows them to access the **Searchable custom contact attributes** page. For more information, see [Search for contacts in Amazon Connect by using custom contact attributes or contact segment attributes](search-custom-attributes.md). |
| Restrict contact access | RestrictContactAccessByHierarchy.View | Manage a user's access to results on the **Contact search** page based on their agent hierarchy group. For more information, see [Manage who can search for contacts and access detailed information](contact-search.md#required-permissions-search-contacts). |
| Contact attributes | ContactAttributes.View | View contact attributes. Also controls access to the search filters based on contact attributes. For more information, see [Search for contacts in Amazon Connect by using custom contact attributes or contact segment attributes](search-custom-attributes.md). |
| Contact Lens - conversational analytics - View | GraphTrends.View | On the **Contact details** page for a contact, users can view conversational analytics outputs such as graphs (on sentiment, talk time, and other various outputs), sentiment indicators, and contact category labels on conversation recordings and transcripts. Users can view data on the [Amazon Connect Contact Lens conversational analytics dashboard](contact-lens-conversational-analytics-dashboard.md). |
| Contact Lens - post-contact summary | ContactLensPostContactSummary.View | View post-contact summarization powered by generative artificial intelligence (generative AI) on the Contact Search and Contact Details pages. |
| Contact Lens - custom vocabularies - Edit | ContactLensCustomVocabulary.Edit | [Add custom vocabularies](add-custom-vocabulary.md). |
| Contact Lens - custom vocabularies - View | ContactLensCustomVocabulary.View | [Download and view custom vocabularies](add-custom-vocabulary.md#view-custom-vocabulary). |
| Contact Lens - theme detection - Create | ThemeDetection.Create | [Create theme detection reports on the **Contact search** page](use-theme-detection.md). |
| Contact Lens - theme detection - View | ThemeDetection.View | View theme detection reports on the **Contact search** page. |
| Contact Lens - theme detection - Delete | ThemeDetection.Delete | Delete theme detection reports on the **Contact search** page. |
| Rules - Create | Rules.Create | [Create rules](connect-rules.md). |
| Rules - Delete | Rules.Delete | Delete rules. |
| Rules - Edit | Rules.Edit | Edit rules. |
| Rules - Generative AI | RulesGenerativeAI.Create RulesGenerativeAI.View RulesGenerativeAI.Edit RulesGenerativeAI.Delete | Manage rules that use generative AI. To create generative AI-powered rules, you additionally need the **Rules** permission. |
| Rules - View | Rules.View | View rules. |
| Login/Logout report - View | AgentTimeCard.View | [View Login/Logout reports](login-logout-reports.md). |
| Real-time contact monitoring- Enable/Disable | ManagerListenIn | [Monitor live conversations](monitor-conversations.md) and [listen to recordings of past conversations](review-recorded-conversations.md). Be sure to assign managers to the Agent security profile so they can access the Contact Control Panel (CCP). This enables them to monitor the conversation through the CCP. |
| Real-time contact barge-in - Enable/Disable | ManagerBargeIn | Enables supervisors and managers to barge into live conversations between agents and customers. To learn more about Barge for live conversations, see [Barge into live voice and chat conversations between contact center agents and customers](monitor-barge.md). |
| Saved reports - View | MetricsReports.View | [View a shared report](view-a-shared-report.md). |
| Saved reports - Create | MetricsReports.Create MetricsReports.Share | [Create and share reports](share-reports.md). |
| Saved reports - Edit | MetricsReports.Edit | Edit save reports. |
| Saved reports - Delete | MetricsReports.Delete | Delete saved reports. |
| Saved reports - Publish | MetricsReports.Publish | [Publish reports](publish-reports.md) and [share reports](share-reports.md). |
| Saved reports - Schedule | MetricsReports.Schedule MetricsReports.Publish ReportSchedules.Create ReportSchedules.Delete ReportSchedules.Edit ReportSchedules.View | [Schedule a saved report](schedule-historical-metrics-report.md). By default, the user gets permission to create, delete, edit, and view a saved report. |
| Saved reports (admin) | ReportsAdmin.View ReportsAdmin.Delete | [View and delete all saved reports in your instance, including those not created by you](manage-saved-reports-admin.md). |
| Evaluation forms - perform evaluations | Evaluation.Create Evaluation.View Evaluation.Edit Evaluation.Delete | [Evaluate performance](evaluations.md). |
| Evaluation forms - manage form definitions | EvaluationForms.Create EvaluationForms.View EvaluationForms.Edit EvaluationForms.Delete | [Create and manage evaluation forms](create-evaluation-forms.md). |
| Evaluation forms - ask AI assistant | EvaluationAssistant.Access | Access the **Ask AI** button while performing evaluations, enabling the user to get generative AI-powered recommendations for answers to questions in evaluation forms. |
| Evaluation forms - manage calibration sessions | EvaluationCalibrationSessions.Create EvaluationCalibrationSessions.Delete EvaluationCalibrationSessions.Edit EvaluationCalibrationSessions.View | Create and manage calibration sessions to drive consistency and accuracy in how managers evaluate agent performance. |
| Coaching - my coaching sessions - View | MyCoachingSessions.View | View [coaching sessions](provide-coaching.md) where you are the coach or the participant. If you are the participant, you can acknowledge the coaching session with this permission. |
| Coaching - my coaching sessions - Create, Edit, Delete | MyCoachingSessions.Create MyCoachingSessions.Delete MyCoachingSessions.Edit | Create, edit or delete coaching sessions with yourself as the coach. |
| Coaching - manage coaching sessions | CoachingSessions.Create CoachingSessions.Delete CoachingSessions.Edit CoachingSessions.View | Access coaching sessions performed by yourself or others. This permission enables you to [create coaching](provide-coaching.md) with yourself or others as the coach. |
| Evaluation forms - review evaluations - Create | EvaluationReviews.Create | Perform evaluation reviews. |
| Evaluation forms - review evaluations - View | EvaluationReviews.View | View evaluation review drafts before they are finalized. |
| Evaluation forms - request evaluation reviews | EvaluationReviewRequest.View EvaluationReviewRequest.Create EvaluationReviewRequest.Delete | [Request evaluation reviews](evaluation-review-requests.md) if the evaluation form has review requests enabled. |
| Voice ID - attributes and search | VoiceIdAttributesAndSearch.View | Search for and view Voice ID results on the **Contact detail** page. |
| Forecasting - View | Forecasting.View | [Review contact volume and average handle time forecasts](inspect-forecast.md). |
| Forecasting - Edit | Forecasting.Edit | [Create and edit contact volume and average handle time forecasts](create-forecasts.md). |
| Forecasting - Publish | Forecasting.Publish | [Publish a forecast in Amazon Connect](publish-forecast.md). |
| Capacity planning - View | Capacity.View | [Review capacity plan output in Amazon Connect](capacity-planning-review-output.md). |
| Capacity planning - Edit | Capacity.Edit | [Create capacity planning scenarios in Amazon Connect](capacity-planning-create-scenarios.md). |
| Capacity planning - Publish | Capacity.Publish | [Publish a capacity plan in Amazon Connect](publish-capacity-plan.md). |
| Forecast and schedule interval - Edit and View | ForecastScheduleInterval.Edit ForecastScheduleInterval.View | [Set the forecast and schedule interval in Amazon Connect](set-forecast-scheduling-interval.md). |
## Recordings and Transcripts
| UI name | API name | Use |
| --- | --- | --- |
| Call recordings (unredacted) - Access | CallRecordings.Unredacted.Access | On the **Contact details** and **Contact search** pages for a contact, view unredacted audio recordings. If you have BOTH **Call recordings (unredacted) - Access** and **Call recordings (redacted) - Access** permissions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) You cannot access both the redacted and unredacted version of a conversation at the same time. |
| Call recordings (redacted) - Access | CallRecordings.Redacted.Access | On the **Contact details** and **Contact search** pages for a contact, listen to call recordings in which the sensitive data has been redacted. |
| Contact transcripts (unredacted) - Access | ContactTranscripts.Unredacted.Access | On the **Contact details** and **Contact search** pages for a contact, view unredacted chat and email conversations, and unredacted voice transcripts produced by Contact Lens. If you have BOTH **Contact transcripts (unredacted) - Access** and **Contact transcripts (redacted) - Access** permissions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) You cannot access both the redacted and unredacted version of a conversation at the same time. |
| Contact transcripts (redacted) - Access | ContactTranscripts.Unredacted.Access | On the **Contact details** and **Contact search** pages for a contact, view chat and voice transcripts in which the sensitive data has been redacted. |
| Call recordings (unredacted) - Enable download button | CallRecordings.Unredacted.DownloadButton | Enables buttons to download call recordings when user is viewing the unredacted recording on the **Contact Search** and **Contact Details** pages. The **Enable download button** permission is selected by default when you select **Call recordings (unredacted)** permission, so the user can [download call recordings](download-recordings.md) through the Amazon Connect admin website. This permission only controls the ability to view the download button. The user may still be able to download the contact recording without this permission if they have the **Call recordings (unredacted) - Access** permission. |
| Call recordings (redacted) - Enable download button | CallRecordings.Redacted.DownloadButton | Enables buttons to download call recordings when user is viewing the redacted recording on the **Contact Search** and **Contact Details** pages. The **Enable download button** permission is selected by default when you select **Call recordings (redacted)** permission, so the user can [download call recordings](download-recordings.md) through the Amazon Connect admin website. This permission only controls the ability to view the download button. The user may still be able to download the contact recording without this permission if they have the **Call recordings (redacted) - Access** permission. |
| Contact transcripts (unredacted) - Enable download button | ContactTranscripts.Unredacted.DownloadButton | Enables buttons to download contact transcripts when user is viewing the unredacted transcript on the **Contact Search** and **Contact Details** pages. The **Enable download button** permission is selected by default when you select **Contact transcripts (unredacted)** permission so the user can [download call recordings](download-recordings.md) through the Amazon Connect admin website. This permission only controls the ability to view the download button. The user may still be able to download the contact transcript without this permission if they have the **Contact transcript (unredacted) - Access** permission. A button appears on the **Contact Search** and **Contact Details** pages to download unredacted transcripts for chat and email. |
| Delete recorded conversations | DeleteCallRecordings | Delete call recordings and contact transcripts |
| Screen recording - Access | ScreenRecording.Access | Access the screen recording media player and view videos on the Contact details page. Screen recording merges the screen recording video with the unredacted call recording file. If users have permission to view screen recordings, they can listen to the unredacted audio. |
| Automated interaction voice (IVR) recordings (unredacted) - Access | AutomatedVoiceInteraction.Recordings.Unredacted.Access | Access voice recordings of automated interactions (with IVR, Amazon Lex or other bots). View the Play icon so users can listen to prompts while reviewing the automated interaction logs on the Amazon Connect admin website. |
| Automated interaction voice (IVR) recordings (unredacted) - Enable download button | AutomatedVoiceInteraction.Recordings.Unredacted.DownloadButton | Enables buttons to download and delete call recordings. The **Enable download button** permission is selected by default when you select the **Automated interaction voice (IVR) recordings** permission so the user can [download call recordings](download-recordings.md) through the Amazon Connect admin website. To perform a download, however, the user needs the **Automated interaction voice (IVR) recordings (unredacted) - Access** permission. |
| Automated interaction voice (IVR) transcripts (unredacted) | AutomatedVoiceInteraction.Transcripts.Unredacted.Access | Access human-readable logs of the IVR interaction including keypad inputs in response to IVR prompts, transcripts of Amazon Lex interactions, and more, on the **Contact details** and **Contact search** pages. |
## Legacy permissions
The following table lists legacy permissions. You can not access these permissions through the Security Profiles page.
Existing security profiles that have these permissions will continue to work. However, note the following functionality:
+ When you edit a security profile that contains legacy permissions, Amazon Connect automatically migrates the legacy permissions to the new corresponding permissions when you choose **Save** on the **Security Profiles** page.
+ You can still add legacy permissions to security profiles by using the [CreateSecurityProfile](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateSecurityProfile.html) and [UpdateSecurityProfile](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateSecurityProfile.html) APIs.
| UI name | API name | Use |
| --- | --- | --- |
| Recorded conversations (redacted) - View | RedactedData.View | On the **Contact Details** and **Contact Search** pages for a contact, listen to call recording files and view call transcripts in which the sensitive data has been removed. If you edit a security profile containing the **Recorded conversations (redacted) - View** permission, it will automatically be migrated to contain the new corresponding permissions (**Call recordings (redacted) - Access** and **Contact transcripts (redacted) - Access**) when you choose **Save** on the **Security Profiles** page. To grant access to redacted recorded conversations: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) You can access both newly migrated permissions in the **Recordings and Transcripts** section of the **Security Profiles** page. |
| Recorded conversations (unredacted) - View | ListenCallRecordings | On the **Contact details** and **Contact search** pages for a contact, view unredacted content that contains sensitive data, such as name and credit card information. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) If you edit a security profile containing the **Recorded conversations (unredacted) - View** permission, it will automatically be migrated to contain the new corresponding permissions (**Call recordings (unredacted) - Access** and **Contact transcripts (unredacted) - Access**) when you choose **Save** on the **Security Profiles** page. To grant access to unredacted recorded conversations: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) You can access both newly migrated permissions in the **Recordings and Transcripts** section on the **Security Profiles** page. If you have both **Recorded conversations (redacted) - Access** and **Recorded conversations (unredacted) - Access** permissions, then: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) You cannot access both the redacted and unredacted version of a conversation at the same time. |
| Recorded conversations - Enable download button | DownloadCallRecordings | Enables buttons on the Amazon Connect admin website to download and delete call recordings. By default, the **Enable download button** permission is granted so the user can [download call recordings](download-recordings.md) through the Amazon Connect admin website. To perform a download, however, the user needs permissions to access a **Recorded conversation (unredacted)**. If you edit a security profile that contains the **Recorded conversations (unredacted) - Enable download button** permission, it is automatically migrated to contain the new corresponding permissions (**Call recordings (unredacted) - Enable download button**, **Call recordings (redacted) - Enable download button**, and **Contact transcripts (unredacted) - Enable download button**) when you choose **Save** on the **Security Profiles** page. To enable the download button for recorded conversations: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/security-profile-list.html) All newly migrated permissions are located in the **Recordings and Transcripts** section on the **Security Profiles** page. |
## Contact Actions
| UI name | API name | Use |
| --- | --- | --- |
| Allow 'Assign to Me' for any contact | ManualAssignAnyContact.Enable | This permission allows an Agent to View and manually assign any Contacts that are part of the Manual Assignment Queue. |
| Allow 'Assign to Me' for my contacts | ManualAssignMyContacts.Enable | This permission allows an Agent to View and manually assign any contacts that are part of the Manual Assignment Queue and the Agent is one of the Preferred Agents on the Contact. |
| Transfer Contact | TransferContact.Enabled | [Transfer contacts on Analytics and optimization pages](transfer-contacts-admin.md). Currently transfer of task contacts to quick connects is supported on the **Contact details** page. |
| End contact | StopContact.Enabled | [End contacts on Analytics and optimization pages](end-contacts-admin.md). Currently supported on the **Contact details** page. |
| Reschedule contact | UpdateContactSchedule.Enabled | [Reschedule previously scheduled contact on Analytics and optimization pages](reschedule-contacts-admin.md). Currently supported on the **Contact details** page for task contacts only. |
## Historical changes
| UI name | API name | Use |
| --- | --- | --- |
| View historical changes | HistoricalChanges.View | View historical changes on all Amazon Connect admin website pages that support historical changes. |
## Customer Profiles
| UI name | API name | Use |
| --- | --- | --- |
| Customer profiles - Create | CustomerProfiles.Create | [Create customer profiles in the agent application](ag-cp-create.md). |
| Customer profiles - Edit | CustomerProfiles.Edit | Edit customer profiles in the agent application. |
| Customer profiles - View | CustomerProfiles.View | View customer profiles in the agent application. |
| Calculated Attributes - Create | CustomerProfiles.CalculatedAttributes.Create | [Create calculated attributes](calculated-attributes-admin-website-create.md). |
| Calculated Attributes - Edit | CustomerProfiles.CalculatedAttributes.Edit | [Edit calculated attributes](calculated-attributes-admin-website-edit.md). |
| Calculated Attributes - Delete | CustomerProfiles.CalculatedAttributes.Delete | [Delete calculated attributes](calculated-attributes-admin-website-delete.md). |
| Calculated Attributes - View | CustomerProfiles.CalculatedAttributes.View | [View calculated attributes](calculated-attributes-admin-website-view.md). |
| Customer segments - View | CustomerProfiles.Segments.View | View all customer created segments. You can see segment details, the definitions that were created, and segment estimate counts. |
| Customer segments - Create | CustomerProfiles.Segments.Create | Create segment definitions based on all profile attributes on a Customer Profiles domain associated with this instance. `Create` permissions allow creating definitions based on existing profile attributes and their values. You can also use default and created calculated attributes in the segment definition. |
| Customer segments - Delete | CustomerProfiles.Segments.Delete | `Delete` permissions allows you to delete your Segment Definition. |
| Customer segments - Export | CustomerProfiles.Segments.Export | Export allows you to create an exported CSV of all the profile data from profiles in that segment. It also allows you to view underlying profile data once exported. |
| Profile explorer - View | CustomerProfiles.ProfileExplorer.View | View the profile explorer landing page and the default Domain layout. |
| Profile explorer - Create | CustomerProfiles.ProfileExplorer.Create | [Create a Domain layout](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-customer-profiles_CreateDomainLayout.html) |
| Profile explorer - Edit | CustomerProfiles.ProfileExplorer.Edit | [Edit a Domain layout](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-customer-profiles_UpdateDomainLayout.html) |
| Profile explorer - Delete | CustomerProfiles.ProfileExplorer.Delete | [Delete a Domain layout](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-customer-profiles_DeleteDomainLayout.html) |
## Scheduling
| UI name | API name | Use |
| --- | --- | --- |
| Schedule manager - View | Scheduling.View | [View generated staff schedules in the Schedule manager user experience](scheduling-publish-schedule.md). |
| Schedule manager - Edit | Scheduling.Edit | [Create, edit schedule configuration and publish generated staff schedules](scheduling-publish-schedule.md). |
| Schedule manager - Publish | Scheduling.Publish | [Publish a schedule](scheduling-publish-schedule.md) by using Schedule Manager. |
| Published schedule calendar | Scheduling.View | [View](scheduling-view-schedule-staff.md) a schedule. |
| Time off requests - Approve, Edit, View | TimeOff.Approve TimeOff.Edit TimeOff.View | [Time off management](scheduling-time-off.md). |
| Time off balance - Edit, View | TimeOffBalance.Edit TimeOffBalance.View | [Time off management](scheduling-time-off.md). |
| Team calendar | TeamCalendar.View | [View published staff schedules in the Published Calendar user experience](scheduling-view-schedule-supervisors.md). |
| Team calendar | TeamCalendar.Edit | [Edit published staff schedules in the Published Calendar user experience](scheduling-view-schedule-supervisors.md). |
## Agent Applications
| UI name | API name | Use |
| --- | --- | --- |
| Agent application schedule calendar | StaffCalendar.View StaffCalendar.Edit | [Ability for agents to view their schedules](scheduling-view-schedule-agents.md). The **Edit** permission is required for agents to view and use the **Time off **widget on their schedule that they use to request time off. If they only have **View** permission, the **Time off** widget will not appear on their schedule. For an example image that shows the **Time off** widget on an agent's schedule, see [Agent initiated time off request](create-time-off-to.md#to-agent). |
| Custom views | CustomViews.Access | Use the [Agent Workspace guided experience](step-by-step-guided-experiences.md) guide. |
| Connect AI agents | Wisdom.View | [View real-time recommendations in the agent application](use-realtime-recommendations.md). |
| *<3p app name* - Access | *<3p app name*.Access | Allows agents to access a third-party application. |
| *Performance metrics* - Access | Analytics.PerformanceMetrics.Access | Displays the **Performance metrics** option in the **Apps** dropdown menu in the agent workspace. For more information, see [Agent workspace performance dashboard](performance-dashboard-aw.md). |
| *Worklist* - Access | ManualAssignAnyContact.Enable ManualAssignMyContacts.Enable | Allows Agents to view the Worklist App that will display Contacts that can be Manually assigned. |
## Content Management
| UI name | API name | Use |
| --- | --- | --- |
| Message templates - View | | View a list of message templates in the Amazon Connect admin website. |
| Message templates - Edit | | Edit message templates. |
| Message templates - Create | | Create message templates. |
| Message templates - Delete | | Delete message templates by using the Amazon Connect admin website. |
| Quick responses - Create | ContentManagement.Create | [Set up a knowledge base to store quick responses](setup-knowledgebase.md). [Create](create-quick-responses.md), [import](add-data.md), and [view the import history](view-import-history.md) of quick responses that are displayed in the agent application. |
| Quick responses - Edit | ContentManagement.Edit | [Edit](edit-quick-responses.md), [import](add-data.md), and [view the import history](view-import-history.md) of quick responses that are displayed in the agent application. |
| Quick responses - View | ContentManagement.View | View a list of quick responses in the Amazon Connect admin website. |
| Quick responses - Delete | ContentManagement.Delete | [Delete quick responses](delete-qr.md) by using the Amazon Connect admin website. |
## Cases
| UI name | API name | Use |
| --- | --- | --- |
| Audit History - View | CaseHistory.View | View the audit history of cases in the agent application. |
| Cases - Create | Cases.Create | [Create cases in the agent application](create-cases.md). |
| Cases - View | Cases.View | View cases in the agent application. |
| Cases - Edit | Cases.Edit | Edit cases in the agent application. |
| Case Fields - Create | CaseFields.Create | [Create case fields](case-fields.md). |
| Case Fields - View | CaseFields.View | View case fields. |
| Case Fields - Edit | CaseFields.Edit | Edit case fields. |
| Case Templates - Create | CaseTemplates.Create | [Create case templates](case-templates.md). |
| Case Templates - View | CaseTemplates.View | View case templates. |
| Case Templates - Edit | CaseTemplates.Edit | Edit case templates. |
## Outbound Campaigns
| UI name | API name | Use |
| --- | --- | --- |
| Campaigns - Create | Campaigns.Create | [Create outbound campaigns](how-to-create-campaigns.md). |
| Campaigns - Delete | Campaigns.Delete | Delete outbound campaigns. |
| Campaigns - Edit | Campaigns.Edit | Edit outbound campaigns. |
| Campaigns - Manage | Campaigns.Delete | Manage outbound campaigns. |
| Campaigns - View | | View outbound campaigns. |
# Default security profiles in Amazon Connect
Amazon Connect includes default security profiles for general roles. You can review the permissions granted by these profiles and use them if they align with the permissions that your users need. Otherwise, create a security profile that grants your users only the permissions they need.
The following table lists the default security profiles.
| Security profile | Description |
| --- | --- |
| **Admin** | Grants administrators permission to perform a majority of actions. |
| **Agent** | Grants agents permission to access the CCP. |
| **CallCenterManager** | Grants managers permission to perform actions related to user management, metrics, and routing. |
| **QualityAnalyst** | Grants analysts permission to perform actions related to metrics. |
**Note**
New permissions are added on a regular basis. We recommend revisiting your permission configurations to ensure your users can access the latest Amazon Connect features.
# Assign a security profile for Amazon Connect to a contact center user
## Required permissions to assign security profiles
Required permissions
Before you can assign a security profile to a user, you must be logged in with an Amazon Connect account that has the **Users - Edit** permission, as shown in the following image. Or, if you're creating the user's account for the first time, you need **Users - Create** permission.
![\[The users and permissions section of the security profiles page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/security-profile-assign-security-profile.png)
By default, the Amazon Connect **Admin** security profile has these permissions.
## How to assign security profiles
How to assign security profiles
1. Review [Best practices for Amazon Connect and Contact Control Panel (CCP) security profiles](security-profile-best-practices.md).
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/.
1. Choose **Users**, **User management**.
1. Select one or more users and choose **Edit**.
1. For **Security Profiles**, add or remove security profiles as needed. To add a security profile, put your cursor in the field and select the security profile from the list. To remove a security profile, click the **x** next to its name.
1. Choose **Save**.
# Create a security profile in Amazon Connect
Creating a security profile enables you to grant your users only the permissions that they need.
For each permission group, there is a set of resources and supported set of actions. For example, users are part of the **Users and permissions** group, which supports the following actions: view, edit, create, remove, enable/disable, and edit permission.
Some actions depend on other actions. When you choose an action that depends on another action, the dependent action is automatically chosen and must also be granted. For example, if you add permission to edit users, we also add permission to view users.
## Required permissions to create security profiles
Required permissions
Before you can create a new security profile, you must be logged in with an Amazon Connect account that has **Security profiles - Create** permissions, as shown in the following image.
![\[The users and permissions section of the security profiles page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/security-profile-create.png)
By default, the Amazon Connect **Admin** security profile has these permissions.
## How to create security profiles
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/.
1. Choose **Users**, **Security profiles**.
1. Choose **Add new security profile**.
1. Type a name and description for the security profile.
1. Choose the appropriate permissions for the security profile from each permission group. For each permission type, choose one or more actions. Selecting some actions results in other actions being selected. For example, selecting **Edit** also selects **View** for the resource and any dependent resources.
1. Choose **Save**.
## Tag-based access controls
Tag-based access controls
You create a security profile with access control tags. Use these steps to create a security profile that enforces tag-based access controls.
1. Choose **Show advanced settings** at the bottom of the security profile.
1. In the **Access control** section, in the **Resources** box, enter the resources to be restricted using tags.
![\[The access control section of the security profile page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-access-control-sp.png)
1. Enter the **Key** and **Value** combination for the resource tags that you want to restrict access to.
1. Ensure that you have enabled *View* permissions for the resources that you have selected.
1. Choose **Save**.
**Note**
It is mandatory to specify both a resource type and an access control tag when configuring tag-based access controls. As a best practice, ensure that you have matching resource tags on a security profile that has tag-based access controls configured. To learn more about tag-based access controls in Amazon Connect, see [Apply tag-based access control in Amazon Connect](tag-based-access-control.md).
## Tag security profiles
Tag security profiles
You can create a new security profile with resource tags. Use these steps to add a resource tag to a security profile.
1. Choose **Show advanced settings** at the bottom of the security profile.
1. Enter a **Key** and **Value** combination to tag the resource, as shown in the following image.
![\[The tags section of the security profiles page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tag-securit-profiles-sp.png)
1. Choose **Save**.
For more information about tagging resources, see [Add tags to resources in Amazon Connect](tagging.md).
# Update security profiles in Amazon Connect
You can update a security profile at any time to add or remove permissions.
## Required permissions to update security profiles
Required permissions
Before you can update permissions in a security profile, you must be logged in with an Amazon Connect account that has the following permissions: **Security profiles - Edit**.
![\[The users and permissions section of the security profiles page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/security-profile-edit.png)
By default, the Amazon Connect **Admin** security profile has these permissions.
## How to update security profiles
How to update security profiles
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. You must be logged in with an Amazon Connect account that has permissions to update security profiles.
1. Choose **Users**, **Security profiles**.
1. Select the name of the profile.
1. Update the name, description, permissions, access control, and resource tags as needed.
1. Choose **Save**.
**Note**
Modifying the access control or resource tags on a security profile may impact the features or resources that a user with this security profile can access.
# Apply tag-based access control in Amazon Connect
Apply tag-based access control
You use tag-based access controls to configure granular access to specific resources based on assigned resource tags. You can configure tag-based access controls by using the API/SDK or the Amazon Connect admin website for supported resources.
## Apply tag-based access control using the API/SDK
Apply tag-based access control using the API/SDK
To use tags to control access to resources within your AWS accounts, you need to provide tag information in the condition element of an IAM policy. For example, to control access to your Voice ID domain based on the tags you've assigned to it, use the `aws:ResourceTag/key-name` condition key, along with a specific operator like `StringEquals` to specify which tag *key:value* pair must be attached to the domain, in order to allow given actions for it.
For more detailed information on tag-based access control, see [Controlling access to AWS resources using tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*.
## Apply tag-based access control using the Amazon Connect admin website
Apply tag-based access control using the Amazon Connect admin website
A *resource* tag is a custom metadata label that you can add to a resource in order to make it easier to identify, organize, and find in a search. You can apply tags programmatically using the Amazon Connect SDK/APIs, and for certain resources you can apply tags from within the Amazon Connect console. To learn more about resource tags, see [Add tags to resources in Amazon Connect](tagging.md).
An access control tag is similar to a resource tag in that it uses the same *Key:value* structure. However, the distinction with an access control tag is that it introduces authorization controls that limit a user’s access, to only specified resources containing resource tags with identical *Key:value* pairs. Access control tags are defined within security profiles, by first selecting the resource (routing profile, queue, users, etc.) for which to control access to, and then defining the *Key:value* pair to match on. Once a security profile with access control tags has been applied to a user, it will limit the user's access based on the defined combination of the selected resource(s) and access control tag(s) (*Key:value*). Without access control tags applied, a user will be able to see all resources if given permission to do so.
To use tags to control access to resources within the admin website of your Amazon Connect instance, you need to configure the access control section within a given security profile. For example, to control access to a routing profile based on the tags you've assigned to it, you would specify the routing profile as an access controlled resource, and then specify which tag *Key:value* pair you would like to enable access to.
## Configuration limitations
Configuration limitations
Access control tags are configured on a security profile. You can configure up to 4 access control tags on a single security profile. Adding additional access control tags will make that security profile more restrictive. For example, if you were to add two access control tags like `Department:X` and `Country:Y`, the user would only be able to see resources containing both tags.
Users can be assigned a maximum of three security profiles that contain access control tags. When multiple security profiles containing access control tags are assigned to a single user, the tag-based access controls become less restrictive. For example, if a user had one security profile with an access control tag like `Country:USA`, and another security profile with an access control tag like `Country:Argentina`, a user would be able to see resources tagged with `Country:USA` or `Country:Argentina`. A user can have other security profiles, as long as those additional security profiles do not contain tags. If multiple security profiles are present with overlapping resource permissions, the security profile without tag-based access controls will be enforced over the one with tag-based access controls.
Service linked roles are required in order to configure [resource tags](https://docs.aws.amazon.com/connect/latest/adminguide/tagging.html) or [access control tags](https://docs.aws.amazon.com/connect/latest/adminguide/tag-based-access-control.html). If your instance was created after October 2018, this will be available by default with your Amazon Connect instance. However if you have an older instance, refer to [Use service-linked roles for Amazon Connect](https://docs.aws.amazon.com/connect/latest/adminguide/connect-slr.html) for instructions for how to enable service linked roles.
## Best practices for applying tag-based access controls
Best practices
Applying tag-based access controls is an advanced configuration feature that is supported by Amazon Connect and that follows the AWS shared responsibility model. It is important to ensure that you are correctly configuring your instance to comply with your desired authorization needs. For more information, review the [AWS shared responsibilities model](https://aws.amazon.com/compliance/shared-responsibility-model/).
Ensure that you have enabled at least *view* permissions for the resources that you enable tag-based access control for. This will ensure that you avoid permission inconsistencies that result in denied access requests.
Tag-based access controls are enabled at the resource level, which means that each resource can be restricted independently. In certain use cases this may be acceptable but it is considered best practice to enable tag-based access controls to all resources together. For example, enabling access to users but not security profiles, would allow a user to create a security profile with privileges that supersede your intended user access control settings.
When logged in to the Amazon Connect console with tag-based access controls applied, users will not be able to access historical change logs for the resources that they are restricted on.
As a best practice, you should disable access to the following resources/modules when applying tag-based access controls within the Amazon Connect console. If you do not disable access to these resources, users with tag-based access controls on a particular resource that view these pages may see an unrestricted list of users, security profiles, routing profiles, queues, flows, or flow modules. For more information on how to manage permissions, see [List of security profile permissions in Amazon Connect](security-profile-list.md).
| Modules | Permission to disable access |
| --- | --- |
| Contact search | Contact Search |
| Dashboard | Access metrics |
| Flows | Flows - View |
| Flow modules | Flow modules - View |
| Forecasting | Forecasting |
| Historical changes/Audit portal | Access metrics |
| Hours of operation | Hours of operation - View |
| Login/Login out report | Login/Logout report - View |
| Outbound Campaign | Campaigns - View |
| Prompts | Prompts - View |
| Quick connect | Quick connects - View |
| Rules | Rules - View |
| Saved reports | Saved reports - View |
| Scheduling | Schedule manager |
| Scheduling | Published schedule calendar |
# Apply hierarchy-based access control in Amazon Connect
Apply hierarchy-based access control
You can restrict access to contacts based on the agent hierarchy assigned to a user. You do this by using security profile permissions such as [Restrict contact access](contact-search.md#required-permissions-search-contacts). In addition to these permissions, you can also use hierarchies enforce granular access controls for resources such as users, and use tags.
This topic information about configuring hierarchy-based access controls.
**Topics**
+ [
## Overview
](#hierarchy-based-access-control-background)
+ [
## Apply hierarchy-based access control using the API/SDK
](#hierarchy-based-access-control-api-sdk)
+ [
## Apply hierarchy-based access control using the Amazon Connect admin website
](#hierarchy-based-access-control-console)
+ [
## Configuration limitations
](#hierarchy-based-access-control-config-limitations)
+ [
## Best practices for applying hierarchy-based access controls
](#hierarchy-based-access-control-best-practices)
## Overview
Hierarchy-based access control enables you to configure granular access to specific resources based on the [agent hierarchy](agent-hierarchy.md) that is assigned to a user. You can configure hierarchy-based access controls by using the API/SDK or the Amazon Connect admin website.
The only resource that supports hierarchy-based access control is users. This authorization model works with [tag-based access control](tag-based-access-control.md) so you can restrict access to users, allowing them to see only other users who belong to their same hierarchy group and who have specific tags associated to them.
**Note**
After you apply hierarchy-based access control to users, they can access their hierarchy group and all of its descendants (beyond the child level).
## Apply hierarchy-based access control using the API/SDK
To use hierarchies to control access to resources within your AWS accounts, you need to provide the hierarchy's information in the condition element of an IAM policy. For example, to control access to a user belonging to a specific hierarchy, use the `connect:HierarchyGroupL3Id/hierarchyGroupId` condition key, along with a specific operator like `StringEquals` to specify which hierarchy group the user must belong to, in order to allow given actions for it.
Following are the supported condition keys:
1. `connect:HierarchyGroupL1Id/hierarchyGroupId`
1. `connect:HierarchyGroupL2Id/hierarchyGroupId`
1. `connect:HierarchyGroupL3Id/hierarchyGroupId`
1. `connect:HierarchyGroupL4Id/hierarchyGroupId`
1. `connect:HierarchyGroupL5Id/hierarchyGroupId`
Each key represents the ID of a given hierarchy group in a specific level of the user's hierarchy structure.
## Apply hierarchy-based access control using the Amazon Connect admin website
To use hierarchies to control access to resources the Amazon Connect admin website, you configure the access control section within a given security profile.
For example, to enable granular access control for a given user based on the hierarchy they belong to, you configure the user as an access controlled resource. To do this, you have the following two options:
1. Enforce hierarchy-based access control based on **the user's hierarchy**
This option ensures that the user being given access can only manage users that belong to this hierarchy. For example, enabling this configuration for a given user enables them to manage other users that either belong to their hierarchy group or a child hierarchy group.
1. Enforce hierarchy-based access control based on **a specific hierarchy **
This option ensures that the user being given access can only manage users that belong to the hierarchy defined in the security profile. For example, enabling this configuration for a given user enables them to manage other users that either belong to the hierarchy group specified in the security profile or a child hierarchy group.
## Configuration limitations
Granular access control is configured on a security profile. Users can be assigned a maximum of two security profiles that enforce granular access control. In this case, the permissions become less restrictive and act as a union of both permission sets.
For example, if one security profile enforces hierarchy-based access control and another one enforces tag-based access control, the user is able to manage any user that belongs to the same hierarchy or tagged with the given tag. If both tag-based and hierarchy-based access control are configured as part of the same security profile, both conditions will need to be met. In this case, the user can only manage users that belong to the same hierarchy and who are tagged with a given tag.
A user can have more than two security profiles, as long as those additional security profiles do not enforce granular access control. If multiple security profiles are present with overlapping resource permissions, the security profile without hierarchy-based access control is enforced over the one with hierarchy-based access control.
Service linked roles are required in order to configure hierarchy-based access control. If your instance was created after October 2018, this is available by default with your Amazon Connect instance. However, if you have an older instance, refer to [Use service-linked roles for Amazon Connect](connect-slr.md) for instructions for how to enable service linked roles.
## Best practices for applying hierarchy-based access controls
+ Review the [AWS shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/).
Applying hierarchy-based access control is an advanced configuration feature that is supported by Amazon Connect and that follows the AWS shared responsibility model. It is important to ensure that you are correctly configuring your instance to comply with your desired authorization needs.
+ Ensure that you have enabled at least *view* permissions for the resources that you enable hierarchy-based access control for.
This will ensure that you avoid permission inconsistencies that result in denied access requests. Hierarchy-based access controls are enabled at the resource level, which means that each resource can be restricted independently.
+ Carefully review the permissions that are granted when hierarchy-based access control is enforced.
For example, enabling hierarchy restricted access to users and view/edit permissions security profiles would allow a user to create/update a security profile with privileges that supersede the intended user access control settings.
+ When logged in to the Amazon Connect console with hierarchy-based access controls applied, users will not be able to access historical change logs for the resources that they are restricted on.
+ When trying to assign a child resource to a parent resource with hierarchy-based access control on the child resource, the operation will be denied if the child resource does not belong to your hierarchy.
For example, if you try to assign a user to a quick connect but you don't have access to the user's hierarchy, the operation fails. This is however not true for disassociations. You are able to disassociate a user freely even with hierarchy-based access control enforced assuming you have access to the quick connect. This is because disassociations are about discarding an existing relation (as opposed to new associations) between two resources and is modeled as part of the parent resource (in this case, the quick connect), which the user already has access to.
+ Be thoughtful about the permissions granted on parent resources since users could be disassociated without their supervisor’s knowledge.
+ Disable access to the following functionality when you apply hierarchy-based access controls in the Amazon Connect admin website.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/hierarchy-based-access-control.html)
If you do not disable access to these resources, users with hierarchy-based access controls on a particular resource that view these pages in the Amazon Connect admin website may see an unrestricted list of users. For more information about how to manage permissions, see [List of security profile permissions](security-profile-list.md).
# Set up routing in Amazon Connect
Set up routing
In Amazon Connect, routing consists of three parts: queues, routing profiles, and flows. This topic discusses queues and routing profiles. For information about flows, see [Flows in Amazon Connect](connect-contact-flows.md).
A queue holds contacts waiting to be answered by agents. You can use a single queue to handle all incoming contacts, or you can set up multiple queues.
Queues are linked to agents through a routing profile. When you create a routing profile, you specify:
+ Which queues will be in it.
+ Whether one queue should be prioritized over another.
+ What channels agents will handle in the Contact Control Panel (CCP).
+ How many contacts agents can handle simultaneously for each channel.
+ Whether individual queues are for all channels or specific ones.
+ What channel and queue combinations will an agent be able to manually prioritize work from.
Each agent is assigned to one routing profile.
**Topics**
+ [How routing works](about-routing.md)
+ [Queues: standard and agent](concepts-queues-standard-and-agent.md)
+ [Queues: priority and delay examples](concepts-routing-profiles-priority.md)
+ [Queue-based routing](concepts-queue-based-routing.md)
+ [Channels and concurrency](channels-and-concurrency.md)
+ [Create a queue](create-queue.md)
+ [Disable a queue temporarily](disable-a-queue.md)
+ [Delete a queue](delete-queue.md)
+ [Set queue capacity](set-maximum-queue-limit.md)
+ [Route contacts based on queue capacity](route-based-on-queue-capacity.md)
+ [Set the hours of operation](set-hours-operation.md)
+ [Create a routing profile](routing-profiles.md)
+ [How Amazon Connect uses routing profiles](concepts-routing.md)
+ [Delete a routing profile](delete-routing-profiles.md)
+ [Set up queue-based routing](set-up-queue-based-routing.md)
+ [Set up routing based on agent proficiencies](proficiency-routing.md)
# How routing works in Amazon Connect
How routing works
Contacts are routed through your contact center based on these factors:
+ The routing profile assigned to the agent.
+ The hours of operation for a given queue.
+ The routing logic you define in your flows.
For example, you use routing profiles to route specific types of contacts to agents with specific skill sets. If no agent with the required skill set is available, you can place the contact in the queue defined in the flow.
Here's the logic Amazon Connect uses to route contacts:
+ Contacts in a queue are automatically prioritized and forwarded to the next available agent (that is, the agent who has been idle longest).
+ Contacts are placed on hold if there are no available agents. The order in which they are serviced is determined by their time in queue, on a first-come, first-served basis.
+ If multiple agents are ready for a contact, by default an inbound contact is routed to the agent who has been in the **Available** status for the longest time.
**Tip**
For information about how queue priority and delay work, see [Queues: priority and delay examples](concepts-routing-profiles-priority.md).
Handling either inbound or outbound contacts causes agents to drop to the bottom of the list for inbound contacts. You can set up your [routing profile](routing-profiles.md) to ignore outbound contacts in this calculation by choosing the **Outbound calls should not impact routing order** option. Consider choosing this option if your organization wants agents to take outbound calls and still get a fair share of inbound contacts.
For example:
+ An agent named Joe is idle. He is third in line to receive an inbound contact. He would rather handle an inbound contact than an outbound contact because he knows he will speak to a customer, whereas an outbound contact may not pick up the phone. Talking to an inbound contact increases his odds of getting recognition in his role.
+ Because he is idle, Joe decides to make an outbound contact to chip away at the backlog. He may or may not reach someone.
+ By default, when Joe makes the outbound contact, he moves from third in line to the bottom of the list of agents waiting to receive an inbound contact. (If there are 10 agents, he is moved to 10th place). If instead he should remain in third place, you can override the default behavior.
+ A routing profile may assign a priority to one queue over another, but the priority within the queue is always set by the order the contact was added to the queue.
+ If the contact belongs to a queue and channel combination that is **only** listed under the manually assigned section of a routing profile, that contact is **not** routed automatically to agents assigned to that routing profile.
## How routing transfers works
As the previous section explains, the order in which contacts in queue are handled in Amazon Connect depends on multiple factors, including the enqueue time, routing age adjustment, and contact priority. In the case of contacts that experience a transfer, however, Amazon Connect handles the routing age adjustment slightly differently: it depends on whether the contact was transferred by an agent, or if it was transferred by a queue-to-queue transfer in a flow or an API.
The following two scenarios demonstrate how Amazon Connect handles the routing age adjustment.
+ **Agent transfers the contact using a quick connect**: A contact is originally enqueued at time **X** and is then handled by an agent. The agent then transfers it back to a queue using a quick connect at time **Y**. In this scenario:
+ The original enqueue time **X** is used to calculate the order in which this contact is ranked in the subsequent queue.
+ Any routing age adjustments are applied relative to that contact enqueue time.
+ **Queue-to-queue transfer**: A contact was in a queue from time **S** and is eventually transferred to a different queue at time **T**. In this scenario:
+ The new enqueue time **T** is used to calculate the order in which the contact is ranked.
+ Any routing age adjustments are applied relative to that contact enqueue time.
## How routing works with multiple channels
When you set up a routing profile to handle multiple channels, you must specify whether agents can handle contacts while already on another channel. This is called cross-channel concurrency.
When using cross-channel concurrency, Amazon Connect checks which contact to offer the agent as follows:
1. It checks what contacts/channels the agent is currently handling.
1. Based on what channels they are currently handling, and the cross-channel configuration in the agent's routing profile, it determines whether the agent can be routed the next contact.
For a detailed example of how Amazon Connect routes contacts when cross-channel concurrency is set up, see [Example of how a contact is routed with cross-channel concurrency](routing-profiles.md#example-routing-concurrency).
## How routing works with manual assignment
When you set up a routing profile that has queues and channels listed for manual assignment, Amazon Connect does not automatically route these contacts.
Agents with this routing profile can view queued contacts (currently only supported for Tasks, Emails, and Chats) in the worklist app in their agent workspaces based on their security profile settings and determine the next important work item to assign to themselves.
## Learn more about routing
Learn more
See the following topics to learn more about routing:
+ [Queues: priority and delay examples](concepts-routing-profiles-priority.md).
+ [How Amazon Connect uses routing profiles](concepts-routing.md)
+ [Queue-based routing to route customers to a specific contact center agent](concepts-queue-based-routing.md)
+ [Set up queue-based routing](set-up-queue-based-routing.md)
# Standard queues and agent queues in your Amazon Connect contact center
Queues: standard and agent
There are two types of queues:
+ **Standard queues**: This is where contacts wait before they are routed to and accepted by agents.
+ **Agent queues**: These queues are created automatically when you add an agent to your contact center.
Contacts are only routed to agent queues when explicitly sent there as part of a flow. For example, you might route contacts to a specific agent who's responsible for certain customer issues, such as billing or premium support. Or you might use agent queues to route to an agent's voice-mail.
Contacts waiting in agent queues are higher priority than contacts waiting in standard queues. Contacts in agent queues have the highest priority and zero delay:
+ Highest priority: If there's another contact in the basic queue, Amazon Connect chooses to give the agent the contact from the agent queue first.
+ Zero delay: If the agent is available, the contact immediately gets routed to them.
## Queues in metrics reports
In a [real-time metrics report](real-time-metrics-reports.md), you can monitor how many contacts are in standard queues and agent queues. The following image shows a sample real-time metrics Queues report where an Agents table and Agent queues table have been added. It shows:
+ **BasicQueue**, which is a standard queue. It shows one agent (John) is online.
+ **Agents** table, which shows the agent John has set his CCP to **Available** and is ready to take contacts. A supervisor can change an agent's status from here. For example, set to **Offline**.
+ **Agent queues** table, which shows John's agent queue. It shows John is online and can take contact from this queue, too.
![\[A queues report with Agents table and Agent queues table.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/rtm-standard-and-agent-queues.png)
When an agent gets a contact from a standard queue, the contact never appears in the agent queue. It just goes directly to the agent.
In a [historical metrics report](historical-metrics.md), by default agent queues don't appear in a Queues table. To show them, choose the **Settings** icon, then choose **Show agent queues**.
![\[The agent queues dropdown menu on the Table settings page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hmr-queues-settings-agent-queues.png)
**Tip**
The metrics APIs don't support agent queues.
## Default queue: BasicQueue
Amazon Connect includes a default queue named **BasicQueue**. Along with the [default flows](contact-flow-default.md) and default routing profile (named **Basic routing profile**), it powers your contact center so you don't need to do any customization. This is what enables you to get started quickly.
# Queue priority and delay examples to help you load balance Amazon Connect contacts
Queues: priority and delay examples
This topic provides several example priority and delay settings for queues, and explains how contacts are routed in each scenario. Use these examples to load balance contacts using the priority and delay features.
## Example 1: Different priority but same delay
For example, one group of agents is assigned to a Sales routing profile. Since their primary job is sales, the Sales queue is Priority 1 and Delay is 0. But they can help with Support too, so that queue is Priority 2 and Delay is 0. This shown in the following table:
| Queue | Priority | Delay (in seconds) |
| --- | --- | --- |
| Sales | 1 | 0 |
| Support | 2 | 0 |
If there are no contacts in the Sales queue, then the agents will be presented with contacts from the Support queue.
## Example 2: Same priority but different delay
Say you set the Support queue to Priority 1 and Delay of 30 seconds, as shown in the following table:
| Queue | Priority | Delay (in seconds) |
| --- | --- | --- |
| Sales | 1 | 0 |
| Support | 1 | 30 |
These agents will always get contacts from the Sales queue first because the delay is 0. However, when a contact in the **Support** queue ages past 30 seconds, it will also be treated as priority 1. The agents will then be presented with the contact from the **Support** queue.
## Example 3: Different Priorities and Delays
Here's a more complicated example for a Support routing profile:
| Queue | Priority | Delay (in seconds) |
| --- | --- | --- |
| Tier 1 Support | 1 | 0 |
| Tier 2 Support | 1 | 0 |
| Tier 3 Support | 2 | 20 |
| Tier 4 Support | 3 | 80 |
This routing profile prioritizes the Tier 1 Support and Tier 2 Support queues equally because each is priority 1.
+ Agents may take contacts from the Tier 3 Support queue when:
+ Customers for Tier 3 Support are waiting for 20 seconds or longer.
+ And no contacts are in the Tier 1 Support or Tier 2 Support queues.
+ Agents may take contacts from the Tier 4 Support queue when:
+ Customers in the Tier 4 Support queue have been waiting 80 seconds or longer.
+ And no contacts are in the Tier 1 Support, Tier 2 Support or Tier 3 Support queues.
**Priority takes precedence**. (You might think that agents take contacts from Tier 4 Support when contacts are in Tier 1 Support, Tier 2 Support, or Tier 3 Support and waiting 20 seconds or longer, but that's not right.)
## Example 4: Same Priority and Delay
In this example a routing profile has only two queues, and they have the same priority and delay:
| Queue | Priority | Delay (in seconds) |
| --- | --- | --- |
| Sales | 1 | 0 |
| Support | 1 | 0 |
For this routing profile, the oldest contact is routed first. It goes to the agent who has been idle for the longest time.
## Example 5: Agent is idle and Contact is in 30 second delay queue
Let's say the agent is idle and the contact is in delay (for a 30 second delay queue, the contact is 15 seconds old). What happens?
The **Delay** setting in the routing profile means that X seconds must pass before this contact can be offered to agents with this routing profile. Whether the agents are idle or not isn't taken into account. So in this case, this agent isn't offered the contact until the contact is at least 30 seconds old.
## Example 6: Different routing profiles, same queues, different priorities
For example:
| Agent | Priority | Queue |
| --- | --- | --- |
| Agent A | 1 | 1 |
| Agent B | 5 | 1 |
+ **Both agents are available. Who will get the call? It depends ... **
+ Routing always attempts to route to the longest available agent first.
Agent A has a profile with Priority 1 for Queue 1, and Agent B has a profile with Priority 5 for Queue 1. Contact Z is added to Queue 1 while both agents are available. In this case, Contact Z will always be routed to whichever agent has been available for longer. If Agent B has been available longer, Contact Z will be routed to Agent B.
+ Priority for queues is relevant to searching for queues for an individual agent. It does not determine which agent out of multiple available agent will be routed contacts.
Let's say Contact Y is in Queue 2 and has been there longer than Contact Z in Queue 1. Agent A will be routed Contact Z even though it is newer. This is because Queue 1 has a higher priority in the agent's profile.
+ **Do Priority 5 agents get calls only when agents with higher priorities are not available? **
No. Priority 5 agents receive calls from that queue only if their other priority queues are empty. One agent's priority setting for a queue does not impact when the queue is routed a contact relative to other agents, but relative to other queues in the agent's profile.
For instructions on how to set priority and delay for a routing profile, see [Create a routing profile in Amazon Connect to link queues to agents](routing-profiles.md).
# Queue-based routing to route customers to a specific contact center agent
Queue-based routing
In your business, you might want to route customers to specific agents based on certain criteria, such as the skill of the agent. This is called queue-based routing, also known as skills-based routing.
For example, an airline might have some agents who handle reservations for English-speaking customers, others who handle Spanish-speaking customers, and a third group that handles both types of customers, but only over the phone.
The following illustration shows you can:
+ Assign the same routing profile to multiple agents.
+ Assign multiple queues to a routing profile.
+ Assign a queue to multiple routing profiles.
![\[A graphic of four routing profiles.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/routing-profile-example2.png)
For an overview of the steps to set up queue-based routing, see [Set up queue-based routing](set-up-queue-based-routing.md).
# Channels and concurrency for routing contacts in Amazon Connect
Channels and concurrency
Agents can handle voice, chat, tasks and email in Amazon Connect. When you set up a routing profile to handle multiple channels, you have two options:
+ Option 1: Set up agents so they can handle contacts while already on another channel. This is called *cross-channel concurrency*.
+ Option 2: Set up agents so they can be offered voice, chat, tasks, or email if they are fully idle, depending on what is in queue. When you choose this option, after the agent starts work on contacts from one channel they will no longer be offered contacts from any other channels.
When using cross-channel concurrency, Amazon Connect checks which contact to offer the agent as follows:
1. It checks what contacts/channels the agent is currently handling.
1. Based on what channels they are currently handling, and the cross-channel configuration in the agent's routing profile, it determines whether the agent can be routed the next contact.
1. Amazon Connect prioritizes the longest waiting contact if Priority and Delay are equal. Even though it's evaluating multiple channels at the same time, First-In First-Out is still respected.
For a detailed example of how Amazon Connect routes contacts when cross-channel concurrency is set up, see [Example of how a contact is routed with cross-channel concurrency](routing-profiles.md#example-routing-concurrency).
To learn more about what the agent experiences in the Contact Control Panel when handling multiple chats, see [Use the Contact Control Panel (CCP) in Amazon Connect to chat with contacts](chat-with-connect-contacts.md).
# Create a queue using the Amazon Connect admin website
Create a queue
This topic explains how to create a queue using the Amazon Connect admin website. To create queues programmatically, see the [create-queue](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/connect/create-queue.html) AWS CLI or [CreateQueue](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateQueue.html) in the *Amazon Connect API Reference*.
**How many queues can I create?** To view your quota of **Queues per instance**, open the Service Quotas console at [https://console.aws.amazon.com/servicequotas/](https://console.aws.amazon.com/servicequotas/).
**To create a queue**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account that has **Routing** - **Queues** - **Create** permission in its security profile.
1. On the Amazon Connect admin website, on the navigation menu, choose **Routing**, **Queues**, **Add new queue**.
1. Add the appropriate information about your queue and choose **Add new queue**.
The following image shows the queue information for the BasicQueue.
![\[The Edit queue page for the Basic queue.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/add-a-new-queue.png)
See the following topics for detailed information about each of the above areas:
1. [Set the hours of operation and time zone for a queue using Amazon Connect](set-hours-operation.md)
1. [Set up outbound caller ID in Amazon Connect](queues-callerid.md)
1. [Set up email in Amazon Connect](setup-email-channel.md)
1. [Set the limit of maximum contacts in a queue using Amazon Connect](set-maximum-queue-limit.md)
1. [Create quick connects in Amazon Connect](quick-connects.md)
The queue is automatically active.
1. Assign the queue to a routing profile; for information, see [Create a routing profile in Amazon Connect to link queues to agents](routing-profiles.md). The routing profile links the queue and agents together.
1. Add tags to identify, organize, search for, filter and control who can access this queue. For more information, see [Add tags to resources in Amazon Connect](tagging.md).
To learn how queues work, see [How Amazon Connect uses routing profiles](concepts-routing.md) and [Queue-based routing to route customers to a specific contact center agent](concepts-queue-based-routing.md).
## APIs to create and manage queues
APIs to create and manage queues
Use the following APIs to create and manage queues programmatically:
+ [CreateQueue](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateQueue.html)
+ [DeleteQueue](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeleteQueue.html)
+ [DescribeQueue](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeQueue.html)
+ [ListQueues](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListQueues.html)
+ [SearchQueues](https://docs.aws.amazon.com/connect/latest/APIReference/API_SearchQueues.html)
+ [UpdateQueueHoursOfOperation](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateQueueHoursOfOperation.html)
+ [UpdateQueueMaxContacts](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateQueueMaxContacts.html)
+ [UpdateQueueName](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateQueueName.html)
+ [UpdateQueueOutboundCallerConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateQueueOutboundCallerConfig.html)
+ [UpdateQueueOutboundEmailConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateQueueOutboundEmailConfig.html)
+ [UpdateQueueStatus](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateQueueStatus.html)
# Disable a queue temporarily using Amazon Connect
Disable a queue temporarily
You can quickly control the flow of contacts to queues by temporarily disabling a queue. When a queue is disabled, it's put in an offline mode. No new contacts are routed to the queue, but any existing contacts already in the queue are routed to agents.
Only users who have a security profile with **Routing** - **Queues** - ** Enable/Disable** permission can disable a queue.
![\[Security profile permissions table showing Queues row with Create checkbox selected.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/disable-queue.png)
**To temporarily disable an active queue**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account that has **Routing** - **Queues** - ** Enable/Disable** permission in its security profile.
1. On the Amazon Connect admin website, on the navigation menu, choose **Routing**, **Queues**.
1. For the queue you want to disable, toggle the **Status** to **Disabled**, as shown in the following image.
![\[The Queues page, the Status toggle.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/disable-queue-power-button.png)
1. Choose **Disable** to confirm you want to disable the queue, as shown in the following image. You can immediately re-enable the queue if needed by toggling the button back to **Enabled**.
![\[The Disable queue confirmation box.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/disable-queue-confirm.png)
# Delete a queue from your Amazon Connect instance
Delete a queue
There are three ways to delete a queue from your Amazon Connect instance:
+ Amazon Connect admin website
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account that has **Routing** - **Queues** - **Delete** permission in its security profile.
1. On the Amazon Connect admin website, on the navigation menu, choose **Routing**, **Queues** and then select the delete icon.
![\[The Queues page, the Status option and the Delete option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/delete-queue.png)
**Important**
You cannot undo a deleted queue. To temporarily disable a queue, toggle its status to **Disabled**.
+ [DeleteQueue](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeleteQueue.html) API
+ [delete-queue](https://docs.aws.amazon.com/cli/latest/reference/connect/delete-queue.html) AWS CLI
# Set the limit of maximum contacts in a queue using Amazon Connect
Set queue capacity
By default a queue can contain up to your [service quota](amazon-connect-service-limits.md) for voice, chat, tasks, and email:
+ **Concurrent active calls per instance**
+ **Concurrent active chats per instance (includes SMS)**
+ **Concurrent active tasks per instance**
+ **Concurrent active emails per instance**
To increase one of these quotas, you must request a quota increase. For more information, see [Amazon Connect service quotas](amazon-connect-service-limits.md).
There may be situations where you want a specific queue to allow fewer contacts than the allowed quota. For example:
+ You have a queue that is dedicated to calls about complicated issues that take an average of 15 minutes to resolve, you may want to limit the number of calls allowed in the queue to be less than **Concurrent active calls per instance**. This prevents customers from waiting for hours.
+ You may have a queue dedicated to chats. Your service quota is 100 but you want only up to 20 chats at a time. You can set that value so Amazon Connect limits the number of active chats routed to that queue.
+ You have a queue that combines more than one channel, and you set a custom value. Note that the queue stops accepting new contacts after that number is reached, regardless of the distribution of contacts. For example, if you set the value to 50, and the first 50 contacts are chats, then voice calls are not routed to this queue.
This topic explains how to reduce the allowed number of contacts in a queue for these situations.
## Reduce the number of contacts allowed in a queue
Reduce the number of contacts allowed in a queue
To reduce the number of contacts allowed in a [standard queue](concepts-queues-standard-and-agent.md) at the same time, you set the **Maximum contacts in queue** limit for the standard queue. This setting does not apply to [agent queues](concepts-queues-standard-and-agent.md).
![\[Option to set a maximum limit for contacts in queue across all channels.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/maximum-contacts-in-queue3.png)
When you enter a number in **Maximum contacts in queue**, Amazon Connect validates that the number is less than the sum of your concurrent active contacts service quotas: **Concurrent calls per instance** \$1 **Concurrent active chats per instance** \$1 **Concurrent active tasks per instance** \$1 **Concurrent active emails per instance**.
**Important**
You must set **Maximum contacts in queue** to be less than the sum of the following quotas combined: **Concurrent calls per instance** \$1 **Concurrent active chats per instance** \$1 **Concurrent active tasks per instance** \$1 **Concurrent active emails per instance**.
Incoming calls and queued callbacks count towards the queue size limit.
For information about default service quotas and how to request an increase, see [Amazon Connect service quotas](amazon-connect-service-limits.md).
**To reduce the number of contacts allowed in a specific queue**
1. On the navigation menu, choose **Routing**, **Queues**, **Add new queue**. Or, edit an existing queue.
1. In **Maximum contacts in queue**, choose **Set a limit across all channels**. If the queue is also used for chats, tasks, and email, then all channels will be capped at the same maximum.
1. In the box, specify how many contacts can be in the queue before it's considered full. The value cannot exceed the sum of **Concurrent active calls per instance** \$1 **Concurrent active chats per instance** \$1 **Concurrent active tasks per instance** \$1**Concurrent active emails per instance**.
![\[Input field for setting maximum contacts in queue, with a value of 7 displayed.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/maximum-contacts-in-queue2.png)
## What happens to calls when a queue is full
What happens to calls when a queue is full
+ Incoming calls: Ideally you've [set up queued callback](setup-queued-cb.md), or have another contingency implemented. If not, the next incoming call gets a reorder tone (also known as a fast busy tone), which indicates no transmission path to the called number is available.
+ Queued callbacks: The next queued callback is routed down the error branch.
## What happens if Maximum contacts in queue is set to 0
What happens if Maximum contacts in queue is set to 0
If you set **Maximum contacts in queue** to 0 it renders the queue unusable. The behavior is the same as when a queue is full.
## Queue maximum limit exceptions
Queue limit additional details
There are times when you can add more contacts to a queue than the set **Maximum contacts in queue** limit.
+ There may be a slight delay between the time that a queue reaches its capacity limit and when this limit is enforced in the flow. This delay could cause incoming contacts to be queued during that time, particularly during bursts of traffic.
Additionally, Amazon Connect includes a 20 percent buffer to the queue capacity for the following exceptional scenarios:
+ A contact was transformed into a Queued Callback, scheduled to be added to the queue at X time using the **Initial delay** setting in the flow. However, when the scheduled time arrived, the target queue had reached its **Maximum capacity in queue** limit. In this scenario, Amazon Connect allows the Queued Callback to be enqueued up to a 20 percent buffer of the **Maximum capacity in queue** limit for the queue.
+ A contact, previously queued in Queue1, is now being transferred to Queue2 through the flow. However, when the transfer is attempted, Queue2 has already reached its **Maximum capacity in queue** limit. In this scenario, Amazon Connect allows the transfer to proceed, up to a 20 percent buffer of the **Maximum capacity in queue** limit for Queue2.
+ An agent initiates a manual transfer of a contact into a queue through quick connects. However, when the transfer is attempted, the queue has already reached its **Maximum capacity in queue** limit. In this scenario, Amazon Connect allows the transfer to proceed, up to a 20 percent buffer of the **Maximum capacity in queue** limit.
# Route contacts based on queue capacity using Amazon Connect
Route contacts based on queue capacity
To define routing decisions based on queue capacity, use a [Transfer to queue](transfer-to-queue.md) block to check whether a queue is full ([Maximum contacts in queue](set-maximum-queue-limit.md)), and then route the contact accordingly.
The [Transfer to queue](transfer-to-queue.md) block checks the [Maximum contacts in queue](set-maximum-queue-limit.md). If no limit is set, the queue is limited to the number of total concurrent contacts for the following quotas:
+ Active tasks per instance
+ Concurrent active emails per instance
+ Concurrent calls per instance
+ Concurrent chats per instance
# Set the hours of operation and time zone for a queue using Amazon Connect
Set the hours of operation
This topic explains how to set hours of operating by using the Amazon Connect admin website. To set hours programmatically, see [Hours of operations actions](https://docs.aws.amazon.com/connect/latest/APIReference/hours-of-operation-api.html).
The first thing you need to do when you set up a queue is to specify the hours of operation and timezone. The hours may be referenced in flows. For example, when routing contacts to agents, you might use the [Check hours of operation](check-hours-of-operation.md) block first, and then route the contact to the appropriate queue.
![\[An Hours of operation page with overrides.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hoop-listpage.png)
**Topics**
+ [How many hours of operation and overrides can I create?](#howmany-hours)
+ [Set the hours of operation](#set-hoop)
+ [
## How to specify midnight
](#set-hours-operation-midnight)
+ [
## Examples
](#set-hours-operation-examples)
+ [
## Add lunch and other breaks
](#add-lunch-breaks)
+ [Daylight saving time](#daylight-savings-time)
+ [
## How flows leverage hours of operation
](#use-check-hours-of-operation-block)
+ [Set overrides for extended, reduced, and holiday hours](hours-of-operation-overrides.md)
+ [View calendar that illustrates effective hours of operation](view-hours-of-operation-calendar.md)
## How many hours of operation and overrides can I create?
How many hours of operation and overrides can I create?
To view your quota of **Hours of operation per instance**, open the Service Quotas console at [https://console.aws.amazon.com/servicequotas/](https://console.aws.amazon.com/servicequotas/).
## Set the hours of operation
Set the hours of operation
1. Log in to the Amazon Connect admin website with an Admin account or an account that has **Routing - Hours of operation - Create** security profile permission.
1. On the navigation menu, choose **Routing**, **Hours of operation**.
1. To create a set of operating hours, choose **Add new set of hours** and enter a name and a description.
1. Choose **Time zone** and select a value.
1. Choose **Operational hours** to set new hours.
1. Optionally, in the **Tags** section, add tags to identify, organize, search for, or filter who can access this hours of operation record. For more information, see [Add tags to resources in Amazon Connect](tagging.md).
1. Choose **Save**.
1. Now you can specify these the hours of operation when you [create a queue](create-queue.md), and check them in the [Check hours of operation](check-hours-of-operation.md) block.
## How to specify midnight
To specify midnight, enter 12:00AM.
For example, if you want to set your hours to 10:00AM to midnight, you would enter: 10:00AM to 12:00AM. Your call center would be open for 14 hours. Here's the math:
+ 10:00AM-12:00PM = 2 hours
+ 12:00PM-12:00AM = 12 hours
+ Total = 14 hours
## Examples
**Schedule for 24x7**
![\[An example of a weekly, 24-hour contact center schedule.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/set-hours-of-operation-24x7.png)
**Schedule for Monday to Friday 9:00 AM to 5:00 PM**
Select the button to **Expand to individual days**.
Remove Sunday and Saturday from the schedule.
![\[An example of removing days from a contact center schedule.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/set-hours-of-operation-closed-weekends-remove.png)
## Add lunch and other breaks
Select **\$1 Add more time** at the bottom of the Operational hours section to create more rows, then set the hour ranges within each day. For example, if Saturday the hours are 8-11 then 1-5:
![\[A diagram showing lunch breaks in a contact center schedule.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hours-of-operation-lunch.png)
In most contact centers breaks are staggered. While some agents are at lunch, for example, others are still available to handle contacts. Instead of specifying this in the hours of operation, you [add custom agent statuses](agent-custom.md) that appear in the agent's Contact Control Panel (CCP).
For example, you might create a custom status named **Lunch**. When the agent goes to lunch, they change their status in the CCP from **Available** to **Lunch**. During this time, no contacts are routed to them. When they return from lunch and are ready to take contacts again, they change their status back to **Available**.
Supervisors can change an agent's status using the real-time metrics report.
For more information, see these topics:
+ [Add a custom agent status to the Amazon Connect Contact Control Panel (CCP)](agent-custom.md)
+ [Agent status in the Contact Control Panel (CCP)](metrics-agent-status.md)
+ [Change the "Agent activity" status in a metrics report in the Contact Control Panel (CCP)](rtm-change-agent-activity-state.md)
## What happens during daylight saving time
Daylight saving time
Amazon Connect uses the timezone to determine whether daylight saving time is in effect for the queues, and **adjusts automatically** for all timezones that observe daylight saving time. When a contact comes in, Amazon Connect looks at the hours and timezone of your contact center to determine whether the contact can be routed to the given queue.
**Important**
Amazon Connect provides options for EST5EDT, PST8PDT, CST6CDT, and more. For example, EST5EDT is defined as:
[Eastern Standard Time (EST)](https://en.wikipedia.org/wiki/Eastern_Time_Zone) is used when observing standard time. It is five hours behind Coordinated Universal Time (UTC).
[Eastern Daylight Time (EDT)](https://en.wikipedia.org/wiki/Eastern_Time_Zone) is used when observing daylight saving time. It is four hours behind Coordinated Universal Time (UTC).
We recommend researching your choice of timezone to ensure you understand it.
### Example
Example
1. A person initiates a call or chat with your contact center.
1. Amazon Connect looks at the hours of operation for your call center right now.
+ The contact is from timezone A.
+ Your call center's hours are 9 AM - 5 PM in timezone B.
+ If the current time in timezone B is 2 PM then the call or chat is queued.
+ If the current time in timezone B is 7 AM then the call or chat is not queued.
## How flows leverage hours of operation
Flows can be configured to check whether a contact is within or outside the hours of operation defined by the block. The flow can then branch to follow a different path based on the results, for example, so a message plays after hours that offers a callback when operations resume. To learn more, go to [Check hours of operation](check-hours-of-operation.md).
# Identify dates where you need to override standard operating hours
Set overrides for extended, reduced, and holiday hours
You can override the standard operating hours for future dates where operations will be closed, have reduced hours, or will be open longer than normal.
**Note**
Up to 50 overrides can be created for each hours of operation resource. This quota is not adjustable.
**Create an override**
1. Navigate to the **Routing** menu and open **Hours of operation**.
1. Open a record by selecting its name.
1. In the **Overrides** section, select **Create**.
**Note**
If you have view-only permissions, you will not see this action.
1. Build your list of overrides by choosing between:
1. **Add recurring event** — Use for holidays and other dates that follow a repeating pattern (e.g. early closure the last Friday of every month).
1. **Create temporary hours** — Use for dates with non-standard hours that are not recurring and where the configured hours must supersede all other settings for that date/range.
1. **Copy from another Hours of Operation** - Use when it is helpful to pull together overrides already configured on other records, but you want the option to make changes (for example, to remove certain dates).
**Note**
Rather than setting up a list of dates and times directly, you can link to the overrides set up on a different Hours of operation resource. Use this approach if you wish to share a master list that is maintained in one place.
1. Follow the instructions on the window that opens.
1. Select **Apply** to commit your selected date(s) and hours.
1. Select **Save** at the top right of the hours of operation resource page.
![\[Hours of operations overrides table actions dropdown.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hours-of-operations-overrides.png)
**Recurring events**
If you choose recurring event:
1. Provide a meaningful **Name** for this override.
1. Select the **Effective dates** for this override.
**Note**
These dates are used by Flows to determine if this override should be considered. If today's date falls before or after this range, the override will be ignored.
1. Indicate if operations are **Closed** or **Open**.
1. Choose the **Recurrence pattern**. Based on your selections, you will be able to provide additional details.
In this example, operations are closed on a specific date each year, no matter what day of the week it falls on:
![\[Dialog to add a recurring event for any day of the week.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/add-annual-recurring-hours-of-operation-override.png)
In this example, extended hours have been set up for every other week:
![\[Dialog to add a recurring event for every other week.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/add-daily-recurring-hours-of-operation-override.png)
**Temporary hours**
If you choose temporary hours:
1. Provide a meaningful **Name** for this override.
1. Select the **Effective dates** for this override.
**Note**
These dates are used by Flows to determine if this override should be considered. If today's date falls before or after this range, the override will be ignored.
1. Select the **Hours** for the specified date(s), that will replace the standard day of the week schedule.
**Note**
Recurring open/closed overrides take precedence over temporary hours.
In this example, operations are only open every other day and for partial hours:
![\[Dialog to create temporary hours for every other day.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-temporary-hours-of-operations.png)
**Copy overrides**
If you choose **Copy from another Hours of Operations**:
1. Find the parent resource and select it.
1. Next, click to **Save link**.
![\[Dialog to copy overrides from a different hours of operation.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/copy-hours-of-operation-overrides.png)
After copying a list, the override records are *distinct from their source*. They are unaffected by changes made to that original list (for example, if Labor Day changes from closed to a half day).
**Note**
Copied overrides count towards the 50 override service quota.
**Note**
If you want to instead rely on a global list and ensure your override dates and times are automatically kept in sync, then follow instructions for *linking* rather than copying.
**Link overrides**
An alternative to setting up a list of overrides within an hours of operation record is to link to another resource that contains a master list. For example, you can set up a “parent” hours of operations to house a list of global corporate holidays, and another for regional blocked dates, and so on. Each “child” that is linked to a parent record inherits its overrides. As changes are made to the parent, the child automatically benefits without additional effort.
![\[Link overrides from a different hours of operation table.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/linked-hours-of-operations.png)
To create a link so overrides are inherited from another hours of operations:
1. Open a record and navigating to the **Linked hours of operations** section.
1. Select the button to **Add link**.
![\[Dialog to link overrides from a different hours of operation.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/link-hours-of-operation-overrides.png)
1. Choose the link mode titled **Inherit**.
1. Search for the hours of operation that will provide the source override list.
1. Select the **Save link** button.
1. Repeat as needed.
**Note**
Parent overrides do not count towards the 50 override service quota.
**Note**
A child can link to up to 3 parents. This quota is not adjustable.
**Note**
After an hours of operation record becomes a child, it cannot have children itself.
To create a link that shares overrides:
1. Open a record and navigating to the **Linked hours of operations** section.
1. Select the button to **Add link**.
1. Choose the link mode titled **Share**.
1. Search an hours of operation that you wish to provide overrides to.
1. Select the **Save link** button.
1. Repeat as needed.
**Note**
The number of children that can reference the same parent is not limited. All of the hours of operations in the instance can share the same parent override list.
**Note**
After an hours of operation record becomes a parent, it cannot have a parent itself.
The list of overrides in a linked list cannot be modified in any way from a child record. Changes can only be made from the parent record. If linkage is made in error, it can be removed.
If only a subset of users with permission to edit hours of operations should have access to a parent record, you can set up granular access control. For more information, see [Apply tag-based access control in Amazon Connect](tag-based-access-control.md).
**Dates with competing overrides**
There may be times where the overrides on a given hours of operation resource conflict with each other. Connect prioritizes the various types as follows:
1. Closed recurring overrides are considered first.
1. Open recurring overrides are considered next.
1. Temporary hours are considered next.
1. Standard day-of-the-week hours are considered last.
In the following example, there are numerous competing configurations, but because the recurring closed hours cover the entire day, the other overrides and operating hours are ignored. The contact center is closed for the full day.
![\[Hours of operation override example to close for the day.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hours-of-operation-overrides-example-1.png)
In a different example, the standard operating hours would normally not be open on a Sunday. However, this is a special exception, as the company prides itself on supporting its customers on one of the busiest shopping days of the year. In this case, the contact center is open from 10am - 10pm.
![\[Hours of operation override example to open on a normally closed day.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hours-of-operation-overrides-example-2.png)
In a final example, the contact center opens at 8am, then closes from noon to 4pm, then reopens for two hours before closing at 8pm.
![\[Hours of operation override example with multiple override types.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hours-of-operation-overrides-example-3.png)
**Note**
Test any configuration that will impact your customers, to be sure they produce the desired results.
**View audit history for overrides**
An audit history of overrides appears on the **Hours of operation** page, distinct from the standard hours of operations audit history. Each audit record refers to the ID of the related hours of operation record.
![\[Hours of operation overrides audit history table.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hours-of-operation-overrides-audit-history.png)
**Note**
AWS CloudTrail tracks the history of all resource changes. For more information, see Log Amazon Connect API calls with AWS CloudTrail.
# View calendar that illustrates effective hours of operation
View calendar that illustrates effective hours of operation
You can review operating hours and overrides together in a calendar. Select the **View in Calendar** button on the top of the detail page.
![\[Calendar view for effective hours of operation.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/hours-of-operation-calendar-view.png)
Choose day, week or month to see open and closed hours. Override names are provided where applicable.
# Create a routing profile in Amazon Connect to link queues to agents
Create a routing profile
This topic is for administrators and contact center managers. It explains how to create routing profiles using the Amazon Connect admin website. For the APIs used to create and manage routing profiles programmatically, see [APIs to create and manage routing profiles](#apis-routing-profiles).
While queues are a 'waiting area' for contacts, a routing profile links queues to agents. When you create a routing profile, you specify:
+ Channels: Which channels—voice, chat, task, and email—are routed to this group of agents; whether to allow channels concurrently.
+ Queues: Which queues are in the routing profile; whether one queue should be prioritized over another.
Each agent is assigned to one routing profile. For more information about routing profiles and queues, see [How Amazon Connect uses routing profiles](concepts-routing.md).
**How many routing profiles can I create?** To view your quota of **Routing profiles per instance**, open the Service Quotas console at [https://console.aws.amazon.com/servicequotas/](https://console.aws.amazon.com/servicequotas/).
**To create a routing profile**
1. On the navigation menu, choose **Users**, **Routing profiles**, **Add routing profile**.
1. In the **Routing Profile Details** section, in the **Name** box, enter a searchable display name. In the **Description** box, enter what the profile is used for.
1. In the **Channel Settings** section, enter or choose the following information:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/routing-profiles.html)
1. In the **Queues** section, enter the following information:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/routing-profiles.html)
1. Optionally, add tags to identify, organize, search for, filter, and control who can access this routing profile. For more information, see [Add tags to resources in Amazon Connect](tagging.md).
1. Choose **Save**.
## Tips for setting up channels and concurrency
+ Use **Channel availability** to toggle on and off whether agents assigned to a profile get voice, chat, task, and email contacts.
For example, there are 20 queues assigned to a profile. All of the queues are enabled for voice, chat, task, and email. By removing the **Voice** option at the routing profile level, you can stop all voice calls to these agents, across all queues in the profile. When you want to restart voice contacts for these agents again, select **Voice**.
+ When using **Cross-channel concurrency**, Amazon Connect checks which contact to offer the agent as follows:
1. It checks what contacts/channels the agent is currently handling.
1. Based on what channels they are currently handling, and the cross-channel configuration in the agent's routing profile, it determines whether the agent can be routed the next contact.
1. Amazon Connect prioritizes the longest waiting contact if Priority and Delay are equal. Even though it's evaluating multiple channels at the same time, First-In First-Out is still respected.
See [Example of how a contact is routed with cross-channel concurrency](#example-routing-concurrency).
+ For each queue in the profile, choose whether it's for voice, chat, task, email, or all channels.
+ If you want a queue to handle voice, chat, task, and email but want to assign a different priority to each channel, add the queue twice. For example, in the following image, voice is priority 1 but chat, task, and email are priority 2.
![\[Queue configuration showing two BasicQueue entries with different channel and priority settings.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/set-channels-and-concurrency-2.png)
## Example of how a contact is routed with cross-channel concurrency
For example, assume an agent is assigned to the routing profile that has the channel settings shown in the following image. They can be routed voice, chat, task, and email contacts. They can receive cross-channel contacts when on tasks.
![\[The create routing profile page, channel settings section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/routing-profile-cross-channel-concurrency.png)
The agent will experience the following routing behavior:
1. Assume the agent is fully idle. Next, the agent accepts a chat and begins working on it. Meanwhile, a task comes into queue.
+ Chat is set to **No other channels allowed**.
+ So even though there is a task in queue, it will not be offered to this agent.
1. Next, there is a chat in queue.
+ The agent's maximum chat concurrency is 2, so they are routed another chat for total of 2 chats. The agent continues working on both of the chats.
1. There are no other chats in queue. The agent finishes both chats (closes ACW).
+ There is still a task waiting in queue.
+ At this point, the task is offered to the agent because they are fully idle again. The agent begins working the task.
1. Another chat comes into queue.
+ Tasks is set to **Allow other channels concurrently**. So, even though the agent is already working on a task, they can still be offered the chat.
+ The chat gets routed to the agent, who now works on both the 1 chat and 1 task concurrently.
1. Now there is a Voice call in queue.
+ The agent is still working on 1 chat and 1 task.
+ Even though **Task** is set to **Allow other channels concurrently**, the agent is still working on 1 chat, and **Chat** is set to **No other channels while agent is on a Chat contact**. So, the voice call is not routed to the agent. The agent continues working on both the chat and the task.
1. The agent completes the chat, but still works on the task.
+ Now, because the only contact still assigned to the agent is a task, and **Tasks** are set to **Allow other channels concurrently**, this means that the agent can be offered the voice call.
+ The agent picks up the voice call and is now working concurrently on both the voice call and the task.
1. Now there is another task in queue.
+ The agent is currently working on a voice call AND a task. Once again, Amazon Connect checks the cross channel settings and Voice is set to **No other channels while agent is on a Voice contact**.
+ Because the agent is working on a voice call, they cannot be offered any tasks until they are done with the voice call.
+ Also, because **Task** is set to **Maximum contacts per agent** is 1, even after the agent handles the voice call, they still won't be offered the task until they finish their current task.
## APIs to create and manage routing profiles
APIs to APIs to create and manage routing profiles
Use the following APIs to create and manage routing profiles programmatically:
+ [CreateRoutingProfile](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateRoutingProfile.html)
+ [DescribeRoutingProfile](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeRoutingProfile.html)
+ [UpdateRoutingProfileConcurrency](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateRoutingProfileConcurrency.html)
+ [UpdateRoutingProfileQueues](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateRoutingProfileQueues.html)
+ [UpdateRoutingProfileDefaultOutboundQueue](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateRoutingProfileDefaultOutboundQueue.html)
# How Amazon Connect uses routing profiles
How Amazon Connect uses routing profiles
A routing profile determines what types of contacts an agent can receive and the routing priority.
+ Each agent is assigned to one routing profile.
+ A routing profile can have multiple agents assigned to it.
![\[A graphic that shows a group of agents mapped to one routing profile.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agents-routing-profile.png)
Amazon Connect uses routing profiles to allow you to manage your contact center at scale. To quickly change what a group of agents does, you only need to make an update in one place: the routing profile.
## Default routing profile: Basic routing profile
Amazon Connect includes a default routing profile named **Basic routing profile**. Along with the [default flows](contact-flow-default.md) and default queue (named **BasicQueue**), it powers your contact center so you don't need to do any customization. This is what enables you to get started quickly.
## Routing Profiles Link Queues and Agents
When you create a routing profile, you specify:
+ The channels the agents will support.
+ The queues of customers that the agents will handle. You can use a single queue to handle all incoming contacts, or you can set up multiple queues. Queues are linked to agents through a routing profile.
+ Priority and delay of the queues.
The following image shows a graphic of a group of agents mapped to a routing profile. The routing profile specifies multiple channels and queues for the agents.
![\[A graphic that shows a group of agents mapped to a routing profile.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/routing-profile-3.png)
# Delete a routing profile from an Amazon Connect instance
Delete a routing profile
There are three ways to delete a routing profile from your Amazon Connect instance:
+ Amazon Connect admin website: On the left side menu, choose **Users**, **Routing profiles** and then select the delete icon.
![\[The Routing profiles page, the Delete option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/delete-routingprofile.png)
**Important**
You cannot undo a deleted routing profile.
+ [DeleteRoutingProfile](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeleteRoutingProfile.html) API
+ [delete-routing-profile](https://docs.aws.amazon.com/cli/latest/reference/connect/delete-routing-profile.html) AWS CLI
# Set up queue-based, or skills-based, routing in Amazon Connect
Set up queue-based routing
Here's an overview of the steps to set up queue-based routing:
1. [Create the queues](create-queue.md), for example, one for each skill you want to use for routing.
1. [Create the routing profiles](routing-profiles.md):
+ Specify the channels supported by this routing profile.
+ Specify the queues: the channel, priority, and delay.
1. [Configure agent settings](configure-agents.md) to assign the routing profiles to them.
When you [create your flows](create-contact-flow.md), you'll add the queues to them. If a contact chooses to speak to an agent in Spanish, for example, they will be routed to the Spanish Reservations queue.
For information about how routing works, and queue-based routing, see these topics:
+ [How routing works with multiple channels](about-routing.md#routing-profile-channels-works)
+ [Queue-based routing to route customers to a specific contact center agent](concepts-queue-based-routing.md)
# Set up routing in Amazon Connect based on agent proficiencies
Set up routing based on agent proficiencies
Following is an overview of the steps to set up routing based on agent proficiencies:
1. [Create predefined attributes for routing contacts to agents](predefined-attributes.md)
+ You create the predefined attributes that you want to use to make a routing decision. In the next step, you can use predefined attributes individually, or you can combine them by using the `AND` or `OR` operators to form a routing step.
1. [Assign proficiencies to agents in your Amazon Connect instance](assign-proficiencies-to-agents.md)
+ You select predefined attributes and associate them with an agent. All available agents that meet a routing step requirement of a contact within the same queue will be considered for a match.
1. Set routing criteria
+ Use the [Set routing criteria](set-routing-criteria.md) flow block to set a routing criteria manually or dynamically.
1. Transfer to queue
Use the [Transfer to queue](transfer-to-queue.md) flow block to transfer the contact to a queue. After the contact is transferred, Amazon Connect runs the routing criteria.
![\[Proficiency routing 4 step chart.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/proficiency-routing-chart.png)
## Example of how to use agent proficiencies for routing
Example of how to use agent proficiencies for routing
Consider a scenario where a contact enters a queue **General Inbound Queue** and two agents, Agent1 and Agent2, are available. A customer who speaks French is seeking assistance regarding AWS DynamoDB. This is their second time calling regarding the same issue and you would prefer to match them with an expert in AWS DynamoDB. In order to preserve the customer experience, you want to implement the following routing requirements:
+ First look for an agent who is highly proficient in **French (>=4)** and an expert in **AWS DynamoDB (>=5)** for the first 30 seconds.
+ If an agent is not found at this time, look for an agent who is highly proficient in **French (>=3)** and highly proficient in **AWS DynamoDB (>=5)** for the next 30 seconds. The requirement for French is relaxed to further expand the pool of eligible agents to meet the requirement.
+ If no join is made at this point, look for an agent who is proficient in **French (>=3)** and highly proficient in **AWS DynamoDB (>=4)** and keep looking until an agent is found. Here the AWS DynamoDB requirement is relaxed to expand the pool of eligible agents who meet the requirement.
**Note**
For regulatory or compliance use cases you can use the **Never Expire** option for the expiration timer to ensure any agent who is joined on the contact meets a minimum requirement.
**To route the contact to the above requirements, complete the following steps:**
1. **Create predefined attributes**: For example, add `Technology` as a predefined attribute in **User Management**, **Predefined Attributes** with `AWS DynamoDB` as one of the values.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/proficiency-routing.html)
**Note**
**Connect:French** is already available as a value in system attribute **Connect:Language** as a predefined attribute. You can use this in your routing criteria. You can also add up to 128 customer languages as values to **Connect:Language**.
1. **Associate proficiencies to users**: There are 2 agents, Agent1 and Agent 2, who speak French and are proficient in AWS DynamoDB as shown below. In **User Management**, **Show Advanced Settings** associate the following proficiencies to the Agent1 and Agent2.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/proficiency-routing.html)
1. **Set routing criteria**: Use this flow block to create the following routing criteria manually or dynamically using JSON that is created by invoking a Lambda function as shown in a potential Inbound flow. Create the following routing criteria:
1. Step 1: connect:Language(connect:French) >=4 **AND** Technology (AWS DynamoDB) >=5 **[30 seconds]**
1. Step 2: connect:Language(connect:French) >=4 **AND** Technology (AWS DynamoDB) >=4 **[30 seconds]**
1. Step 3: connect:Language(connect:French) >=3 **AND** Technology (AWS DynamoDB) >=4 **[Never expire]**
The following image shows an example inbound flow that is configured for routing by agent proficiencies. This flow includes the following blocks: [AWS Lambda function](invoke-lambda-function-block.md), [Set routing criteria](set-routing-criteria.md), [Set working queue](set-working-queue.md), [Transfer to queue](transfer-to-queue.md), and [Disconnect / hang up](disconnect-hang-up.md).
![\[A flow that is configured for routing by agent proficiencies.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/proficiency-routing-example-flow-block.png)
1. **Transfer to queue**: After the contact is transferred to the "General Inbound Queue," Amazon Connect immediately starts running the routing criteria. The following steps occur before the contact is joined to Agent1.
1. **Routing Step 1**: For the first 30 seconds (no match) as neither agent has an AWS DynamoDB proficiency >= 5, Amazon Connect does not match with any agent.
1. **Routing Step 2**: In the next 30 seconds (no match) as neither agent is both highly proficient (>=4) in both French and AWS DynamoDB
1. **Routing Step 3**: As soon as the previous step expires, Amazon Connect finds the available agent, Agent1 (French 3, AWS DynamoDB 4) is proficient in French and highly proficient in AWS DynamoDB. Therefore, the contact is matched with Agent1.
There is a [one-click drill-down](one-click-drill-downs.md) in the real-time metrics for queues table which shows you a list of the routing steps in use for active contacts on the queue. You can find the definitions for the routing step specific metrics under [Metric definitions in Amazon Connect](metrics-definitions.md).
## Contact record, contact event stream, and agent event stream updates for agent proficiencies
Contact record, contact event stream, and agent event stream updates for agent proficiencies
Models have been added for proficiency routing in the following sections:
+ [Data model for Amazon Connect contact records](ctr-data-model.md)
+ [Agent event streams data model in Amazon Connect](agent-event-stream-model.md)
+ [Contact events data model](contact-events.md#contact-events-data-model)
## Frequently asked questions
Frequently asked questions
+ **Are queues still relevant?**
+ Yes, queues are still necessary. The routing criteria is only activated when a contact is enqueued. Agent proficiencies provide additional control to target specific agents within a queue.
+ **When should we model something as a proficiency instead of modeling it as a queue?**
+ This is a business decision. You should consider the impact on the number of queues you can eliminate and consolidate while using agent proficiencies.
+ **Do agent proficiencies work across all channels?**
+ Yes, routing using agent proficiencies works for all channels.
+ **How do I remove a routing criteria?**
+ You can interrupt a routing criteria using a customer queue flow.
+ You can also update the routing criteria this way.
+ **How many times can I change a routing criteria on a queued contact?**
+ You can change the routing criteria an unlimited number of times. However, only the latest 3 routing criteria updates are stored on the contact record.
+ **With agent proficiencies, do queue priority and delay operate as usual?**
+ Yes, queue priority and delay operate as they already do in a non-agent-proficiencies environment.
+ **Which operators are supported for creating a routing criteria?**
+ The following Boolean operators are supported:
+ AND
+ OR
+ The following comparison operators are supported:
+ >=
+ You can also define a range of minimum and maximum proficiency levels such as:
+ connect:English(1-3)
+ connect:Chat(4-4)
+ You cannot use the same attribute more than once in an expression. For example, connect:English(1-3) AND connect:English(5-5) are not allowed.
+ NOT (for exclusion) - You can use the NOT operator to exclude agents with certain proficiencies when routing such as:
+ NOT connect:French(1-5)
+ **Which characters can be used for predefined attributes?**
+ The pattern for predefined attribute name and value is `^(?!(aws:|connect:))[\p{L}\p{Z}\p{N}_.:/=+-@']+$`. For example, it can contain any letter, numeric value, whitespace, or `_.:/=+-@'` special characters, but can't start with `aws:` or `connect:`.
+ **Can I add the same attribute multiple times in a routing criteria?**
+ Yes, you can the same attribute multiple times in a routing criteria.
+ **When triggering a transfer (quick connect), is it possible to set the routing criteria?**
+ You use the [Set routing criteria](set-routing-criteria.md) block in the transfer flow to set the routing criteria on the transferred contact segment. It is not possible to carry forward the routing criteria of previous contact to the new contact segment created after an agent has been joined.
+ **What happens to the routing criteria if a contact is being transferred queue to queue, before it was routed?**
+ The routing criteria starts from the first step in the new queue in case a contact was transferred before being joined to an agent. For this, we carry-forward the routing criteria of previous contact to the new contact segment created due to queue transfer.
+ **Does the contact record have a snapshot of the proficiencies of the matched agent?**
+ No, the contact record does not carry the proficiencies of an agent.
+ The agent event stream does have a snapshot of the agent's proficiencies at the time of joining.
+ **Can we search for an agent by proficiency using APIs?**
+ No, this is not supported.
+ **What happens if we delete an attribute if it is on an active contact?**
+ You can delete an attribute that is used on active contacts. However, any routing step with that attribute will not find a matching agent and the contact stays in the queue until the routing criteria expires.
+ All new contacts with that attribute start taking the error branch on the [Set routing criteria](set-routing-criteria.md) block in the flow.
+ **What happens to the routing criteria steps / expiration when an agent rejects a call?**
+ Routing considers a join to be complete when an agent accepts the contact and a join is completed. When an agent rejects a contact, the routing engine continues to run through the routing criteria with the timer continually running.
+ **Will the agent who rejected the step be part of the pool when routing runs again?**
+ Yes, the agent continues to be a part of the pool when routing runs again.
+ **Are historical metrics available?**
+ No, historical metrics are not available in analytics.
+ The contact record, agent event stream, and contact event stream contain all the required information.
+ **Where can I find a sample Lambda function for setting routing criteria?**
+ For a sample Lambda function for setting routing criteria, see [Sample Lambda function for setting routing criteria](set-routing-criteria.md#set-routing-criteria-sample-lambda-function).
+ **What happens to the routing criteria set on a contact if the contact is being transferred to an agent queue?**
+ The routing criteria has no effect on contacts present in an agent queue. If a contact with routing criteria is transferred from an agent queue to a standard queue, then the routing criteria is forwarded to the new contact segment created due to queue transfer.
# Set up your contact center agents in Amazon Connect
Set up agents
You can manage and load-balance customer contacts using agent hierarchy organization and agent status management. These tools provide filtering and agent availability management per queue, skill set, and routing profiles.
**Topics**
+ [Set up agent hierarchies](agent-hierarchy.md)
+ [Add custom agent statuses](agent-custom.md)
+ [Configure agent settings](configure-agents.md)
+ [Enable Audio Enhancement](audio-enhancement.md)
+ [Create predefined attributes for routing contacts to agents](predefined-attributes.md)
+ [Assign proficiencies to agents](assign-proficiencies-to-agents.md)
+ [Enable auto-accept](enable-auto-accept.md)
+ [Enable persistent connection](enable-persistent-connection.md)
+ [Set up agents to assign tasks to themselves](setup-agents-assign-tasks-themselves.md)
# Organize agents into teams and groups for reporting and access by creating hierarchies
Set up agent hierarchies
Agent hierarchies are a way for you to organize agents into teams and groups for reporting purposes. It's useful to organize them based on their location and their skill sets. For example, you might want to create large groups, such as all agents who work on a specific continent, or smaller groups such as all agents working in a specific department.
You can also configure hierarchies with up to five levels, and segment agents or teams. Here are a couple of things to note about using hierarchies:
+ Removing agents from a level affects historical reporting.
+ When you use the **Restrict contact access** security profile permission, you can restrict contact search results based on the agent's hierarchy. For more information, see [Manage who can search for contacts and access detailed information](contact-search.md#required-permissions-search-contacts).
**Topics**
+ [
## Required permissions
](#permissions-agent-hierarchy)
+ [
## Define your organization's hierarchy levels
](#new-agent-hierarchy)
+ [
## Define groups and teams in your hierarchy
](#add-groups-teams-agents-hierarchy)
+ [
## Delete an agent hierarchy
](#delete-agent-hierarchy)
## Required permissions
To create agent hierarchies, you need to be assigned to a security profile that has the **Users and Permissions** - **Agent hierarchy** - **Create** permission.
**Note**
Since agent hierarchies may include location and skill set data, you also need **Agent hierarchy** - **View** permission to view the agent hierarchy information in a real-time metrics report.
The following image shows the **Users and Permissions - Agent hierarchy** permissions on the **Security profile permissions** page.
![\[The Users and Permissions - Agent hierarchy on the Security profile permissions page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/permission-agent-hierarchy.png)
## Define your organization's hierarchy levels
You can specify up to 5 levels or tiers for your organization's hierarchy groups. For example, if your teams are organized by geography your levels might be Continent, Country, Region, State, Team. Levels need to be put in place before you can describe the groupings that you want to assign agents and other users to.
1. Log in to the Amazon Connect admin website with an **Admin** account, or an account assigned to a security profile that has **Users and Permissions** - **Agent hierarchy** - **Create** permission.
1. Choose **Users**, **Hierarchies**, and then choose **Add level hierarchy structure**, as shown in the following image.
![\[The Hierarchies page, the Add level hierarchy structure button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-add.png)
1. Enter a name for the first level. Choose the **\$1** icon to add another level, such as Level 2, Start or Province. You can add up to five levels. In the following image, we've named Level 1 **Country**.
![\[The Level hierarchy structure section, Level 1.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-level1.png)
The following image shows a hierarchy structure with four levels for Country, State or Province, City, Neighborhood.
![\[The hierarchy structure for Country, State or Province, City, Neighborhood.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-structure.png)
**Tip**
After you [add groups](#add-groups-teams-agents-hierarchy) to these levels, you must delete the groups before you can delete the level.
1. Choose **Save** to apply the changes, or **Cancel** to undo them. If the **Save** button isn't active, you don't have [permissions](#permissions-agent-hierarchy) in your security profile to create or edit the agent hierarchy.
## Define groups and teams in your hierarchy
After you create hierarchy levels, you can add the groups that call within each, from the top down.
1. Scroll down the **Hierarchies** page to the **Hierarchy groups** section. Choose **Add new *Level1\$1Name***. For example, in the following image the name of Level 1 is **Country**.
![\[The Hierarchy groups section, the Add new Level1 button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-addnewcountry.png)
1. Enter the name for the group, such as Australia, and then choose **Save**. Choose **Add new Country** to add another country. The following image shows we added Australia and United States.
![\[The Hierarchy groups section, add groups for Level 1.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-us.png)
1. Next to the name of the group, choose **Add child State or Province**, as shown in the following image.
![\[The Add child option for level 1.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-addchild.png)
Choose **Add child State or Province** each time you want to add a group to level 2. When you're done, choose **Save**.
The following image shows we added New York and California.
![\[The Add child option for level 2 Add a child State or Province.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-addstates.png)
1. For each state, choose **Add child City** each time you want to add group to level 3. When you're done, choose **Save**. The following image shows we added Los Angeles and San Francisco.
![\[The Add child option for level 3 Add a child City.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-addchildcities.png)
1. Choose **Add child Neighborhood** to add groups to Level 4, as shown in the following image. We added Hollywood to Los Angeles.
![\[The Add child option for level 4 Add a child Neighborhood.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-hierarchy-addchild-neighborhood.png)
Choose **View historical changes** to view the change history. You can filter changes by date (between two dates) or by user name. If you cannot see the link, ensure that you have the proper permissions to view these changes.
## Delete an agent hierarchy
**Important**
Deleting a hierarchy level severs the link to existing contacts. This action can not be reversed.
# Add a custom agent status to the Amazon Connect Contact Control Panel (CCP)
Add custom agent statuses
Agents are responsible for setting their status in the Contact Control Panel (CCP). In fact, the only time an agent's status changes is when they manually change it in the CCP, or when [their supervisor changes it](rtm-change-agent-activity-state.md) in a real-time metrics report.
Amazon Connect provides two default status values:
+ Available
+ Offline
You can change the name of these values, and you can add new ones. For example, you might add a status for Lunch, and another for Training. These and the default status values will be used for reporting, metrics, and resource management.
When you add a new status, it will always be **Custom**, not routable.
You can't delete a status value but you can disable it so it doesn't appear on the agent's CCP.
**To add a new agent status**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account that has **Users and permissions** - **Agent status** - **Create** permissions in its security profile.
1. On the Amazon Connect admin website, on the navigation menu, choose **Users**, **Agent status**, **Add new agent status**. The following image shows a sample **Manage agent statuses** page.
![\[The Manage agent statuses page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/manage-agent-status.png)
1. Enter a status name and description.
1. Under **Tags**, optionally add resource [tags](tagging.md) to help organize agent statuses.
**Note**
Tags cannot be used for access control, for example, if you want to show a different CCP status to different agents based on their department (Sales, Technical, HR).
1. Choose **Save**.
1. After saving a custom status, you can disable it so that the status does not appear in the Contact Control Panel to agents.
To change the order that the status values appear in the CCP, choose **Reorder agent statuses**. Enter the display order that makes sense for your agents. The following image shows a sample **Reorder agent statuses** page.
![\[The Reorder agent statuses page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/reorder-agent-status.png)
**To edit an agent status**
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an **Admin** account, or an account that has **Users and permissions** - **Agent status** - **Edit** permissions in its security profile.
1. On the Amazon Connect admin website, on the navigation menu, choose **Users**, **Agent status**.
1. Choose the status you want to edit.
1. Enter the new information, and choose **Save** to apply the changes.
Choose **View historical changes** to view the change history. You can filter changes by date (between two dates) or by user name. If you can't see the **View historical changes** link, make sure you have the following permission in your security profile: **Historical changes** - **View historical changes** - **View**.
# Configure agent settings in Amazon Connect
Configure agent settings
Before you configure your agent settings, here is some info to have on hand. Of course, you can always change this information later.
+ What is their routing profile? They can only be assigned one.
+ Will they have the **Agent** security profile or a custom profile you created?
+ Are they going to use a soft phone? If so, will they be connected to contacts automatically, or will they need to press the **Accept** button in their Contact Control Panel (CCP)?
+ Or, are they going to use a desk phone? If so, what is their number?
+ How many seconds do they have for After contact work (ACW)? There's no way you can turn off ACW time altogether so agents never go to ACW. (A value of **0 **means an indefinite amount of time.)
+ Are they going to be assigned to an agent hierarchy?
**Note**
You can't configure how long an available agent has to connect with a contact before it's missed. Agents have 20 seconds to accept or reject a voice or chat contact, and 30 seconds for a task contact If no action is taken, the current agent's status will be **Missed** and the contact is routed to the next available agent.
**To configure agent settings**
1. On the left navigation menu, go to **Users, User management**.
1. Choose the user you want to configure, then choose **Edit**.
1. Assign a [routing profile](routing-profiles.md) to them. You can only assign one.
1. Assign the **Agent** security profile, unless you've created custom security profiles.
1. Under **Phone Type** choose whether the agent is using a desk phone or soft phone.
+ If you select **Desk phone**, enter their phone number.
**Important**
Outbound telephony charges occur when using a desk phone to answer inbound calls.
+ If you select **Soft phone**, we recommend selecting **Enable persistent connection**. This maintains agent connection after a call ends. It enables subsequent calls to connect faster. This doesn't apply to chats or tasks. For more information, see [Enable persistent connection](enable-persistent-connection.md).
1. Under Contact handling choose whether you want to auto accept contacts and set the After Contact timeout duration.
+ **Auto-Accept Call**: This enables agents to be connected to contacts automatically for the respective channel. For more information, see [Enable auto-accept](enable-auto-accept.md).
+ In **After call work (ACW) timeout**, type how many seconds agents have for after contact work, such as entering notes about the contact. This needs to be typed separately for each individual channel.
+ Minimum setting is 1 second.
+ Maximum setting is 2,000,000 seconds (24 days).
+ Enter **0** if you don't want to allocate a specific amount of ACW time. It essentially means an indefinite amount of time. When the conversation ends, ACW starts; the agent must choose **Close contact** to end ACW.
+ The following image shows the **Contact Handling** section of the **User Management** page. Each channel has a separate **Auto-accept** and **ACW timeout** setting.
+ Note -To configure auto-accept or ACW timeouts for Outbound Campaigns calls or customer-first callbacks, use the “Voice” settings.
+
![\[The Edit User page, the contact handling section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-contact-handling-config.png)
1. If desired, choose **Show advanced settings** to access the following additional properties.
![\[The Hide advance settings option on the User management page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/configure-agents-advanced-settings.png)
1. See the following topics:
+ [Assign proficiencies to agents in your Amazon Connect instance](assign-proficiencies-to-agents.md)
+ [Organize agents into teams and groups for reporting and access by creating hierarchies](agent-hierarchy.md)
1. Under **Tags**, optionally add resource [tags](tagging.md) to identify, organize, search for, filter and control who can access this user.
# Enable Audio Enhancement for agents in Amazon Connect
Enable Audio Enhancement
Audio Enhancement improves audio quality and reliability on the agent's side by reducing background noise and isolating the agent's voice during calls. This feature includes two enhancement modes: noise suppression and voice isolation.
## How Audio Enhancement works
Audio Enhancement processes audio in real-time and improves the audio quality perceived by the end-customer in one of two modes:
+ **Noise suppression** - Reduces background noise from the agent's environment.
+ **Voice isolation** - Reduces background noise and isolates the agent's voice when multiple people are speaking in the contact center environment.
The feature automatically applies to incoming and outgoing calls once enabled for an agent.
## Prerequisites
Before enabling Audio Enhancement, ensure the agent environment meets these requirements:
+ **CPU** - Minimum 4-core CPU or 4 vCPU for virtual machines
+ **Memory** - Follow CCP hardware recommendations (see [Agent headset and workstation requirements for using the Contact Control Panel (CCP)](ccp-agent-hardware.md))
+ **Phone type** - Softphone users only
+ **Infrastructure** - Native, embedded, custom, and [VDI client with local browser access](https://docs.aws.amazon.com/connect/latest/adminguide/scenario-deployment-approaches.html#vdi-with-browser) are supported; [VDI with Amazon Connect audio optimization](https://docs.aws.amazon.com/connect/latest/adminguide/scenario-deployment-approaches.html#vdi-citrix) is not supported
## Enable Audio Enhancement for agents
Audio Enhancement is disabled by default. Administrators must enable it for specific agents through user management settings.
**To enable Audio Enhancement**
1. In the Amazon Connect admin website, choose **Users** and then choose **User management**.
1. Review the **Audio Enhancement** column to see current settings for each agent.
1. Select one or more agents, then choose **Edit**.
1. Make sure to set **Phone type** to **Soft phone**.
1. In the user edit panel, expand the **Audio Enhancement** dropdown and select your preferred mode:
+ **Isolate Agent's Voice** – Suppresses background noise and isolates the agent's voice. This mode should only be enabled if the agent uses a wired headset. If you're not sure whether your agents will consistently use a wired headset, we recommend configuring 'Suppress Background Noise' mode instead.
+ **Suppress Background Noise** – Suppresses background noise. You can use this mode with any headset configuration, including wired headsets, wireless headsets, or no headset.
+ **No enhancement** – Disables Audio Enhancement capability. This is the default setting.
**Important**
Voice isolation should only be used with a wired headset.
![\[The Audio Enhancement dropdown in the user edit panel.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/admin-website-voice-enhancement.png)
1. Choose **Save**.
**Important**
Changes to Audio Enhancement settings take effect on the agent's next call. Current ongoing calls are not affected.
## Allow agents to control their Audio Enhancement settings
To let agents adjust their own Audio Enhancement settings during work sessions, you must enable the appropriate security profile permission.
**To allow agents to control Audio Enhancement**
1. In the Amazon Connect admin website, choose **Users**, **Security profiles**.
1. Select the security profile assigned to your agents.
1. Expand **Contact Control Panel (CCP)** permissions.
1. Select **Audio device settings**.
![\[The Audio device settings permission in the Contact Control Panel (CCP) section of the security profile.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/audio-device-settings-security-profile.png)
1. Choose **Save**.
After enabling this permission, agents will see Audio Enhancement controls in their CCP.
![\[The Audio Enhancement controls in the CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/ccp-audio-enhancement-dropdown.png)
**Important notes about agent control**
If you don't want your agents to adjust the Audio Enhancement settings, do not enable the **Audio device settings** security profile permission for those agents.
Audio Enhancement changes take effect on the agent's next call, not during ongoing calls. However, changing the microphone device immediately applies the latest configured settings, even during active calls.
The system doesn't automatically adjust settings when agents change headsets - agents must manually update their Audio Enhancement mode.
When both administrators and agents can control Audio Enhancement, the most recent change takes effect.
## Set up Audio Enhancement mode through Amazon Connect APIs
If you are using the Amazon Connect APIs, you can set the Audio Enhancement mode by including the [VoiceEnhancementConfigs](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateUser.html#connect-CreateUser-request-VoiceEnhancementConfigs) parameter in the [CreateUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateUser.html) or [UpdateUserConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateUserConfig.html) requests.
For example, the body of the `UpdateUserConfig` request should be:
```
POST /users/InstanceId/UserId/config HTTP/1.1
Content-type: application/json
{
...,
"VoiceEnhancementConfigs": [
{
"Channel": "VOICE",
"VoiceEnhancementMode": "VOICE_ISOLATION"
}
]
}
```
For both endpoints, the accepted values of `VoiceEnhancementMode` are `VOICE_ISOLATION`, `NOISE_SUPPRESSION`, or `NONE`.
## Set up Audio Enhancement mode for custom CCP
If you are using a custom CCP with the Amazon Connect Streams API, you can set the Audio Enhancement mode in either of the following ways:
+ **Using agent.setVoiceEnhancementMode API**
```
agent.setVoiceEnhancementMode("VOICE_ISOLATION");
```
+ **Using agent.setConfiguration API**
```
const configuration = agent.getConfiguration();
agent.setConfiguration({
...configuration,
voiceEnhancementMode: "NOISE_SUPPRESSION",
});
```
+ **Using the ConnectSDK** – Reference the [setVoiceEnhancementMode()](https://docs.aws.amazon.com/agentworkspace/latest/devguide/3P-apps-voice-requests-setvoiceenhancementmode.html) and [getVoiceEnhancementMode()](https://docs.aws.amazon.com/agentworkspace/latest/devguide/3P-apps-voice-requests-getvoiceenhancementmode.html) methods in the Voice API.
In all cases, the accepted values are `VOICE_ISOLATION`, `NOISE_SUPPRESSION`, or `NONE`. Once the mode is set, Amazon Connect Streams will apply the selected Audio Enhancement.
## Troubleshooting
If your customers report any audio quality issues:
1. Please make sure that Voice Isolation mode is enabled only if the agent is using a wired headset.
1. Confirm the agent's device meets minimum CPU requirements.
1. Check that the agent is using a supported CCP configuration.
If you require additional support, contact AWS Support and include:
+ The affected contact IDs and AWS account ID
+ Call recordings for affected contacts
+ Confirmation of the agent's audio setup and selected enhancement mode
## Related topics
+ [Agent headset and workstation requirements for using the Contact Control Panel (CCP)](ccp-agent-hardware.md)
+ [Security profiles for Amazon Connect and Contact Control Panel (CCP) access](connect-security-profiles.md)
+ [Provide agents with access to the Amazon Connect Contact Control Panel (CCP)](amazon-connect-contact-control-panel.md)
+ [Set up your contact center in Amazon Connect](amazon-connect-contact-centers.md)
# Create predefined attributes for routing contacts to agents
Create predefined attributes for routing contacts to agents
A predefined attributed is made up of a name-value pair. For example, a name such as `language` and values such as `English`, `French`, `Japanese`. You can use predefined attributes to route contacts to an agent or pools of agents within a queue.
**Tip**
You define the level of an agent's proficiency in their user profile, not when you create a predefined attribute. A proficiency level is an indicator, ranging from 1 to 5, of the level of expertise of an agent for a given attribute value. Level 1 is the lowest proficiency, while 5 is the highest.
You can create and manage predefined attributes manually by using the Amazon Connect admin website; the steps are described in this topic. Or programmatically by using the [Predefined attribute management APIs](#predefined-attributes-apis).
**Topics**
+ [
## Important things to know
](#important-things-predefined-attributes)
+ [
## System predefined attributes
](#sytem-predefined-attributes)
+ [
## Create a predefined attribute
](#predefined-attributes-create-web-admin)
+ [
## Update the name of an attribute or value
](#update-predefined-attributes)
+ [
## Predefined attribute management APIs
](#predefined-attributes-apis)
## Important things to know
Important things to know
+ The information in a predefined attribute is not encrypted. We strongly recommend you follow the [Best practices for PII compliance in Amazon Connect](compliance-validation-best-practices-PII.md).
+ You can create up to 500 values per attribute.
+ A predefined attribute **name** can be up to 100 characters long.
+ A predefined attribute **value** can be up to 100 characters long.
+ The pattern for predefined attribute name and value is `^(?!(aws:|connect:))[\p{L}\p{Z}\p{N}_.:/=+-@']+$`. For example, it can contain any letter, numeric value, whitespace, or `_.:/=+-@'` special characters, but can't start with `aws:` or `connect:`.
+ You cannot create duplicate predefined attribute names or values. In addition, case sensitivity does not allow you to use duplicate names. For example, a new predefined attribute with the name `language` cannot be created if a predefined attribute with name `Language` exists in your Amazon Connect instance.
+ An attribute can only be deleted if it not associated with any agent.
Before deleting an attribute, ensure none of the contacts are waiting for an agent with that attribute or the contact will not find a match.
+ For the quota for predefined attributes allowed in an Amazon Connect instance, see [Amazon Connect quotas](amazon-connect-service-limits.md#connect-quotas).
## System predefined attributes
System predefined attributes
System attributes, identified as `connect:`, are predefined attributes set by Amazon Connect. You cannot change or delete the `connect:` name and values.
The following system attributes are available:
+ `connect:Language`. You can add 500 custom values for `connect:Language`.
+ `connect:Subtype`. You cannot change `connect:Subtype` but it can be used in routing criteria for routing.
## Create a predefined attribute
Create a predefined attribute
1. Log in to the Amazon Connect admin website with an **Admin** account, or an account assigned to a security profile that has **Routing** - **Predefined attributes** - **Create** permission.
1. In Amazon Connect, on the left navigation menu, choose **Routing**, **Predefined attributes**.
1. On the **Attribute management** page choose **Add attribute**, as shown in the following image.
![\[The Attribute management page, the Add attribute button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/add-attribute.png)
1. On the **Add predefined attribute** page, in the **Details** section, complete the following fields as needed:
1. **Name**: Enter a name for the segment attribute.
1. **Use as a Contact search filter**: Choose if you want to enable contact search on this segment attribute.
1. **Use in analytics for granular insights**: Choose if you want to enable Analytics on this segment attribute.
Amazon Connect unlimited AI should be enabled for the instance in order to view this option.
Note: Do not store personally identifiable information (PII) as values in attributes are used for analytics purposes.
1. **Enforce valid values**: Choose to allow only predefined values when using this attribute as a contact segment attribute.
1. Choose **Add value** to add values to the attribute. For example, you might enter Sales, Marketing, and Accounts for Business units.
![\[Choose Save to save the attribute and values.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/predefined-attribute-add.png)
1. Choose **Save** to save the predefined attribute and values.
## Update the name of an attribute or value
Update the name of an attribute or value
1. Stop using the attribute on future contacts to drain all of the contacts on an active contact type.
1. Update all of the attributes.
## Predefined attribute management APIs
Predefined attribute management APIs
+ [CreatePredefinedAttribute](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreatePredefinedAttribute.html)
+ [UpdatePredefinedAttribute](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePredefinedAttribute.html)
+ [DeletePredefinedAttribute](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeletePredefinedAttribute.html)
+ [DescribePredefinedAttribute](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribePredefinedAttribute.html)
+ [ListPredefinedAttributes](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListPredefinedAttributes.html)
# Assign proficiencies to agents in your Amazon Connect instance
Assign proficiencies to agents
A proficiency consists of a predefined attribute name, its value, and a proficiency level. The level is a numeric value of 1, 2, 3, 4, or 5. After you have created predefined attribute, you can assign one or more proficiencies to an agent.
For example, Agent1 and Agent2 may be proficient in multiple technologies at varying levels. They can be assigned proficiencies to reflect their level of proficiency in those technologies as shown in the following table:
| Agent Name | Predefined Attribute | Value | Proficiency Level |
| --- | --- | --- | --- |
| Agent1 | Technology | AWS Kinesis | 2 |
| Agent1 | Technology | AWS Dynamo DB | 5 |
| Agent1 | Technology | AWS EC2 | 4 |
| Agent1 | Language | French | 3 |
| Agent1 | Language | English | 4 |
| Agent2 | Technology | AWS Dynamo DB | 3 |
| Agent2 | Technology | AWS EC2 | 5 |
| Agent2 | Technology | AWS Nepture | 5 |
| Agent2 | Language | French | 4 |
| Agent2 | Language | English | 3 |
**To assign a proficiency to a user**
1. On the navigation menu, choose **Users**, **User Management.**
1. Select the user name to open the user profile.
1. Go to **Show advanced settings**.
1. In the **Attributes** section, for the **Name ** field, using the dropdown menu select a predefined attribute that was created earlier.
1. From the **Value** field, using the dropdown menu ,select a option.
1. Under the **Skill level** field, select a proficiency level for the previous attribute value.
1. You can add up to 10 proficiencies per agent.
![\[Assigning proficiencies to an agent or user.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/assign-proficiencies-to-agents.png)
**Agent proficiencies management APIs**
+ [AssociateUserProficiencies](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociateUserProficiencies.html)
+ [DisassociateUserProficiencies](https://docs.aws.amazon.com/connect/latest/APIReference/API_DisassociateUserProficiencies.html)
+ [ListUserProficiencies](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListUserProficiencies.html)
# Enable auto-accept for agents
Enable auto-accept
When auto-accept is enabled for an available agent, the agent will be automatically connected to contacts from that channel, and won’t need to manually click accept or reject.
Auto-accept can be enabled for calls, callbacks, chats, tasks, and emails. Auto-accept for customer-first callbacks, inbound calls, and Outbound Campaigns calls are covered under the Voice auto-accept settings. Auto-accept for agent-first callbacks are covered under the Agent-first callback setting.
## How long until the contact is connected to the agent?
How long until the contact is connected to the agent?
Less than one second. When a contact arrives to an available agent who has auto-accept enabled for that channel, the Contact Control Panel (CCP) may briefly show the options **Accept** or **Reject**. This is expected behavior. After less than a second, the contact is automatically accepted and these options disappear. Additionally, if the contact is a chat, task, or email, an audio notification will be played to notify the agent that the contact has been auto-accepted. For voice calls, the auto-accept audio notification does not play, only the [agent whisper](https://docs.aws.amazon.com/connect/latest/adminguide/set-whisper-flow.html).
## Enable auto-accept for existing agents
You can enable auto-accept using the Edit or Bulk Edit features in Amazon Connect. Please note that you cannot configure per-channel auto-accept on user creation when creating users via importing a .csv template; instead, first create the users then use Bulk Edit to modify their per-channel auto-accept settings.
To Edit or Bulk Edit:
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an Admin account, or an account with **Users and Permissions** - **Users** - **Create** or **Edit** permission in it's security profile.
1. On the left navigation menu, choose **Users**, **User management**.
1. In the list of users, select an agent, and then choose **Edit**.
1. On the **Edit users** page, find the **Contact handling** section under **Settings**, and enable auto-accept for the desired channel.
1. Choose **Save**.
**Note**
**Firefox users**: If you are using the Firefox browser and using auto-accept for calls, you must keep the CCP or Agent Workspace browser tab in focus when you accept and connect to a voice contact. The CCP conforms to Firefox microphone usage guidance, and only has access to connect to the user's microphone when CCP tab is in focus.
![\[Enable auto-accept for existing agents.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/agent-contact-handling-config.png)
## Bulk upload new users
You cannot configure per-channel auto-accept on user creation when creating users via importing a .csv template; instead, first create the users then use Bulk Edit to modify their per-channel auto-accept settings.
You can't use the CSV template to edit information for existing users.
# Enable persistent connection for Amazon Connect agents
Enable persistent connection
When **Enable persistent connection** is selected for an agent, after a call ends the agent's softphone maintains its media connection to Amazon Connect for a few minutes. This enables subsequent calls to connect faster. In case the agent remains idle for an extended period of time, the softphone media connection is dropped to reduce agent workstation and network resource consumption. It is re-established upon the next call for this agent.
This functionality doesn't apply to chats or tasks.
## How to configure persistent connection for an agent
How to configure persistent connection
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an Admin account, or an account with **Users and Permissions** - **Users** - **Create** or **Edit** permission in it's security profile.
1. On the left navigation menu, choose **Users**, **User management**.
1. In the list of users, select an agent, and then choose **Edit**.
1. On the **Edit users** page, under **Phone**, choose **Softphone**, and then
a) select **Enable persistent connection** - to enable the feature
b) deselect **Enable persistent connection** - to disable the feature
1. Choose **Save**.
## Configure Persistent Connection using Bulk upload for new users
You can't use the CSV template to edit information for existing users. If you include duplicate users with different information in the CSV template, you will receive an error.
1. Log in to the Amazon Connect admin website at https://*instance name*.my.connect.aws/. Use an Admin account, or an account with **Users and Permissions** - **Users** - **Create** permission in it's security profile.
1. On the left navigation menu, choose **Users**, **User management**.
1. Choose **Add new users**.
1. Choose **Import users using a .csv template**.
1. Download the template for a pre-formatted CSV file.
1. In the CSV file, configure the details for the new users who you want to add.
a) To enable persistent connection - **persistent connection (yes/no)**, be sure to enter **yes**.
b) To disable persistent connection - **persistent connection (yes/no)**, be sure to enter **no**.
1. After configuring the CSV file, in your Amazon Connect instance, choose **Upload file**, and then choose the configured CSV file from its location on your computer.
1. Under **Upload file and verify**.
1. Under **Verify user details**, verify that the information is correct for the new users, and then choose **Save**.
## FAQ
FAQ
### When is the softphone connection created?
The media connection for agent softphone is created upon the first incoming or outbound call for the agent.
### Does the softphone connection persist for the entire agent session?
If the agent makes or receives another call within a few minutes of a previous call ending, the softphone connection gets re-used to reduce call setup time for the new call. This process repeats (and the session persists) for as long as the agent keeps placing or receiving calls in quick succession. However, if the agent remains idle for several minutes, then the connection is dropped. In such cases, the connection is re-created silently upon the next call.
### Can the agent opt-out of persistent connection?
Only the contact center administrator can enable or disable this feature for agents using steps mentioned above. Agents cannot disable persistent connection.
### Are there any browser restrictions for using this feature?
This feature is available on supported versions of [Chrome and Edge](connect-supported-browsers.md). It's not supported on Firefox.
### Can this feature be used when VDI audio optimization is enabled?
Yes.
### Is this feature supported on custom Call Control Panels (CCPs)? Is there a change needed to the Call Control Panel (CCP) to use this feature?
If your custom CCP uses the softphone from Amazon Connect embedded iframe (that is, if `allowFramedSoftphone` is passed as true to initiate the CCP using [Amazon Connect Streams JS](https://github.com/amazon-connect/amazon-connect-streams)), then you don't need to make any changes for this functionality to work.
If your custom CCP integrates [Amazon Connect RTC JS](https://github.com/aws/connect-rtc-js) in it's own frame, then you need to upgrade the same.
# Set up agents in Amazon Connect to assign tasks to themselves
Set up agents to assign tasks to themselves
For an agent to be able receive a task, they need a quick connect created for them. With this quick connect, agents will be able to assign tasks to themselves, and other agents will be able to assign tasks to them.
## Step 1: Create a quick connect for the agent
1. On the navigation menu, choose **Routing**, **Quick connects**, **Add a new**.
1. Enter a name for the quick connect, such as the name of the agent. For example, if you want Jane Doe to be able to assign tasks to herself, enter **Jane Doe**.
1. Under **Type**, use the dropdown list to choose **Agent**.
1. Under **Destination**, use the dropdown list to choose the user name for the agent.
1. Under **Flow**, choose **Default agent transfer**, or the appropriate flow for your contact center.
1. Under **Description**, enter a description, such as **Jane Doe's quick connect**.
1. Choose **Save**.
The following image shows a quick connect for Jane Doe on the **Quick connects** page.
![\[The quick connects page, a sample quick connect.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tasks-agent-quick-connect.png)
## Step 2: Create a queue for the agent and associate the quick connect
1. After you create the quick connect, go to **Routing**, **Queues** and add a queue for the agent.
1. On the **Add new queue** page, in the **Quick connects** box, search for the quick connect you created for the agent.
1. Select the quick connect and then choose **Save**.
## Step 3: Add the queue to the agent's routing profile
1. Go to **Users**, **Routing profiles** and choose the agent's routing profile.
1. Add the agent's queue to the routing profile, and choose **Task** for the channel.
If the agent can receive transfers through other channels, select them as well.
1. Choose **Save**.
# Provide agents with access to the Amazon Connect Contact Control Panel (CCP)
Provide access to the CCP
**Note**
This is the URL to the CCP website:
**https://*instance name*.my.connect.aws/ccp-v2/**
This is the URL to the [agent workspace](#use-agent-workspace):
**https://*instance name*.my.connect.aws/agent-app-v2/**
## Steps to ensure agents can access the CCP
Steps to ensure agents can access the CCP
Agents use the Contact Control Panel (CCP) to communicate with contacts. But before agents can access the CCP and handle contacts, there are a few things you need to do:
1. Ensure your network meets the requirements for using the CCP. For more information see [Set up your network to use the Amazon Connect Contact Control Panel (CCP)](ccp-networking.md).
1. Ensure agents have the appropriate headsets and workstations. For more information see [Agent headset and workstation requirements for using the Contact Control Panel (CCP)](ccp-agent-hardware.md).
1. Create a user name and password for agents to log into the CCP, by [adding agents to your instance](user-management.md).
1. At minimum, [assign them the **Agent** security profile](assign-security-profile.md). This grants them permissions to access the CCP, which they use to manage contacts.
1. Provide the user name, password, and the CCP website link to your agents so they can log in.
We recommend telling agents to bookmark the URL to the CCP so they can readily access it.
1. Train your agents on the CCP:
+ Watch [Training video: How to use the Contact Center Panel (CCP) in Amazon Connect](ccp-video-training.md)
## Agent workspace: Everything in one place
Want your agents to handle contacts and access customer profiles, cases, and knowledge all in one place? Use the [agent workspace](agent-user-guide.md)\$1
The *agent workspace* is a single web browser interface that hosts the CCP, [Customer Profiles](ag-cp-select.md), [Cases](search-cases.md), and [Connect AI agents](search-for-answers.md).
If you're using the CCP that is provided with Amazon Connect, after you enable Customer Profiles, Cases, or Connect AI agents, share the following URL with your agents so they can access it in the agent workspace:
+ **https://*instance name*.my.connect.aws/agent-app-v2/**
For help finding your instance name, see [Find your Amazon Connect instance name](find-instance-name.md).
## Grant microphone access in Chrome, Firefox, or Edge
If agents experience problems with their microphone, they may need to grant microphone access in their browser. Choose one of the following articles to get the steps appropriate for your browser:
+ [Use your camera and microphone in Chrome](https://support.google.com/chrome/answer/2693767?hl=en)
+ [Firefox Page Info window](https://support.mozilla.org/en-US/kb/firefox-page-info-window)
+ *How to allow a website to use your camera or microphone while browsing in Microsoft Edge* in the article [Windows camera, microphone, and privacy](https://support.microsoft.com/en-us/windows/windows-camera-microphone-and-privacy-a83257bc-e990-d54a-d212-b5e41beba857)
**Important**
A change introduced in Google Chrome version 64 may result in issues with receiving calls if you are using an embedded Contact Control Panel (CCP) softphone using the Amazon Connect Streams library. If you are experiencing issues with your microphone when using Chrome version 64, you can resolve the issue by building and deploying the latest version of the [Amazon Connect Streams API](https://github.com/aws/amazon-connect-streams/blob/master/Documentation.md#downloading-streams), following the steps under *Downloading Streams*.
You can also resolve the issue by using Firefox or Edge as your browser.
## How to get help for CCP issues
**Agents**: Contact your manager or the technical support provided by your company.
**Amazon Connect Administrators**: See [Troubleshooting Issues with the Contact Control Panel (CCP)](troubleshooting.md) for detailed troubleshooting steps. Or, log in to the [AWS Management Console](https://console.aws.amazon.com/console) (https://console.aws.amazon.com/console) using your AWS account. In the upper right corner of the page, choose **Support**, and open a support ticket.
# Agent headset and workstation requirements for using the Contact Control Panel (CCP)
Headset and workstation requirements
Agent headsets and workstations in the contact center vary widely. While the Amazon Connect CCP is built to handle high levels of jitter and high latency environments, the architecture of the **workstations** that agents use, and the location and environment in which they take contacts, can impact the quality of experience.
## Headset requirements
Headsets
The agent's Contact Control Panel (CCP) is compatible with all types of headsets.
For the best agent and customer experience, we recommend using a USB headset.
Alternatively, you can redirect the contact to an external number, in E.164 format, using an agent's existing telephony.
**Note**
If the agent's audio device does not support up to 48kHz and the browser asserts a sample rate of 48kHz, audio issues such as an audible humming sound may be present in the agent's outgoing audio. This has been seen with Firefox but not with Chrome.
For instructions on verifying the sample rate of the agent's headset and browser, see [Humming sound in the agent's audio device: Verify the headset and browser sample rates](verify-sample-rate.md)
## Workstation minimum requirements
Workstations
Underpowered workstations can make it difficult for agents to access the tools and resources they need to service contacts. Also, keep in mind the resource requirements when scoping workstations to ensure that they can perform under load while appropriately multitasking for the use case.
Following are the minimum system requirements for the workstations using the CCP only. You'll need to scope additional memory, bandwidth, and CPU for the operating system and anything else running on the workstation to avoid resource contention.
+ **Browser**: For a list of all supported browsers, see [Browsers supported by Amazon Connect](connect-supported-browsers.md).
+ **Network**
+ **Audio**
+ **1:1 call:** 54 Kbps up and down
+ **Large call**: no more than 32 Kbps extra down for 50 callers
+ **Video**
+ **1:1 call**: 650 Kbps up and down
+ **HD mode**: 1400 Kbps up and down
+ **3 – 4 people**: 450 Kbps up and (N-1)\$1400 Kbps down
+ **5 – 16 people**: 184 Kbps up and (N-1)\$1134 Kbps down
+ Up and down bandwidth adapts lower based on network conditions
+ **Screen**
+ 1.2 Mbps up (when presenting) and down (when viewing) for high quality. This adapts as low as 320 Kbps based on network conditions.
+ **Remote control**: 800 Kbps fixed
+ **Memory**: 2 GB RAM
+ **Processor (CPU)**: 2 GHz
## iPhone and other mobile devices are not supported
Mobile devices
The Amazon Connect console, Contact Control Panel (CCP), and agent workspace do not support mobile browsers.
## How to determine whether a workstation is the source of problems
To determine whether a workstation is the source of problems, you need access to various levels of logging information. However, adding logging and monitoring to workstations that are already experiencing resource contention may further reduce available resources and invalidate test results. We recommended that your workstation meet the minimum requirements, so you leave additional resources available for logging, monitoring, malware scanning, operating system functions, and any other running processes.
Collect additional historical logging and data sources for correlation. If you see a correlation between the time of the event and the time the issue was reported, you may be able to determine the root cause with the following information:
+ Round trip time (RTT) and packet loss to endpoints located within your Amazon Connect Region from your agent workstation, or an identical workstation on the same network segment. If no Region endpoints are available because of security policies, any public WAN endpoint suffices, for example, www.Amazon.com. Ideally, use your instance alias address (https://*your-instance-alias*.my.connect.aws/), and also your signaling address for endpoints.
You can find your Region endpoints here: [Amazon Connect endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/connect_region.html).
+ Regular monitoring of workstations that show processes running, and the current resource usage of each process.
+ Workstation performance/utilization in these areas:
+ Processor (CPU)
+ Disk / drive
+ RAM / memory
+ Network throughput and performance
+ Monitor all of the preceding for your VDI desktop environment, including RTT/packet monitoring between the agent workstation and the VDI environment.
# How to troubleshoot the agent's headset in the Contact Control Panel (CCP)
Can't hear caller or caller can't hear agent?
Problems with the agent's headset are usually caused by two issues:
+ The connection between the agent's headset and computer.
+ The permissions for the browser microphone.
Here's what you need to do:
+ **Check that your computer recognizes your headset**—Check the settings in Device Manager to ensure that your computer recognizes the headset and allows proper headset connectivity. For example, if you're using a Windows PC:
1. Go to **Device Manager**, then expand **Audio inputs and outputs**.
1. If your computer recognizes your headset, you'll see it listed there.
+ **Check your browser settings for your headset/microphone**
+ **Chrome**
1. go to **Settings**, **Site Settings**, **Microphone**.
1. Then check that the correct headset is enabled.
1. To learn more, see [Use your camera and microphone in Chrome](https://support.google.com/chrome/answer/2693767?hl=en).
+ **Firefox**
1. While in the CCP, choose the lock icon in the address bar. If needed, grant permissions to the CCP.
1. To learn more, see [Firefox Page Info window](https://support.mozilla.org/en-US/kb/firefox-page-info-window).
+ **Remove your ad blocker**: If you're using an ad blocker extension, remove it and see if that fixes the problem.
**Important**
A change introduced in Google Chrome version 64 may result in issues with receiving calls if you are using an embedded Contact Control Panel (CCP) softphone using the Amazon Connect Streams library. If you are experiencing issues with your microphone when using Chrome version 64, you can resolve the issue by building and deploying the latest version of the [Amazon Connect Streams API](https://github.com/aws/amazon-connect-streams/blob/master/Documentation.md#downloading-streams), following the steps under *Downloading Streams*.
You can also resolve the issue by using Firefox or Edge as your browser.
For more information about solving audio problems, see [Troubleshooting Issues with the Contact Control Panel (CCP)](troubleshooting.md).
# Agents not hearing the indicator for incoming chat
Agents can't hear indicator for incoming chat?
If an agent can't hear the audio indicator for an incoming chat, the problem is likely because Google added an audio policy flag to Chrome. This flag exists in Chrome versions 71 - 75.
To fix this, add the CCP website to the allowlist in the agent's Chrome settings. For instructions, see this [Google Chrome Help article](https://support.google.com/chrome/answer/114662).
For more information about solving audio problems, see [Troubleshooting Issues with the Contact Control Panel (CCP)](troubleshooting.md).
# Embed a custom Amazon Connect Contact Control Panel (CCP)
Embed a custom CCP
The [Amazon Connect Streams](https://github.com/aws/amazon-connect-streams) documentation describes how to integrate your existing web applications with Amazon Connect. Streams gives you the power to embed the Contact Control Panel (CCP) UI components into your page, and/or handle agent and contact state events directly giving you the power to control agent and contact state through an object oriented event driven interface. You can use the built in interface or build your own from scratch: Streams gives you the power to choose.
**Topics**
+ [Using Amazon Connect with third-party cookies](admin-3pcookies.md)
+ [Embed CCP into Salesforce](salesforce-integration.md)
+ [Embed CCP into Zendesk](zendesk-integration.md)
# Using Amazon Connect with third-party cookies
Using Amazon Connect with third-party cookies
## Google Chrome
Google Chrome
On Jul 22, 2024, Google [announced](https://privacysandbox.com/news/privacy-sandbox-update/) that they no longer plan to deprecate third-party cookies and instead will provide an opt-in mechanism for deprecating third-party cookies. Amazon Connect uses third-party cookies for authentication. With this announcement, Amazon Connect customers using Google Chrome no longer need to upgrade to StreamsJS or CTI Adapter versions that address third-party cookie deprecation, which were planned for release in Q3 2024. No customer action is needed at this time.
# Embed the Amazon Connect Contact Control Panel (CCP) into Salesforce
Embed CCP into Salesforce
The core functionality of the Amazon Connect CTI Adapter provides a WebRTC browser-based Contact Control Panel (CCP) within Salesforce. The Amazon Connect CTI integration consists of two components:
+ [A managed Salesforce package](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000EJH4yUAH)
+ [An AWS Serverless application deployed to your AWS environment](https://serverlessrepo.aws.amazon.com/applications/arn:aws:serverlessrepo:us-west-2:821825267871:applications~AmazonConnectSalesforceLambda)
For a detailed walk-through and setup of the full CTI Adapter capabilities for Salesforce Lightning, see the [Amazon Connect CTI Adapter for Salesforce Lightning installation guide](https://amazon-connect.github.io/amazon-connect-salesforce-cti/docs/lightning/notices/).
For the CTI Adapter for Salesforce Classic, see the [Amazon Connect CTI Adapter for Salesforce Classic installation guide](https://amazon-connect.github.io/amazon-connect-salesforce-cti/docs/classic/notices/).
We recommend that you initially install the package into your Salesforce sandbox. After the package is installed, you can configure your Salesforce Call Center configuration within Salesforce.
# Embed the Amazon Connect Contact Control Panel (CCP) into Zendesk
Embed CCP into Zendesk
To integrate Amazon Connect and Zendesk, you need:
+ An Amazon Connect instance.
+ A [Zendesk Support](https://www.zendesk.com/support/) account and the [Contact Center add-on](https://www.zendesk.com/pricing/), or a Zendesk trial account.
+ A Zendesk for Contact Center instance configured by Zendesk.
Before installing the [Zendesk for Contact Center app](https://www.zendesk.com/marketplace/apps/support/1114151/zendesk-for-contact-center/) you need to connect your Zendesk for Contact Center instance to your Amazon Connect instance using a CloudFormation stack installation. The template for this will be provided to you by Zendesk when your Zendesk for Contact Center instance is set up.
After your Zendesk for Contact Center instance is created and linked to your Amazon Connect instance, install and configure the [Zendesk for Contact Center app](https://www.zendesk.com/marketplace/apps/support/1114151/zendesk-for-contact-center/) in your Zendesk Support account, and then connect the app with your Zendesk for Contact Center instance.
For more information, see the [Zendesk for Contact Center documentation](https://support.zendesk.com/hc/en-us/sections/9248688983706-Using-Zendesk-for-Contact-Center).
# Upgrade to the latest Amazon Connect Contact Control Panel (CCP).
Upgrade to the latest CCP
The URL for the latest Contact Control Panel (CCP) ends with **ccp-v2**
You only need to upgrade to the latest CCP if you're using one the following options:
+ [The URL for your CCP ends with **/ccp\$1**](upgrade-browser-ccp.md)
+ [You use the Amazon Connect Streams API](upgrade-ccp-streams-api.md). The URL associated with `initCCP()` ends with **/ccp\$1**
If you’re still unsure whether your using the latest CCP, go to [Compare the earlier and latest CCP](upgrade-browser-ccp.md#ui-comparison) to see if your CCP looks like the latest one.
## Upgrade on your own schedule, before your automatic upgrade date
To upgrade to the latest CCP before your automatic upgrade date, use the steps in the following sections:
+ [Upgrade your Contact Control Panel (CCP) when your CCP URL ends with /ccp\$1](upgrade-browser-ccp.md)
+ [Upgrade your Contact Control Panel (CCP) when using the Amazon Connect Streams API](upgrade-ccp-streams-api.md)
## Upgrade later, automatically
If you don't want to upgrade now, you can choose to wait until your scheduled upgrade date.
Between now and your scheduled upgrade date, we recommend the following change management steps:
+ Compare how the upgraded CCP differs from the earlier one. For side-by-side visuals, see [Compare the earlier and latest CCP](upgrade-browser-ccp.md#ui-comparison).
+ Upgrade your CCP in a test environment. Use the latest CCP to learn how it's different, and to check your configurations.
+ Communicate to your agents when the upgrade is going to take place.
+ Train your agents to help them get ready.
## Schedule for the automatic upgrade
Your automatic upgrade date is dependent on your usage. Following is the schedule for when we will start migrating environments:
+ <100 weekly minutes - start migrating on August 16, 2024
+ <1K weekly minutes - start migrating on August 30, 2024
+ <10K weekly minutes - start migrating on September 13, 2024
+ <100K weekly minutes - start migrating on October 4, 2024
+ >100K weekly minutes - start migrating on November 1, 2024
# Upgrade your Contact Control Panel (CCP) when your CCP URL ends with /ccp\$1
Upgrade my CCP when my CCP URL ends with /ccp\$1
Upgrading to the latest CCP is easy. If you want, you can try out the latest CCP and then at a later date make the switch. Here's what you do:
1. **Try it out**: Change the URL in your browser from **/ccp\$1** to **/ccp-v2**. The latest CCP appears automatically. If you want, change it back to /ccp\$1 to return to the earlier CCP.
1. **Upgrade**: Change the URL in your browser from **/ccp\$1** to **/ccp-v2**. Bookmark the URL.
1. If you access the CCP through the Amazon Connect console by choosing the phone icon on the top right of a page, you will be re-directed according to the automatic upgrade date sent by email. Please reach out to your Amazon Solution Architect if your request is more urgent.
![\[The Amazon Connect admin website, phone icon in top right corner.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-phone-icon.png)
1. After the upgrade happens, if you use the /ccp\$1 URL, it resolves to **/ccp-v2**.
## Verify your network settings
We highly recommend setting up your network to use [Option 1 (recommended): Replace Amazon EC2 and CloudFront IP range requirements with a domain allowlist](ccp-networking.md#option1).
Using this option helps Amazon Connect Support to quickly troubleshoot any issues you have. Specifically, using **\$1.telemetry.connect.\$1region\$1.amazonaws.com** passes more metrics to our Support team to help with troubleshooting.
## Update your SAML URL to ccp-v2
If you use SAML 2.0 as your identity management system, be sure to update the destination in your relay state URL to **ccp-v2**.
Change `destination=/connect/ccp` to `destination=/connect/ccp-v2`.
For more information, see [Use a destination in your relay state URL](configure-saml.md#destination-relay)
## Compare the earlier and latest CCP
Compare the earlier and latest CCP
The images in this section show you how the latest CCP differs from the earlier CCP for common tasks that agents perform. The images show both CCP versions in their default state.
**Tip**
The chat tab appears on an agent's CCP only if their routing profile includes chat.
### Set status, use chat, access quick connects and number pad
![\[The available status in earlier CCP, available status in latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-status-available.png)
1. Agents use a dropdown to set their status.
1. If you have enabled chat for the agent’s routing profile, the chat tab appears.
1. Choose the **Quick connects** button to type and call a phone number, or select a quick connect.
1. Choose the **Number pad** button to type and call a phone number. This is useful when the phone number has letters.
### Receive a call
![\[Receive a call in earlier CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-receive-call-earlier-ccp.png)
![\[Receive a call in latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-receive-call-latest-ccp.png)
### Miss a call
![\[Miss a call in earlier CCP, miss a call in latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-missed-call.png)
### Make a call: When to use Quick connects
![\[Make a call in earlier CCP, Make a call in latest CCP using quick connect.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-make-call.png)
+ Use the **Quick connects** button to type a number or select a quick connect.
### Make a call: When to use Number pad
![\[Make a call in earlier CCP, Make a call in latest CCP using number pad.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-make-call2.png)
+ Choose the **Number pad** button to type and call a number. This is useful for corporate numbers with letters (for example, 1-800-EXAMPLE).
### Make an outbound call
![\[Make an outbound call in earlier CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-connected-outbound-call-earlier.png)
![\[Make an outbound call in latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-connected-outbound-call-latest.png)
### Agent ends a call before being connected to the other party
![\[Agent ends call before being connected in earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-end-outbound-call-before-connecting.png)
1. If an agent ends a call before being connected, they are then available for a new contact to be routed to them automatically.
1. If an agent ends a call before being connected, they are prompted to choose **Clear contact**.
### Make another call while connected on a call
![\[Make another call while connected on a call earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-another-call.png)
1. You can see the call that you are on while typing another number or selecting a quick connect.
1. After choosing **Quick connects**, you can choose the **Number pad** button. Then on the **Number pad** page, you can enter a number.
### Enter DTMF input while connected on a call
![\[Enter DTMF input while connected on a call earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-dtmf.png)
+ While on a call, only use **Number pad** to enter DTMF input.
### Conference call scenario 1: Leaving a call when one party is on hold and the other is connected
![\[Leaving call earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-conference-call.png)
1. Choose **Leave call** to leave the call. This automatically takes the first party off hold and connects them to the second party.
1. If instead you want to end the call, choose the **x** next to each party's number. This disconnects each party.
### Conference call scenario 2: Leaving a call when the other parties are joined
![\[Leaving call earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-leave-call-keep-others-joined.png)
1. Choose **Leave call** to leave the call. The other two parties stay joined.
1. If instead you want to end the call, choose the **x** next to each party's number. This disconnects each party.
### Conference call scenario 3: Leaving a call when the other parties are on hold
![\[Leaving call earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-on-hold.png)
1. Choose **Leave call** to leave the call. The other two parties are automatically taken off hold and connected.
1. If instead you want to end the call, choose the **x** next to each party's number. This disconnects each party.
### Receive a queued callback
![\[Receive a queued callback earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-receive-callback.png)
### Miss a queued callback
![\[Miss a queued callback earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-miss-callback.png)
### Finish After contact work (ACW)
![\[Finish After contact work earlier CCP, latest CCP.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-acw.png)
+ During After contact work (ACW), agents can finish follow-up work, and then choose **Clear contact**.
# Upgrade your Contact Control Panel (CCP) when using the Amazon Connect Streams API
Upgrade your CCP when using the Amazon Connect Streams API
**Note**
The Amazon Connect Streams API remains the same between the earlier and latest versions of the CCP. We recommend validating custom implementations built using the Amazon Connect Streams API when upgrading versions to ensure consistency in behavior.
Use the following steps to upgrade to the latest CCP.
1. We recommend using the latest [Amazon Connect Streams API](https://github.com/amazon-connect/amazon-connect-streams).
1. Update the URL associated with `initCCP()` from **/ccp\$1** to **/ccp-v2**. For information about `initCCP()`, see [connect.core.initCCP()](https://github.com/aws/amazon-connect-streams#initialization) in the Amazon Connect Streams API documentation on GitHub.
1. Add your domain URL to the Approved origin list:
1. Log in to the [AWS Management Console](https://console.aws.amazon.com/console) (https://console.aws.amazon.com/console) using your AWS account.
1. Navigate to the Amazon Connect console.
1. Check that you're in the correct Region for your Amazon Connect instance. Choose your instance.
![\[The Amazon Connect virtual contact center instances page, the alias of your instance.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/tutorial1-lex-custom-bot18.png)
1. Choose **Application integration**, and then choose **Add origin**.
![\[The left navigation pane, application integration option, Add origin.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/upgradeccp-application-integration.png)
1. Enter your domain URL. All domains that embed the CCP for a particular instance to be explicitly added. For more information, see [this article](https://github.com/amazon-connect/amazon-connect-streams/blob/master/Documentation.md#allowlisting) on GitHub.
If you use Salesforce, you need to add the Salesforce domains to your allowlist to prevent any issues with the CTI Adapter CCP functionality. For detailed instructions, see the [Amazon Connect CTI Adapter for Salesforce Lightning installation guide](https://amazon-connect.github.io/amazon-connect-salesforce-cti/docs/lightning/notices/) or the [Amazon Connect CTI Adapter for Salesforce Classic installation guide](https://amazon-connect.github.io/amazon-connect-salesforce-cti/docs/classic/notices/).
## Verify your network settings
We highly recommend setting up your network to use [Option 1 (recommended): Replace Amazon EC2 and CloudFront IP range requirements with a domain allowlist](ccp-networking.md#option1).
Using this option helps Amazon Connect Support to quickly troubleshoot any issues you have. Specifically, using **\$1.telemetry.connect.\$1region\$1.amazonaws.com** passes more metrics to our Support team to help with troubleshooting.
## Update your SAML URL to ccp-v2
If you use SAML 2.0 as your identity management system, be sure to update the destination in your relay state URL to **ccp-v2**.
Change `destination=/connect/ccp` to `destination=/connect/ccp-v2`.
For more information, see [Use a destination in your relay state URL](configure-saml.md#destination-relay)