# 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', /* ... */);
<script/>
```

## 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.

```
<button id="launch-widget-btn">Chat With Us</button>
```

```
<script type="text/javascript">
 (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,
        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;
                }
            }
        }),
    });
</script>
```

### 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
```

```
<script type="text/javascript">
 (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
    });
</script>
```

### 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. 

```
<button id="launch-widget-btn">Chat With Us</button>
```

```
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.

```
<button id="openChatWindowButton">Launch a Chat</button>
```

```
<script> // Function to open a new browser window with specified URL and dimensions
    function openNewWindow() {
        var url = 'https://mycompany.com/support?autoLaunchChat=true';

        // Define the width and height
        var width = 300;
        var height = 540;

        // Calculate the left and top position to center the window
        var left = (window.innerWidth - width) / 2;
        var top = (window.innerHeight - height) / 2;

        // Open the new window with the specified URL, dimensions, and position
        var newWindow = window.open(url, '', 'width=${width}, height=${height}, left=${left}, top=${top}');
    }

    // Attach a click event listener to the button
    document.getElementById('openChatWindowButton').addEventListener('click', openNewWindow);
</script>
```

## 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. 

```
<script type="text/javascript">
  (function(w, d, x, id){ /* ... */ })(window, document, 'amazon_connect', 'widgetId');
  amazon_connect('snippetId', 'snippetId');
  amazon_connect('styles', /* ... */);
  // ...

  amazon_connect('contactAttributes', {
   foo: 'bar'
  })
<script/>
```

### Using the attributes in flows


The [Check contact attributes](check-contact-attributes.md) flow block provides access to these attributes by using the **User defined** namespace, as shown in the following image. You can use the flow block to add branching logic. The full path is `$.Attributes.HostedWidget-attributeName`.

![\[Image showing a flow block branching to Valid and Invalid prompts.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/flow-check-contact-attrib.png)


## Things you need to know

+ The communications widget has a 6144 bytes limit for the entire encoded token. Because JavaScript uses UTF-16 encoding, 2 bytes are used per character, so the maximum size of the `encoded_token` should be around 3000 characters.
+ The encoded\$1token should be passed in to `callback(data)`. The `authenticate` snippet does not need any additional changes. For example:

  ```
  amazon_connect('authenticate', function(callback) {
    window.fetch('/token').then(res => {
      res.json().then(data => {
        callback(data.data);
      });
    });
  });
  ```
+ Using a JWT to pass contact attributes ensures the integrity of the data. If you safeguard the shared secret and follow appropriate security practices, you can help ensure that the data cannot be manipulated by a bad actor.
+ Contact attributes are only encoded in the JWT, not encrypted, so it's possible to decode and read the attributes.
+ If you want to test the chat experience with the [simulated chat experience](chat-testing.md#test-chat) and include contact attributes, be sure to enclose both the key and value in quotes, as shown in the following image.  
![\[The test settings page, a contact attribute key in quotes, a value in quotes.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/test-chat-contact-attributes.png)

# Additional customizations for your Amazon Connect chat widget
Additional customizations for your chat widget

You can add the following optional customizations to your chat user interface:
+ Display the **End chat** button in the header dropdown menu instead of in the footer.
+ Mask or hide display names.
+ Add message icons.
+ Override event messages.
+ Configure a confirmation dialog that will be presented to customers when they choose the **End chat** button. This dialog verifies that customers intend to actually end the chat session. You can customize the confirmation dialog, title, message, and button text.
+ Override the attachment rejection message.

## Configure the customization object


This example shows how to implement some of the optional customizations. For a list of all possible customizations, see [Supported options and constraints](#customization-options-constraints). Because these customizations are optional, you can implement some or all of the fields shown in the following example. Replace the `eventNames.customer`, `eventNames.agent`, `eventNames.supervisor`, `eventMessages.participantJoined`, `eventMessages.participantDisconnect`, `eventMessages.participantLeft`, `eventMessages.participantIdle`, `eventMessages.participantReturned`, and `eventMessages.chatEnded` strings as needed. Icons must be hosted on public URLs.

```
amazon_connect('customizationObject', {
        header: { 
            dropdown: true, 
            dynamicHeader: true,
        },
        transcript: { 
            hideDisplayNames: false, 
            eventNames: {
                customer: "User",
                agent: "Webchat Agent",
                supervisor: "Webchat Supervisor"
            },
            eventMessages: {
                participantJoined: "{name} has joined the chat",
                participantDisconnect: "",
                participantLeft: "{name} has dropped",
                participantIdle: "{name}, are you still there?",
                participantReturned: "",
                chatEnded: "Chat ended",
            },
            displayIcons: true,
            iconSources: { 
                botMessage: "imageURL",
                systemMessage: "imageURL",
                agentMessage: "imageURL",
                customerMessage: "imageURL",
            },
        },
        composer: {
            disableEmojiPicker: true,
            disableCustomerAttachments: true,
            alwaysHideToolbar: true,
            hide: false,
        },
        footer: {
            disabled:true,
            skipCloseChatButton: true,
        },
        endChat: {
            enableConfirmationDialog: true,
            confirmationDialogText: {
                title: "End Chat",
                message: "Are you sure you want to end this chat?",
                confirmButtonText: "End Chat",
                cancelButtonText: "Cancel",
        },
    },
    attachment: {
         // Default rejectedErrorMessage: Attachment was rejected.
        rejectedErrorMessage: "Custom Error Message: Files cannot exceed 15 MB." //this is customizable attribute 
    }
});
```

The following image shows how the customizations look if you use the example:

![\[Diagram showing the customizable display names, menu locations, icons, and End chat confirmation dialog.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chat-customization-diagram2.png)


## Supported options and constraints


The following table lists the supported customization fields and recommended value constraints.


| Custom layout option | Type | Description | 
| --- | --- | --- | 
|  `header.dropdown`  |  Boolean  |  Renders the header dropdown menu instead of the default footer  When you set this option to `true`, the **Transcript download** button appears and remains visible until you set the option to `false`, or until you remove the option.   | 
| `header.dynamicHeader` | Boolean | Dynamically sets the header title to "Chatting with Bot/AgentName". | 
| `header.hideTranscriptDownloadButton` | Boolean | Hide the [download transcript](chat-widget-download-transcript.md) button in the header dropdown menu. The default value is false. | 
|  `transcript.hideDisplayNames`  |  Boolean  |  Hides all display names, will apply default name masks if `eventNames` is not provided.  | 
|  `transcript.eventNames.customer`  |  String  |  Masks the display name of customer.  | 
|  `transcript.eventNames.agent`  |  String  |  Masks the display name of agent.  | 
|  `transcript.eventNames.supervisor`  |  String  |  Masks the display name of supervisor.  | 
|  ` transcript.eventMessages.participantJoined`  |  String  |  Overrides event message in the transcript for when a participant has joined the chat. If an empty string is specified, the event message will be omitted from the transcript. `{name}` can be passed in the message, and will be replaced with the display name of the corresponding participant. The default message is `{name} has joined the chat`.   | 
|  `transcript.eventMessages.participantDisconnect`  |  String  |  Overrides event message in the transcript for when a participant is disconnected from the chat. If an empty string is specified, the event message will be omitted from the transcript. `{name}` can be passed in the message, and will be replaced with the display name of the corresponding participant. The default message is \$1`name} has been idle too long, disconnecting`.  | 
|  `transcript.eventMessages.participantLeft`  |  String  |  Overrides event message in the transcript for when a participant has left the chat. If an empty string is specified, the event message will be omitted from the transcript. `{name}` can be passed in the message, and will be replaced with the display name of the corresponding participant. The default message is `{name} has left the chat`.  | 
|  `transcript.eventMessages.participantIdle`  |  String  |  Overrides event message in the transcript for when a participant is idle. If an empty string is specified, the event message will be omitted from the transcript. `{name}` can be passed in the message, and will be replaced with the display name of the corresponding participant. The default message is `{name} has become idle`.  | 
|  `transcript.eventMessages.participantReturned`  |  String  |  Overrides event message in the transcript for when a participant has returned to the chat. If an empty string is specified, the event message will be omitted from the transcript. `{name} `can be passed in the message, and will be replaced with the display name of the corresponding participant. The default message is `{name} has returned`.  | 
|  `transcript.eventMessages.chatEnded`  |  String  |  Overrides event message in the transcript for when the chat has ended. If an empty string is specified, the event message will be omitted from the transcript. `{name}` can be passed in the message, and will be replaced with the display name of the corresponding participant. The default message is `Chat has ended!`  | 
|  `transcript.displayIcons`  |  Boolean  |  Enables message display icons.  | 
|  `transcript.iconSources.botMessage`  |  String  |  Icon displayed for bot messages, must be hosted on a public URL.  | 
|  `transcript.iconSources.systemMessage`  |  String  |  Icon displayed for system message, must be hosted on a public URL.  | 
|  `transcript.iconSources.agentMessage`  |  String  |  Icon displayed for agent message, must be hosted on a public URL.  | 
|  `transcript.iconSources.customerMessage`  |  String  |  Icon displayed for customer message, must be hosted on a public URL.  | 
|  `composer.alwaysHideToolbar`  |  Boolean  |  Hides the formatting toolbar that includes text styling features such as Bold, Italic, and both bulleted and numbered list options.  | 
|  `composer.disableEmojiPicker`  |  Boolean  |  Disables the emoji picker when using the [rich text editor.](enable-text-formatting-chat.md)  | 
| `composer.disableCustomerAttachments` | Boolean | Prevents customers from sending or uploading attachments. | 
| `composer.hide` | Boolean | Hides the composer (`true`) or shows it (`false`). To toggle the composer based on events (such as when an agent joins), use `registerCallback` with the `hideComposer` method. For more information, see [Supported widget snippet fields in Amazon Connect that are customizable](supported-snippet-fields.md).<pre>document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatInterface.hideComposer(false)</pre> | 
|  `footer.disabled`  |  Boolean  |  Hides the default footer and **End chat** button.  | 
|  `footer.skipCloseChatButton`  |  Boolean  |  Directly closes the widget on click of the **End chat** button instead of showing **Close** button.  | 
| `endChat.enableConfirmationDialog` | Boolean | Enables the End Chat confirmation dialog. Default texts are used if confirmationDialogText is not provided. | 
| `endChat.confirmationDialogText.title` | String | Overrides the title of End Chat confirmation dialog. | 
| `endChat.confirmationDialogText.message` | String | Overrides the message of End Chat confirmation dialog. | 
| `endChat.confirmationDialogText.confirmButtonText` | String | Overrides the confirm button text in End Chat confirmation dialog. | 
| `endChat.confirmationDialogText.cancelButtonText` | String | Overrides the cancel button text in End Chat confirmation dialog. | 
| `attachment.rejectedErrorMessage` | String | Overrides the error message for chat widget attachment rejection. | 

# Download the transcript for your chat widget in Amazon Connect
Download the transcript for your chat widget

You can download a PDF of the transcript in your chat widget.

**Topics**
+ [

## Enable Header Dropdown
](#chat-widget-download-transcript-enable-header-dropdown)
+ [

## Download PDF of Chat Transcript
](#chat-widget-download-transcript-pdf)

## Enable Header Dropdown


The button to download the transcript is within a drop down menu in the header. To enable the header’s drop down menu, we have to configure our chat widget’s [customizationObject](pass-customization-object.md) in the widget script.

```
amazon_connect('customizationObject', {
        header: { 
            dropdown: true, 
        }
});
```

Note that enabling the drop down menu will automatically disable the footer since the **End Chat** functionality is moved to the header drop down menu. If you want to keep the footer, you can re-enable it by using the following:

```
amazon_connect('customizationObject', {
        header: { 
            dropdown: true, 
        },
        footer: {
            disabled: false,
        }
});
```

## Download PDF of Chat Transcript


After enabling the header drop down menu, you should be able to see a triple dot menu on the top left of the chat widget. Within that drop down menu, you should see a download **Chat Transcript** button.

![\[Shows button to download chat transcript.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chat-widget-download-transcript-pdf-1.png)


Choosing download **Chat Transcript** will start a PDF download. The PDF of the chat transcript will show all messages, display names, time stamps and message events, such as participants leaving or joining.

![\[Downloaded chat transcript example.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chat-widget-download-transcript-pdf-2.png)


# Customize chat with the Amazon Connect open source example
Download and customize our open source example

You can further customize the chat experience customers use to interact with agents. Use the [Amazon Connect open source library](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/cloudformationTemplates/asyncCustomerChatUX) on GitHub. It's a platform to help you get started quickly. Here's how it works:
+ The GitHub repository links to a CloudFormation template, which starts the Amazon API Gateway endpoint that initiates a Lambda function. You can use this template as an example.
+ After you create the AWS CloudFormation stack, you can call this API from your app, import the pre-built communications widget, pass the response to the widget, and start chatting. 

For more information about customizing the chat experience, see: 
+ [Amazon Connect Service API Documentation](https://docs.aws.amazon.com/connect/latest/APIReference/welcome.html), 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 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. 
+ [Amazon Connect Chat SDK and Sample Implementations](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/) 

# Start chats in your applications by using Amazon Connect APIs


Use the StartChatContact API in Amazon Connect APIs to start chats in your own applications.

To start a chat, use the [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API.

When you explore the chat experience for the first time, you'll notice that chats aren't counted in the **Contacts Incoming** metric in your historical metrics report. This is because the initiation method for the chat in the contact record is **API**. 

The following image of a contact record shows the *Initiation Method* set to *API*. 

![\[A contact record, the initiation method set to API.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/ctr-api.png)


After a chat is transferred to an agent, the **Contacts Incoming** metric is incremented. The contact record for the transfer no longer increments the API, but it does increment **Contacts Incoming**. 

# Send browser notifications to customers when chat messages arrive


The communications widget supports browser notifications for your customers through their desktop devices. Specifically, your customers will receive a notification through their web browser when they receive a new message, but are not active on the web page that contains the chat window. When your customers click or tap this notification, they are automatically redirected to the web page containing the chat window. Your customers can enable or disable notifications at the start of each chat conversation. 

The following image shows an example of the notification banner that customers receive when they are not on the web page that contains the chat window. The banner tells your customers that they have a new message, and it displays the name of the website. 

![\[A Google Chrome banner that says you have received a new message.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-notification-banner.png)


Customers also receive a notification icon—a red dot—on the communications widget when it is minimized. The following image shows an image of the notification icon that customers receive when their chat window is minimized.

![\[A notification icon.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-browser-notification.png)


Both of these features are automatically included in the communications widget. You don't need to perform any steps to make them available to your customers.

Your customers receive a pop-up to allow/deny notification when they initiate a chat and have not yet allowed notifications from your website or domain. After they grant notification permissions, they start receiving browser notifications for any message or attachment sent by the agent when they are not on the web page with the chat window. This behavior applies even if you've already implemented the communications widget.

## How to test


1. After you allow notifications as a test customer and the agent is connected to the chat, minimize your chat window and then open a new browser instance so you aren't on the web page that contains the chat window.

1. Send a message from the agent window.

1. As the test customer, you'll see the notification banner.

1. Choose or tap the notification banner. You'll automatically go to the web page that contains the chat window.

1. Because you minimized your chat window earlier, you will also see a notification icon—a red dot—on the communications widget.

If you can't see the browser notification, check the following: 
+ You're using a [supported browser](add-chat-to-website.md#chat-widget-supported-browsers).
+ The notification permission is allowed/enabled on your browser for the web page with chat window.
+ The agent (or you from your agent chat session) has sent a new message/attachment while you're on a web page that is different from the one that contains the chat window. For the notification icon—a red dot—on the widget to be visible, minimize your chat window.
+ Notifications from the browser are not snoozed (temporarily dismissed).

# Programmatically disconnect the chat session of an Amazon Connect communication widget
Programmatic chat disconnect

You can disconnect the chat session of a communication widget programmatically using 'JavaScript by calling the `disconnect` method stored to the widget's `iframe`. From the widget's host document, you can reference the `disconnect` function using the following code snippet: 

```
document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect()
```

You can readily add it to the existing widget script. Following is an example code snippet:

```
<script type="text/javascript">
  (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', '...');
  amazon_connect('styles', { iconType: 'CHAT', openChat: { color: '#ffffff', backgroundColor: '#123456' }, closeChat: { color: '#ffffff', backgroundColor: '#123456'} });
  amazon_connect('snippetId', '...');
  amazon_connect('supportedMessagingContentTypes', [ 'text/plain', 'text/markdown', 'application/vnd.amazonaws.connect.message.interactive', 'application/vnd.amazonaws.connect.message.interactive.response' ]);
 
  // Add disconnect event listener
  window.addEventListener("pagehide", () => {
      document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect();
  });
</script>
```

## 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. 

```
<script type="text/javascript">
  (function(w, d, x, id){ /* ... */ })(window, document, 'amazon_connect', 'widgetId');
  amazon_connect('snippetId', 'snippetId');
  amazon_connect('styles', /* ... */);
  // ...
  
  amazon_connect('contactAttributes', {
   foo: 'bar'
  })
<script/>
```

### Using the attributes in contact flows


The [Check contact attributes](check-contact-attributes.md) flow block provides access to these attributes via the **User defined** namespace, as shown in the following image. You can use the flow block to add branching logic. The full path is `$Attribute.HostedWidget-attributeName`. 

![\[Image showing a flow block branching to Valid and Invalid prompts.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/flow-check-contact-attrib.png)


## Copy communications widget code and security keys
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. You can also copy the secret keys for creating the JWTs. 

### 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.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatwidget-security-key.png)


When your customers interact with the start call 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 call 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 call 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 [Communications widget script](add-chat-to-website.md#chat-widget-script).
  + **iat**: \$1Issued At Time.
  + **exp**: \$1Expiration (10 minute maximum).

  \$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:

```
payload = {
'sub': widgetId, // don't add single quotes, such as 'widgetId'
'iat': datetime.utcnow(),
'exp': datetime.utcnow() + timedelta(seconds=JWT_EXP_DELTA_SECONDS)
}

header = {
'typ': "JWT",
'alg': 'HS256'
}

encoded_token = jwt.encode((payload), CONNECT_SECRET, algorithm=JWT_ALGORITHM, 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 be able to call your contact center. This script displays the widget in the bottom-right corner of your website. 

The following image shows an example of where to find your widgetId.

![\[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 call 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-call-edit.png)


To make changes to widget icons on the website, you will receive a new code snippet to update your website directly.

# Additional customizations for your Amazon Connect web calling widget
Additional customizations

You can add the following additional customizations to your web calling widget:
+ Apply [background blur](#background-blur) to your customer's video tile.
+ Set the widget to [fullscreen](#fullscreen-mode).
+ Select the [default camera device](#choose-default-camera).
+ [Resize the video](#resize-video) to fit its container.

The following sections explain the details of the customizations, their use cases, and how to configure them. You manage these customizations by configuring `WebCallingCustomizationObject`.

**Topics**
+ [Background blur](#background-blur)
+ [Fullscreen mode](#fullscreen-mode)
+ [Choose the default camera device](#choose-default-camera)
+ [Resize video](#resize-video)
+ [Configure the customization object](#configure-customization-object-web)
+ [Supported options and constraints](#supported-options-web-calling)

## Background blur
Background blur

This customization controls the background blur behavior of the customer's video. When enabled, the customer's background is blurred when video is active. This helps protect their personal information or private spaces that may be visible in the background during the video call.

To enable background blur, set `videoFilter.backgroundBlur.option` to `ENABLED_ON_BY_DEFAULT` in `WebCallingCustomizationObject`.

## Fullscreen mode
Fullscreen mode

Use this customization to control the widget's fullscreen behavior. There are two ways you can enable fullscreen: 
+ Add a fullscreen button to the widget. The customer can use the button to toggle fullscreen on and off.

  To add a fullscreen button, set `fullscreen.displayButton` to `ENABLED`. 

OR
+ Set the widget to fullscreen upon load.

  To enable fullscreen upon load, set `fullscreen.fullscreenOnLoad` to `ENABLED`.

It's particularly helpful to use fullscreen mode when the customer needs to focus on the widget, such as during screen sharing.

You can use these two options individually or in combination.

## Choose the default camera device
Choose the default camera device

This customization allows the widget to select default camera device when your customer enables video, offering options for front or back camera. This ability is useful for diagnosing appliances remotely, for example. The customer can use back camera to show the appliance to agent.

To select back camera as default, set `devices.defaultCamera` to `Back`.

## Resize video
Resize video

This customization controls how the video tiles for both the customer and agent are resized in the widget. For example, the video frame can be resized to fill the entire video tile, or scaled to fit the video tile, leaving empty spaces if the aspect ratio of the video frame does not match the video tile.
+ To resize the video for customer, set `videoTile.localVideoObjectFit` to the target value.
+ To resize the video for agent, set `videoTile.remoteVideoObjectFit` to the target value.

For more information, see [Supported options and constraints](#supported-options-web-calling).

## Configure the customization object
Configure the customization object

The following example shows how to implement optional customizations for web calling. For a detailed description of these options, see [Supported options and constraints](#supported-options-web-calling). 

You can implement some or all of the fields shown in the following example. When you don't implement customizations, default behaviors are used for the missing fields.

```
amazon_connect('webCallingCustomizationObject', { 
        videoFilter: { 
            backgroundBlur: { 
                option: "ENABLED_OFF_BY_DEFAULT" 
            }
        },
        fullscreen: {
            displayButton: "ENABLED",
            fullscreenOnLoad: "DISABLED"
        },
        devices: { 
            defaultCamera: "Front" 
        },
        videoTile: {
            localVideoObjectFit: "cover",
            remoteVideoObjectFit: "cover"
        },
        copyDisplayNameFromAuthenticatedChat: true
});
```

The following image shows how the customizations look when not in full-screen mode. 

![\[Customizations when not in full-screen model.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/fullscreenmode.png)


The following image shows how the customizations look when in full-screen mode.

![\[Customizations when in full-screen mode.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/nonfullscreenmode.png)


## Supported options and constraints
Supported options and constraints

The following table lists the supported customization fields and recommended value constraints.


| Custom layout option | Type | Values | Description | 
| --- | --- | --- | --- | 
|  `videoFilter.backgroundBlur.option`  |  string  |  `ENABLED_ON_BY_DEFAULT` \$1 `ENABLED_OFF_BY_DEFAULT`  |  Sets your customer's video tile background blur. By default, when your customer enables video, the background blur filter will be applied to the video tile, if you don't want to enable the filter by default, you can set it to `ENABLED_OFF_BY_DEFAULT`, your customer can still manually enable the filter in the widget's preferences page. | 
|  `fullscreen.displayButton`  |  string  |  `ENABLED`  |  Adds a button to the top right corner of the widget to make it fullscreen in the browser. By default, this button will not be added to the widget, if you want to add this button, you can set it to `ENABLED`. | 
|  `fullscreen.fullscreenOnLoad`  |  string  |  `ENABLED`  |  Makes the widget fullscreen in the browser. By default, the widget will be anchored to the bottom right corner of the webpage, setting it to `ENABLED` will make the widget fullscreen in the browser. | 
|  `devices.defaultCamera`  |  string  |  `Front` \$1 `Back`  | Sets the default camera device when your customer enables video. This is for mobile or tablet use cases. By default, the default camera is selected([detail](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices)). (For more information, see the [MediaDevices: enumerateDevices() method](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices) in the Mozilla developers documentation.) When you set it to `Front\|Back`, it selects the corresponding camera if available. | 
|  `copyDisplayNameFromAuthenticatedChat`  |  boolean  |  `true` \$1 `false`  | In the case that the end customer is authenticated using the [Authenticate Customer](authenticate-customer.md) flow block, setting the value to `true` will copy the display name to the voice contact. The default is `false`. | 
|  `videoTile.localVideoObjectFit`  |  string  |  `fill` \$1 `contain` \$1 `cover` \$1 `none` \$1 `scale-down`  |  Sets the [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) property of your customer's video tile in the widget. By default, the value is determined by the width and height of the video resolution: if height is greater than width, it will be `contain`, else it will be `cover`. For a detailed description of each value, see [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) in the Mozilla developer documentation.  This attribute is applied to only the display height and width of the customer's video in the widget. The height and width of the customer's video sent to the agent is unaltered.  | 
|  `videoTile.remoteVideoObjectFit`  |  string  |  `fill` \$1 `contain` \$1 `cover` \$1 `none` \$1 `scale-down`  | Sets the [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) property of your customer's video tile in the widget. By default, the value is determined by the width and height of the video resolution: if height is greater than width, it will be `contain`, else it will be `cover`. For a detailed description of each value, see [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) in the Mozilla developer documentation.  This attribute is applied to only the display height and width of agent's video in the widget.   | 

# Integrate video calling and screen sharing into your custom agent desktop by using Amazon Connect Streams JS
Integrate video calling and screen sharing into your custom agent desktop

This topic is for developers. For custom agent desktops, you need to make changes to support video calling and screen sharing. Following are high level steps.

**Note**  
If you embed the CCP directly into your custom agent application make sure `allowFramedVideoCall` is set to true when you initiate the CCP using [Amazon Connect Streams JS](https://github.com/aws/amazon-connect-streams).

1. Use [Amazon Connect Streams JS](https://github.com/aws/amazon-connect-streams) to check if the incoming contact is an WebRTC contact. Use contact subtype `"connect:WebRTC"`, as shown in the following code example:

   `contact.getContactSubtype() === "connect:WebRTC"`

1. You can retrieve the customer display name by using the name field in ` contact contact.getName()`.

## Add support for video
Add support for video

Complete the following steps to add support for video handling when your customers have it enabled.

1. To check whether a contact has video capability:

   ```
   // Return true if any connection has video send capability
   contact.hasVideoRTCCapabilities()
   
   // Return true if the agent connection has video send capability
   contact.canAgentSendVideo()
   
   // Return true if other non-agent connection has video send capability
   contact.canAgentReceiveVideo()
   ```

1. To check on whether the agent has video permission to handle video call:

   `agent.getPermissions().includes('videoContact');`

1. To accept a video call, the contact must have video capability and the agent must have video permission.

   ```
   function shouldRenderVideoUI() {
       return contact.getContactSubtype() === "connect:WebRTC" &&
       contact.hasVideoRTCCapabilities() &&
       agent.getPermissions().includes('videoContact');
   }
   ```

1. In order to join a video session, call `getVideoConnectionInfo`:

   ```
   if (shouldRenderVideoUI()) {
      const response = await
      contact.getAgentConnection().getVideoConnectionInfo();
   }
   ```

1. To build a video UI and join a video meeting session, see:
   + [Amazon Chime SDK for JavaScript](https://github.com/aws/amazon-chime-sdk-js) on GitHub 
   + [Amazon Chime SDK React Components Library](https://github.com/aws/amazon-chime-sdk-component-library-react) on GitHub

1. For simplicity, the following code snippets use examples from the Amazon Chime SDK React Components Library.

   ```
   import { MeetingSessionConfiguration } from "amazon-chime-sdk-js";
   import {
     useMeetingStatus,
     useMeetingManager,
     MeetingStatus,
     DeviceLabels,
     useLocalAudioOutput
   } from 'amazon-chime-sdk-component-library-react';
   
   const App = () => (
     <MeetingProvider>
       <MyVideoManager />
     </MeetingProvider>
   );
   
   const MyVideoManager = () => {
       const meetingManager = useMeetingManager();
       if (shouldRenderVideoUI()) {
           const response = await contact.getAgentConnection().getVideoConnectionInfo();
           const configuration = new MeetingSessionConfiguration(
               response.meeting, response.attendee);
           await meetingManager.join(configuration, { deviceLabels: DeviceLabels.Video });
           await meetingManager.start();
       }
       
       function endContact() {
           meetingManager.leave();
       }
   }
   ```

1. To render the video grid, use the [VideoTileGrid](https://aws.github.io/amazon-chime-sdk-component-library-react/?path=/docs/sdk-components-videotilegrid--page) from the Amazon Chime SDK React Components Library or customize the UI behavior using [RemoteVideoTileProvider](https://aws.github.io/amazon-chime-sdk-component-library-react/?path=/docs/sdk-providers-remotevideotileprovider--page). 

1. To render a video preview, you can use [VideoPreview](https://aws.github.io/amazon-chime-sdk-component-library-react/?path=/docs/sdk-components-previewvideo--page) and [CameraSelection](https://aws.github.io/amazon-chime-sdk-component-library-react/?path=/docs/sdk-components-deviceselection-camera-cameraselection--page) components. To choose or change a camera video, you can use `meetingManager.selectVideoInputDevice` or `meetingManager.startVideoInput `if the meeting is in progress.

   ```
   const meetingManager = useMeetingManager();
   const { isVideoEnabled } = useLocalVideo();
   if (isVideoEnabled) {
       await meetingManager.startVideoInputDevice(current);
    } else {
       meetingManager.selectVideoInputDevice(current);
   }
   ```

1. To implement background blur, see [useBackgroundBlur](https://aws.github.io/amazon-chime-sdk-component-library-react/?path=/docs/sdk-hooks-usebackgroundblur--page). 

1. For sample code on how to build a custom video experience, see this Amazon Chime SDK sample: [Amazon Chime React Meeting demo](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/meeting). 

## Add support for screen sharing
Add support for screen sharing

**Note**  
If you use the out-of-box CCP directly in your custom agent application make sure `allowFramedScreenSharing` and `allowFramedScreenSharingPopUp` are set to true when you initiate the CCP using [Amazon Connect Streams JS](https://github.com/aws/amazon-connect-streams).   
Setting `allowFramedScreenSharing` to true enables the screen sharing button on only one CCP in one window or tab. Setting `allowFramedScreenSharingPopUp` to true launches the screen sharing app in a separate window when the agent chooses the screen sharing button. For more detail, see the [Amazon Connect Streams JS](https://github.com/aws/amazon-connect-streams) documentation.

Complete the following steps to enable screen sharing on your custom agent desktops. 

1. Check whether a contact has screen sharing capability. 

   ```
   // Return true if any connection has screen sharing send capability
   contact.hasScreenShareCapability()
   
   // Return true if the agent connection has screen sharing send capability
   contact.canAgentSendScreenShare()
   
   // Return true if customer connection has screen sharing send capability
   contact.canCustomerSendScreenShare()
   ```

1. Check whether the agent has video permission.

   ```
   agent.getPermissions().includes('videoContact');
   ```

1. Check whether the agent can initiate a screen sharing session for the eligible contact.

   ```
   fun canStartScreenSharingSession() {
       return contactgetContactSubtype() === "connect:WebRTC" &&
       contact.hasScreenShareCapability() &&
       agent.getPermissions().includes('videoContact');
   }
   ```

1. Call `startScreenSharing` to initiate the screen sharing session. This adds `ScreenSharingActivated` to the contact, enabling you to search for it in the [contact record](ctr-data-model.md). 

   ```
   contact.startScreenSharing();
   ```

1. Call `getVideoConnectionInfo` to join the session. You can skip the step if the agent has joined the video session to handle video.

   ```
   if (canStartScreenSharingSession) {
       contact.startScreenSharing();
       const response = await
       contact.getAgentConnection().getVideoConnectionInfo();
   }
   ```

1. Join the session by using the Amazon Chime SDK React Components Library. For a code snippet, see step 6 in [Add support for video](#support-video).

1. Use the same [VideoTileGrid](https://aws.github.io/amazon-chime-sdk-component-library-react/?path=/docs/sdk-components-videotilegrid--page) from the Amazon Chime SDK React Components to render screen sharing video tile. For more information, see [useContentShareState](https://aws.github.io/amazon-chime-sdk-component-library-react/?path=/docs/sdk-hooks-usecontentsharestate--page) and [useContentShareControls](https://aws.github.io/amazon-chime-sdk-component-library-react/?path=/docs/sdk-hooks-usecontentsharecontrols--page) 

1. Call `stopScreenSharing` when end the session.

   ```
   contact.stopScreenSharing();
   ```

1. You can receive events for the screen sharing activity by subscribing the following callbacks:

   ```
   initScreenSharingListeners() {
       this.contact.onScreenSharingStarted(() => {
           // Screen sharing session started
       });
   
       this.contact.onScreenSharingStopped(() => {
           // Screen sharing session ended
       });
   
       this.contact.onScreenSharingError((error) => {
           // Screen sharing session error occurred
       });
     }
   }
   ```

# Enable URL restriction for screen sharing
Enable URL restriction for screen sharing

You can manage the URLs that your customers and agents are allowed to share during the contact. This enables you to achieve enhanced security and privacy. When a customer or agent shares a URL that is not allowlisted, they receive an error message and the screen share video is automatically paused and blacked out. 

**Important**  
The following browsers are supported:   
Chrome version 109 and later
Edge version 109 and later
Agents and customers can share only the browser tab. They cannot share the window or entire screen. If you enable this feature and your customers or agents use an unsupported browser, window, or the entire screen, they will receive an error.

Complete the following steps to enable URL restriction for screen sharing.

## Step 1: Create an allowed URLs list
Step 1: Create an allowed URLs list

You configure the lists of allowed URLs by using predefined attributes. Complete the following steps.

1. In the Amazon Connect admin website, choose ****Routing****, **Predefined attributes**, **Add predefined attribute**.

1. In the **Add predefined attributes** section, in the **Predefined attribute** box, add one of the following.
   + To create allowed list for customer screen sharing, enter `screensharing:customer-allowed-urls`.
   + To create allowed list for agent screen sharing, enter `screensharing:agent-allowed-urls`.

1. In the **Value** box, enter the allowed URL. It can be a fully formatted URL or a string pattern for substring matching, such as` https://mycompany` or ` /mytransactions`. The following table shows examples of valid formats.    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/screen-sharing-url-restriction.html)

1. Save the list. The URLs appear on the **Predefined attributes** page, as shown in the following example.   
![\[The Predefined attributes page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/screen-sharing-restricted-urls.png)

## Step 2: Add script to your website list
Step 2: Add script to your website list

You need to embed a script into your website so the URL of the page can be exposed to the capturing application. You get the capture handler from a file on the Amazon CloudFront endpoint that Amazon Connect hosts. Complete the following instructions.

1. In the Amazon Connect admin website, choose **Channels**, **Communicate widgets**. On your Communication widget summary page, look for the widget script. Get the endpoint from the `s.src` attribute, as shown in the following example.   
![\[The Widget script.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/screen-sharing-restricted-urls-step2.png)

   The endpoint can be in a different AWS Region than your Amazon Connect instance. For best performance, we recommend using the same Region as your Amazon Connect instance. 

1. Replace the following placeholder `${endpoint}` with the value from previous step. Copy the entire code snippet and paste it on the top level of your website.

   ```
   <script type="text/javascript" src='${endpoint}/amazon-connect-url-restriction.js'></script>
   ```

# 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 `<li>` 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}}`  
`<li>{{this}}</li>`  
`{{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 `<h1>Art</h1>`.

*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).