# Set up Amazon Connect Global Resiliency **Note** **New user?** Check out the [Amazon Connect Global Resiliency Workshop](https://catalog.workshops.aws/amazon-connect-global-resiliency/en-US). This online course guides you through the process of onboarding and testing phone number and agent failover using new APIs through the AWS CLI. Global Resiliency is available only for Amazon Connect instances created in the following AWS Regions: US East (N. Virginia), US West (Oregon), Asia Pacific (Osaka), Asia Pacific (Tokyo), Europe (Frankfurt), and Europe (London). You can only create a replica in the US East (N. Virginia) Region if your source is US West (Oregon), or the other way around. You can only create a replica in the Europe (Frankfurt) Region if your source is Europe (London), or the other way around. You can only create a replica in Asia Pacific (Osaka) Region if your source is Asia Pacific (Tokyo). To obtain access to this feature, contact your Amazon Connect Solutions Architect or Technical Account Manager. **Important** Amazon Connect Global Resiliency (ACGR) is the only AWS-supported solution for multi-region resiliency in Amazon Connect. AWS does not support third-party or custom-built alternatives for achieving global resiliency. Deploying unsupported solutions may result in denied or reduced service limits on the secondary instance and could impact SLA coverage if downtime is attributed to the unsupported deployment. Amazon Connect Global Resiliency enables you to provide customer service anywhere in the world with the highest reliability, performance, and efficiency. With its distributed telephony features, your contact center can meet international regulatory requirements. Amazon Connect Global Resiliency provides a set of APIs that you use to: + Provision a linked Amazon Connect instance in another AWS Region. + Provision and manage phone numbers that are global and accessible in both Regions. + Distribute telephony traffic and agents across Amazon Connect instances and Regions in 10% increments, or shift them all at once. This enables you to slowly shift inbound voice contacts and agents across Regions or shift them all at the same time. For example, you can distribute inbound voice contacts and agents 100% in US East (N. Virginia) and 0% in US West (Oregon), or 50% in each Region. + Access reserved capacity across Regions. **Topics** + [Global Resiliency requirements](connect-global-resiliency-requirements.md) + [Get started](get-started-connect-global-resiliency.md) + [Manage traffic distribution groups](manage-traffic-distribution-groups.md) + [Manage phone numbers across Regions](manage-phone-numbers-across-regions.md) + [Manage chat across Regions](manage-chat-across-regions.md) + [Metrics, Reports and Search across ACGR Regions](metrics-reports-and-search-across-acgr-regions.md) # Amazon Connect Global Resiliency requirements If you have decided that Amazon Connect Global Resiliency is the appropriate deployment for you, ensure you adhere to the following pre-requisites before onboarding: + [Port](about-porting.md) all phone numbers you want to enable to be multi-region to Amazon Connect. + AWS Enterprise Support or AWS Unified Operations is required to onboard to Amazon Connect Global Resiliency. For more information about AWS Support plans, see [AWS Support Plans ](https://aws.amazon.com/premiumsupport/plans/). + You must have an existing production [SAML 2.0-enabled](connect-identity-management.md) Amazon Connect instance in a Region where Amazon Connect Global Resiliency is available. To confirm, see [Global Resiliency availability by Region](regions.md#gr_region). + It is recommended to onboard and test Amazon Connect Global Resiliency services in a test environment before onboarding production traffic. + Request that ALL service quotas in the replica instance match the service quotas in the source instance: [Create a service quota increase case](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) in the AWS Management Console > Support. + Ensure your Lambda functions across AWS Regions have the same name. + Update your flows to replace any hardcoded Regions with a `$.AwsRegion` or `$['AwsRegion']` parameter. **Note** In the [AWS Lambda function](invoke-lambda-function-block.md) block, `$.AwsRegion` is not allowed in the flowArn. To use `$.AwsRegion`, you need to use a [Set contact attributes](set-contact-attributes.md) block to set the flow, for example: `flowIdKey` : `arn:aws:connect:$.AwsRegion:123456789012:instance/12345678-1234-1234-1234-123456789012/contact-flow/12345678-1234-1234-1234-123456789012` Then later use that attribute key in the [AWS Lambda function](invoke-lambda-function-block.md) block as `${flowIdKey}`. `$.AwsRegion` is supported only for Lambda ARN and Lex ARN. + For Amazon Lex bots, you can do one of the following: + Use Amazon Lex Global Resiliency to replicate bots across AWS Regions and retain the bot ID. + Change your flows to branch based on the AWS Region where the flow is running. At flow runtime, these parameters are replaced with the Region where the flow is run, as shown in the following example. ![\[The properties page of the check contact attributes block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/acgr-requirements.png) # Get started with Amazon Connect Global Resiliency **Important** Amazon Connect instances created before March 31, 2021, were assigned a domain with the following format: ``` https://your-instance-alias.awsapps.com/connect/ ``` If your domain uses the older format, you won’t be able to properly configure the Amazon Connect Global Resiliency feature. To enable this feature, you’ll need to [update your domain](update-your-connect-domain.md) to the newer format: ``` https://your-instance-alias.my.connect.aws/ ``` **Note** **New user?** Check out the [Amazon Connect Global Resiliency Workshop](https://catalog.workshops.aws/amazon-connect-global-resiliency/en-US). This online course guides you through the process of onboarding and testing phone number and agent failover using new APIs through the AWS CLI. Global Resiliency is available only for Amazon Connect instances created in the following AWS Regions: US East (N. Virginia), US West (Oregon), Asia Pacific (Osaka), Asia Pacific (Tokyo), Europe (Frankfurt), and Europe (London). You can only create a replica in the US East (N. Virginia) Region if your source is US West (Oregon), or the other way around. You can only create a replica in the Europe (Frankfurt) Region if your source is Europe (London), or the other way around. You can only create a replica in Asia Pacific (Osaka) Region if your source is Asia Pacific (Tokyo). To obtain access to this feature, contact your Amazon Connect Solutions Architect or Technical Account Manager. You get started with Amazon Connect Global Resiliency by creating a replica of your existing Amazon Connect instance in another AWS Region, and by creating a traffic distribution group. A *traffic distribution group* is an Amazon Connect resource that enables you to link Amazon Connect instances that are in different AWS Regions. Phone numbers can be attached to the traffic distribution group. Traffic to these numbers can be distributed between the instances in the traffic distribution group. ## How to set up Amazon Connect Global Resiliency 1. [Create a replica of your existing Amazon Connect instance](create-replica-connect-instance.md). Use the [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API. 1. [Create a traffic distribution group](setup-traffic-distribution-groups.md). 1. Use the [CreateTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateTrafficDistributionGroup.html) API. 1. Use [DescribeTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeTrafficDistributionGroup.html) API to determine whether the traffic distribution group has been created successfully (`Status` must be `ACTIVE`). 1. [Claim phone numbers to your traffic distribution group](claim-phone-numbers-traffic-distribution-groups.md). After your traffic distribution group has been created successfully (`Status` is `ACTIVE`), you can claim phone numbers to it using the [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) API. **Note** The default traffic distribution for these phone numbers is set to 100% - 0%. That is, 100% of inbound telephony traffic will go to the source Amazon Connect instance that was used to create a replica. In addition, after phone numbers are claimed to an instance, you can assign them to multiple instances across AWS Regions. To do this, use the [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) API to assign the numbers to a traffic distribution group. 1. [Update your traffic distribution](update-telephony-traffic-distribution.md). Use the [UpdateTrafficDistribution](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateTrafficDistribution.html) API to distribute traffic across the linked instances in 10% increments. # Create a replica of your existing Amazon Connect instance **Note** **New user?** Check out the [Amazon Connect Global Resiliency Workshop](https://catalog.workshops.aws/amazon-connect-global-resiliency/en-US). This online course guides you through the process of onboarding and testing phone number and agent failover using new APIs through the AWS CLI. Global Resiliency is available only for Amazon Connect instances created in the following AWS Regions: US East (N. Virginia), US West (Oregon), Asia Pacific (Osaka), Asia Pacific (Tokyo), Europe (Frankfurt), and Europe (London). You can only create a replica in the US East (N. Virginia) Region if your source is US West (Oregon), or the other way around. You can only create a replica in the Europe (Frankfurt) Region if your source is Europe (London), or the other way around. You can only create a replica in Asia Pacific (Osaka) Region if your source is Asia Pacific (Tokyo). To obtain access to this feature, contact your Amazon Connect Solutions Architect or Technical Account Manager. You call the [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API to create a replica of your Amazon Connect instance in another AWS Region and to copy configuration information for Amazon Connect resources across AWS Regions. **Topics** + [Important things to know](#important-info-automated-config) + [Characteristics of the replica instance](#replica-characteristics) + [What resources are mirrored in the replica instance](#mirrored-resources) + [What to do after the replica instance is created](#configure-replica-instance) + [When to contact AWS Support](#replica-cs) + [Why a ReplicateInstance call fails](#why-replicateinstance-fails) + [Find the source Region of your instance](#how-to-find-source-region-of-instances) ## Important things to know + Before running [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html): + Make sure you have the minimum required IAM permissions to create an instance. See [Required permissions for using custom IAM policies to manage access to the Amazon Connect console](security-iam-amazon-connect-permissions.md). + Update your flows to replace any hardcoded Regions with a `$.AwsRegion` or `$['AwsRegion']` parameter. At flow runtime, these parameters are replaced with the Region where the flow is run. + Ensure your Lambda functions across AWS Regions have the same name. + For Amazon Lex bots, you can do one of the following: + Use Amazon Lex Global Resiliency to replicate bots across AWS Regions and retain the bot ID. + Change your flows to branch based on the AWS Region where the flow is running. At flow runtime, these parameters are replaced with the Region where the flow is run, as shown in the following example. ![\[The properties page of the check contact attributes block.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/acgr-requirements.png) + To allow AWS managed keys in the replica instance, using the AWS console, create a temporary Amazon Connect instance in the Region where you are planning to create the replica instance. This will create the default AWS managed keys for Amazon Connect. + [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) copies the Amazon Connect configuration across AWS Regions as part of the initial replication process. After this first step completes, any changes made to either the original or [mirrored resources](#mirrored-resources) at a later time are continuously synchronized. This happens bidirectionally, from source to replica, and from the replica to the source. + All phone numbers on the source instance that aren't already associated to number groups are automatically added to the default traffic distribution group. This step enables the phone numbers to be available in both source and replica Regions, and enables phone number-flow associations to be mirrored across AWS Regions. + For instances in Asia Pacific (Tokyo), only phone numbers that are explicitly enabled for Amazon Connect Global Resiliency (ACGR) will support complete replication behavior to Asia Pacific (Osaka). When routing through Asia Pacific (Osaka), inbound calls may experience delivery times of up to 20 seconds. + Emergency access to log into the replica instance is available only after the default routing profile and queue have been mirrored across the Regions. + As the configuration is propagated across AWS Regions, you can view the progress in AWS CloudTrail logs. Or, in the Amazon Connect admin website you can navigate to **User management**, **View historical changes** to view an audit trail of changes to the users. Audit trails are also available for other configurations. + You may see the following errors in the CloudTrail log which do not impact the configurations mirroring. + Http 409 (conflict) errors: These errors occur due to mirroring conflicts when processing multiple configuration updates made to the same contact center resource in quick succession. While these errors might appear in your logs, they do not impact the actual mirroring of your contact center resources. + A resource name conflict will occur if resources in the source instance and the replica instance have the same name but different resource IDs. This might happen, for example, if the resource in the replica instance was created manually outside of the replication process. In the case of resource name conflicts, [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) doesn't synchronize the resource across Regions. Instead it throws a `ResourceConflictException` error. After you resolve the name conflict (for example, delete the resource in the replica instance), you can run `ReplicateInstance` again to synchronize the resource. + After running `ReplicateInstance`, you must use the [AssociateTrafficDistributionGroupUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociateTrafficDistributionGroupUser.html) API to associate agents to either the default traffic distribution group or a custom traffic distribution group. + Running [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) does not synchronize Lambda functions or Amazon Lex bots, or other third-party / integrations you may have. ## Characteristics of the replica instance + The replica Amazon Connect instance is created in the same AWS account as your existing Amazon Connect instance. + [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) creates a default traffic distribution group if one doesn't already exist. This default traffic distribution group has three types of traffic distribution: + Sign in + Agent + Telephony Use the [CreateTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateTrafficDistributionGroup.html) API to create more traffic distribution groups, however, these additional traffic distribution groups are not default traffic distribution groups and thus only support agent and telephony distributions. + The default traffic distribution group is the only traffic distribution group where you can change the `SignInConfig` distribution. See the `IsDefault` parameter in the [TrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_TrafficDistributionGroup.html) data type. + You use `SignInConfig` to choose the backend sign-in servers to facilitate the agent signing in to their Amazon Connect instance. For example, if you call `UpdateTrafficDistribution` with a modified `SignInConfig` and a non-default `TrafficDistributionGroup`, an `InvalidRequestException` is returned. + The replica instance has the same instance ID as the Amazon Connect instance it is replicated from. ## What resources are mirrored in the replica instance [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) mirrors the following Amazon Connect resources across AWS Regions. **Important** The service quotas for these resources are automatically matched across AWS Regions *before* the resources are mirrored across Regions. To increase any other quota in the replica instance, submit a request. + Agent proficiencies + Flows + Flow modules + Users + Routing profiles + Queues + Security profiles + Hours of operation + Quick connects + Predefined attributes + Prompts (not including those stored in S3) + User hierarchies (groups and levels) + Agent status + Predefined attributes + Saved reports + Views + Data tables + Workspaces + Flow Module Versions + Flow Module Aliases + Custom Metrics + Test Cases + Notifications **Important notes about specific resources** **Saved reports**: While saved reports are replicated, the schedules associated with saved reports are *not* replicated. **Views**: Only Views in a *published* state are replicated. Views in a draft state are *not* replicated. **Data tables**: Data Table values that contain literal ARN references will automatically adjust the region code to the local region when replicated. ARNs constructed using expressions may not automatically adjust the region code. [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) also replicates the following associations across AWS Regions: + Phone number to flow + Queue to routing profile + User to security profile, routing profile, and user hierarchy + Routing profiles + Queue to quick connects + Queue to hours of operation + Queue to flow **Note** After initial replication, configuration changes are replicated bidirectionally between replicated instances in near real-time. If this fails, Amazon Connect Global Resiliency attempts to sync updates within 30 minutes. ## What to do after the replica instance is created After your replica Amazon Connect instance is created, you need to configure it: 1. Ensure redundancy for front-end and back-end integrations (for example, SSO, Lambda, Lex) across Regions. 1. Make matching manual updates across the linked instances. 1. Use the [AssociateTrafficDistributionGroupUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociateTrafficDistributionGroupUser.html) API to associate agents to the default traffic distribution group. Before you can associate agents to a traffic distribution group, they must be present on both the source and replica instances. You cannot associate users to a traffic distribution group when they are newly added to source instance and not yet in the replica. ## When to contact AWS Support Contact AWS Support for help with the following activities: + To understand mirroring status beyond what's available in the CloudTrail logs and audit trail in the Amazon Connect admin website. ## Why a ReplicateInstance call fails A [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API call fails with an `InvalidRequestException` in the following cases: 1. The Region where you are creating the replica is the same Region as your existing instance. 1. The instance was already replicated as part of a different [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API call. 1. The instance does not have an alias. 1. The instance is not in `ACTIVE` status. 1. The instance does not have SAML enabled. 1. There is a resource name conflict. ## How to find the source Region of your Amazon Connect instances If you forget which Region is your source Region for your Amazon Connect instances, perform the following steps to find it: 1. Call the [ListTrafficDistributionGroups](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListTrafficDistributionGroups.html) API with your `InstanceId`. 1. For any traffic distribution group in the response list, the returned `InstanceARN` includes the source Region. For example in the following ARN, *source-region* would be the Region of your Amazon Connect instance. `arn:aws:connect:source-region:account-id:traffic-distribution-group/ traffic-distribution-group-id` # Create traffic distribution groups for your Amazon Connect instance You can create a traffic distribution group for your existing Amazon Connect instance by using the [CreateTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateTrafficDistributionGroup.html) API. A *traffic distribution group* is an Amazon Connect resource that enables you to link Amazon Connect instances that are in different AWS Regions. Phone numbers can be attached to the traffic distribution group. Traffic to these numbers can be distributed between the instances in the traffic distribution group. ## Important things to know + When creating a traffic distribution group, it must be created in the source AWS Region. A *source Region* is the Region where you set up your existing Amazon Connect instance. + When associating phone numbers to a traffic distribution group: + You can associate only phone numbers that are claimed in the source Region. + The phone number must be in the same Region as where the traffic distribution group was created. + You can claim numbers to a traffic distribution group, or get or update traffic distribution for a traffic distribution group only when its `Status` is `ACTIVE`. Use the [DescribeTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeTrafficDistributionGroup.html) API to determine whether it has been created successfully (`Status` must be `ACTIVE`). + When you create a replica Amazon Connect instance, a default traffic distribution group is created for it. The default traffic distribution group is the only traffic distribution group where you can change the `SignInConfig` distribution. See the `IsDefault` parameter in the [TrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_TrafficDistributionGroup.html) data type. You use `SignInConfig` to choose which backend sign-in servers are used to facilitate the agent signing in to their Amazon Connect instance. For example, if you call `UpdateTrafficDistribution` with a modified `SignInConfig` and a non-default `TrafficDistributionGroup`, an `InvalidRequestException` is returned. ## Traffic distribution group statuses Following is a description of the traffic distribution group statuses: + `CREATION_IN_PROGRESS`: Traffic distribution group creation is in progress. + `ACTIVE`: Traffic distribution group has been created. + `CREATION_FAILED`: Traffic distribution group creation failed. + `PENDING_DELETION`: Traffic distribution group deletion is in progress. + `DELETION_FAILED`: Traffic distribution group deletion failed. + `UPDATE_IN_PROGRESS`: Traffic distribution group update is in progress. ## Why a CreateTrafficDistributionGroup call fails A [CreateTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateTrafficDistributionGroup.html) API call fails with an `InvalidRequestException` in the following cases: + The [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API was not called before creating a traffic distribution group for the linked instances. + The [CreateTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateTrafficDistributionGroup.html) API was not called in the same Region where the [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API was called. The Region where this API is called must match the Region of the instance that was used to create a replica. # Claim phone numbers to traffic distribution groups using Amazon Connect **Note** **New user?** Check out the [Amazon Connect Global Resiliency Workshop](https://catalog.workshops.aws/amazon-connect-global-resiliency/en-US). This online course guides you through the process of onboarding and testing phone number and agent failover using new APIs through the AWS CLI. Global Resiliency is available only for Amazon Connect instances created in the following AWS Regions: US East (N. Virginia), US West (Oregon), Asia Pacific (Osaka), Asia Pacific (Tokyo), Europe (Frankfurt), and Europe (London). You can only create a replica in the US East (N. Virginia) Region if your source is US West (Oregon), or the other way around. You can only create a replica in the Europe (Frankfurt) Region if your source is Europe (London), or the other way around. You can only create a replica in Asia Pacific (Osaka) Region if your source is Asia Pacific (Tokyo). To obtain access to this feature, contact your Amazon Connect Solutions Architect or Technical Account Manager. After your traffic distribution group is created successfully (`Status` is `ACTIVE`), you can use [SearchAvailablePhoneNumbers](https://docs.aws.amazon.com/connect/latest/APIReference/API_SearchAvailablePhoneNumbers.html) to search for available phone numbers and [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) to claim them. Before you claim a phone number to your traffic distribution group, we recommend using the [DescribeTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeTrafficDistributionGroup.html) API to verify the status of the traffic distribution group is `ACTIVE`. Assigning a phone number to a traffic distribution group that isn't `ACTIVE` results in `ResourceNotFoundException`. You can claim a phone number to a traffic distribution group by providing the traffic distribution group ARN in the **TargetArn** parameter when calling the [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) API. You can also use the [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) API to assign a phone number previously claimed to an instance to a traffic distribution group. **Note** To update the **Description** field, you must use the Amazon Connect console. ## Example workflow Following is an example workflow to claim phone numbers and use them across multiple AWS Regions: 1. Create a replica of your instance: 1. Call the [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API. 1. Create a traffic distribution group that links these instances together: 1. Call the [CreateTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateTrafficDistributionGroup.html) API. 1. Find available phone numbers that can be claimed to your traffic distribution group: 1. Call the [SearchAvailablePhoneNumbers](https://docs.aws.amazon.com/connect/latest/APIReference/API_SearchAvailablePhoneNumbers.html) API in the Region where the traffic distribution group was created. Provide the traffic distribution group ARN for the `TargetArn` parameter. 1. In the Region where the traffic distribution group was created, call the [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) API: 1. Provide your traffic distribution group ARN for the `TargetArn` parameter. 1. Provide the E164 phone number value that was returned by the [SearchAvailablePhoneNumbers](https://docs.aws.amazon.com/connect/latest/APIReference/API_SearchAvailablePhoneNumbers.html) API call in step 3. A `PhoneNumberId` and `PhoneNumberArn` are returned. You can use these values for follow-up operations. 1. Verify that the phone number status is `CLAIMED`: 1. Call the [DescribePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribePhoneNumber.html) API. (DescribePhoneNumber can also be called in the other Region associated with the traffic distribution group. It will return the same phone number details.) The phone number can be used by follow-up operations only after its status is `CLAIMED`. For a description of possible statuses, see [Phone number statuses defined](#claim-phone-number-status). 1. Repeat steps 3-5 for all phone numbers you need to claim to your traffic distribution group. 1. Perform the following steps to associate flows to phone numbers. Do them in both Regions where the traffic distribution group operates. These steps ensure your telephony traffic will route correctly to your flows to support your traffic distribution configuration. 1. In your existing Amazon Connect instance in the Region where the traffic distribution group was created, do the following steps: 1. Call [ListContactFlows](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListContactFlows.html) API. Provide the `InstanceId` that corresponds to the instance that was replicated. 1. A list of flow ARNs is returned. Use these flow ARNs to associate a flow to a phone number; call the [AssociatePhoneNumberContactFlow](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociatePhoneNumberContactFlow.html) API. 1. In the replicated Amazon Connect instance in the other AWS Region, do the following steps: 1. Call [ListContactFlows](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListContactFlows.html) API. Provide the `InstanceId` that corresponds to the instance that was replicated. 1. A list of flow ARNs is returned. Use these flow ARNs to associate a flow to a phone number; call the [AssociatePhoneNumberContactFlow](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociatePhoneNumberContactFlow.html) API. ## Why a ClaimPhoneNumber call fails Your [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) API call will fail with a `ResourceNotFoundException` in the following cases: + The specified traffic distribution group does not exist, the status of the traffic distribution group is not `ACTIVE`, or you do not have ownership of the traffic distribution group. + The phone number is not available for claiming. In some cases, a phone number found from [SearchAvailablePhoneNumbers](https://docs.aws.amazon.com/connect/latest/APIReference/API_SearchAvailablePhoneNumbers.html) may have been claimed by another customer. [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) will fail with a `InvalidParameterException` error in the following case: + The endpoint you are calling is not in the same Region where the traffic distribution group was created. ## Phone number statuses defined Following is a description of phone number statuses: + `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), [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 includes a message indicating the failure reason. A common reason for a failure is 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. # Assign claimed phone numbers to traffic distribution groups in Amazon Connect + You created a new traffic distribution group and it's status is `ACTIVE`. We recommend using the [DescribeTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeTrafficDistributionGroup.html) API to verify the status. + You have already claimed phone numbers to instances or other traffic distribution groups. Now you can assign those claimed phone numbers to your new traffic distribution group by using the [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) API. Provide the traffic distribution group ARN in the `TargetArn` parameter. **Note** To update the **Description** field, you must use the Amazon Connect console. ## Example workflow Following is an example workflow to assign claimed phone numbers to your traffic distribution group: 1. Call the [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) API to assign the phone number to a new `TargetArn`. The `TargetArn` can be for another Amazon Connect instance or for a traffic distribution group created in the same Region where the phone number was initially claimed. 1. Perform the following steps to associate flows to phone numbers. These steps ensure your telephony traffic will route correctly to your flows to support your traffic distribution configuration. 1. In your existing Amazon Connect instance in the Region where the traffic distribution group was created, do the following steps: 1. Call the [ListContactFlows](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListContactFlows.html) API. Provide the `InstanceId` that corresponds to the instance that was replicated. 1. A list of flow ARNs is returned. Use these flow ARNs to associate a flow to a phone number; call the [AssociatePhoneNumberContactFlow](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociatePhoneNumberContactFlow.html) API. The phone number to flow association will be mirrored between Amazon Connect instances across AWS Regions. ## Why an AssociatePhoneNumberContactFlow call fails If the number is claimed to a traffic distribution group, and you are calling [AssociatePhoneNumberContactFlow](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociatePhoneNumberContactFlow.html) using an instance in the AWS Region where the traffic distribution group was created, you can use either a full phone number ARN or UUID value for the `PhoneNumberId` URI request parameter. However, if the number is claimed to a traffic distribution group and you are calling this API using an instance in the replica AWS Region associated with the traffic distribution group, you must provide a full phone number ARN. If a UUID is provided in this scenario, you will receive a `ResourceNotFoundException`. ## Why an UpdatePhoneNumber call fails Your [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) API call will fail with a `ResourceNotFoundException` in the following case: + The specified traffic distribution group does not exist, the status of the traffic distribution group is not `ACTIVE`, or you do not have ownership of the traffic distribution group. [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) will fail with a `InvalidParameterException` error in the following case: + The endpoint you are calling is not in the same Region where the traffic distribution group was created. ## Phone number statuses defined Following is a description of phone number statuses: + `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), [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 includes a message indicating the failure reason. A common reason for a failure is that the `TargetArn` value you are claiming or updating a phone number to has reached its limit of total claimed numbers. # Update telephony traffic distribution across Amazon Connect instances and AWS Regions You use the [UpdateTrafficDistribution](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateTrafficDistribution.html) API to distribute telephony traffic and [shift agents](update-agents-across-regions.md) across Regions. **Note** When you shift telephony traffic, also shift agents and/or agent sign-ins to ensure they can handle the calls in the other Region. If you don't shift the agents, voice calls will go to the shifted Region but there won't be any agents available to receive the calls. After you have claimed phone numbers to your traffic distribution group, you can use the [UpdateTrafficDistribution](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateTrafficDistribution.html) API to distribute inbound voice contacts across linked instances in a given traffic distribution group in 10% increments. If the following requirements are not met, your [UpdateTrafficDistribution](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateTrafficDistribution.html) API call will fail with an `InvalidRequestException`: + You must provide distribution for telephony traffic configuration. + You must specify the traffic distribution for both linked instances and the total distribution must add up to 100%. + You must specify traffic distribution in 10% increments. + The instance ARNs specified in the telephony configuration must match the ARNs of the linked instances. When you call `UpdateTrafficDistribution` from the source AWS Region you can use either the traffic distribution group ID or Amazon Resource Name (ARN). When you call `UpdateTrafficDistribution` in the replica Region, you must use the traffic distribution group ARN. # Set up your agent's experience with Amazon Connect Global Resiliency Amazon Connect Global Resiliency enables you to provide a global experience for agents with global sign-in, agent distribution API, and Agent Workspace enhancements. With this set of features, you can: + Enable your agents to sign in once at the beginning of their day and process contacts from their current active Region without needing to know which Region is active at any time. + Add agents to your traffic distribution group and distribute agents across AWS Regions. + Redirect new inbound voice contacts to the agent workspace for the current active Region with a simple page refresh. **Topics** + [Integrate your IdP with an Amazon Connect Global Resiliency SAML sign in endpoint](integrate-idp.md) + [Associate agents to instances across multiple AWS Regions](associate-agents-across-regions.md) + [Update agent distribution across Regions](update-agents-across-regions.md) + [Set up Agent Workspace](setup-agentworkspace-switchover.md) + [Tips for avoiding issues when shifting agents across Regions](possible-issues-shifting-regions.md) # Integrate your identity provider (IdP) with an Amazon Connect Global Resiliency SAML sign in endpoint To enable your agents to sign in once and be logged into both AWS Regions to process contacts from the current active Region, you need to configure IAM settings to use the global sign in SAML endpoint. ## Before you begin You must enable SAML for your Amazon Connect instance to use Amazon Connect Global Resiliency. For information about getting started with IAM federation, see [Enabling SAML 2.0 federated users to access the AWS Management Console](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-saml.html). ## Important things to know + Agent failover is only supported when using the global sign-in endpoint. + To perform the steps in this topic, you'll need your instance ID. For instructions about how to find it, see [Find your Amazon Connect instance ID or ARN](find-instance-arn.md). + You will also need to know the source Region of your Amazon Connect instances. For instructions about how to find it, see [How to find the source Region of your Amazon Connect instances](create-replica-connect-instance.md#how-to-find-source-region-of-instances). + If you are embedding your Connect application within an iframe, you must ensure that your domain is present in the list of Approved Origins in both your source and replica instance in order for global sign-in to work. To configure Approved Origins at the instance level, follow the steps in [Use an allowlist for integrated applications in Amazon Connect](app-integration.md). + Agents must be created already in *both* your source and replica Amazon Connect instances and have the same username as the role session name from your identity provider (IdP). Otherwise, you will receive a `UserNotOnboardedException` exception and risk losing agent redundancy capabilities between your instances. + You must associate agents to a traffic distribution group before agents attempt to sign in. Otherwise agent sign-in will fail with a `ResourceNotFoundException`. For information about how to setup your traffic distribution groups and associate agents to them, see [Associate agents to Amazon Connect instances across multiple AWS Regions](associate-agents-across-regions.md). + When your agents federate into Amazon Connect with the new SAML sign-in URL, Amazon Connect Global Resiliency always attempts to log the agent into both your source and replica Regions / instances, no matter how `SignInConfig` is configured in your traffic distribution group. You can verify this by checking CloudTrail logs. + The `SignInConfig` distribution in your default traffic distribution group only determines which AWS Region is used to facilitate sign-in. Regardless of how your `SignInConfig` distribution is configured, Amazon Connect always attempts to sign in agents to both Regions of your Amazon Connect instance. + After replicating an Amazon Connect instance, only one SAML sign-in endpoint is generated for your instances. This endpoint always contains the source AWS Region in the URL. + You don't need to configure a relay state when using the personalized SAML sign-in URL with Amazon Connect Global Resiliency. ## How to integrate your identity provider 1. When you create a replica of your Amazon Connect instance using the [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API, a personalized SAML sign-in URL is generated for your Amazon Connect instances. The URL is generated in the following format: `https://instance-id.source-region.sign-in.connect.aws/saml` 1. *instance-id* is the instance ID for either instance in your instance group. The instance ID is identical in the source and replica Regions. 1. *source-region* corresponds to the source AWS Region in which the [ReplicateInstance](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReplicateInstance.html) API was called. 1. Add the following trust policy to your IAM Federation role. Use the URL for the global sign-in SAML endpoint as shown in the following example. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Federated":[ "arn:aws:iam::111122223333:saml-provider/MySAMLProvider" ] }, "Action":"sts:AssumeRoleWithSAML", "Condition":{ "StringLike":{ "SAML:aud":[ "https://instance-id.source-region.sign-in.connect.aws/saml*" ] } } } ] } ``` ------ **Note** `saml-provider-arn` is the identity provider resource created in IAM. 1. Grant access to `connect:GetFederationToken` for your `InstanceId` on your IAM Federation role. For example: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "GetFederationTokenAccess", "Effect": "Allow", "Action": "connect:GetFederationToken", "Resource": "*", "Condition": { "StringEquals": { "connect:InstanceId": "your-instance-id" } } } ] } ``` ------ 1. Add an attribute mapping to your identity provider application using the following attribute and value strings. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/integrate-idp.html) 1. Configure the Assertion Consumer Service (ACS) URL of your identity provider to point to your personalized SAML sign-in URL. Use the following example for the ACS URL: ``` https://instance-id.source-region.sign-in.connect.aws/saml?&instanceId=instance-id&accountId=your AWS account ID&role=saml-federation-role&idp=your SAML IDP&destination=optional-destination ``` 1. Set following fields in the URL parameters: + `instanceId`: The identifier of your Amazon Connect instance. For instructions about how to find your instance ID, see [Find your Amazon Connect instance ID or ARN](find-instance-arn.md). + `accountId`: The AWS account ID where the Amazon Connect instances are located. + `role`: Set to the name or Amazon Resource Name (ARN) of the SAML role used for Amazon Connect federation. + `idp`: Set to the name or Amazon Resource Name (ARN) of the SAML identity provider in IAM. + `destination`: Set to the optional path where agents will land in the instance after signing in (for example: `/agent-app-v2`). # Associate agents to Amazon Connect instances across multiple AWS Regions To allow your agents to sign-in to both AWS Regions and process contacts from either Region, you must first assign them to a traffic distribution group. 1. If you have not yet set up a traffic distribution group, do so now. For instructions, see [Create traffic distribution groups for your Amazon Connect instance](setup-traffic-distribution-groups.md). 1. After your traffic distribution group is created successfully (`Status` is `ACTIVE`), you can assign agents to it. Always associate users to a traffic distribution group in the source Region. Assigning an agent to a traffic distribution group without an `ACTIVE` status results in `ResourceNotFoundException`. Use the [DescribeTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeTrafficDistributionGroup.html) API to determine whether it has been created successfully (`Status` must be `ACTIVE`). 1. You can assign an agent to a traffic distribution group by calling the [AssociateTrafficDistributionGroupUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociateTrafficDistributionGroupUser.html) API. ## Examples The following `associate-traffic-distribution-group-user` example command shows how agents can be associated to and used across multiple AWS Regions. ``` aws connect associate-traffic-distribution-group-user --traffic-distribution-group-id UUID --user-id UUID --instance-id ``` The following [AssociateTrafficDistributionGroupUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociateTrafficDistributionGroupUser.html) example associates an agent with a traffic distribution group. ``` PUT /traffic-distribution-group/trafficDistributionGroupId/user HTTP/1.1 Content-type: application/json { "UserId": "string" } ``` The following `disassociate-traffic-distribution-group-user` example command disassociates an agent from a traffic distribution group. ``` aws connect disassociate-traffic-distribution-group-user --instance-id your instance ID --traffic-distribution-group-id UUID --user-id UUID ``` The following [DisassociateTrafficDistributionGroupUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_DisassociateTrafficDistributionGroupUser.html) example disassociates an agent from a traffic distribution group. ``` DELETE /traffic-distribution-group/trafficDistributionGroupId/user/UserId HTTP/1.1 ``` ## Why an AssociateTrafficDistributionGroupUser call fails An [AssociateTrafficDistributionGroupUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociateTrafficDistributionGroupUser.html) API call fails with an `ResourceNotFoundException` in the following cases: 1. The specified traffic distribution group does not exist. 1. The status of the traffic distribution group is not `ACTIVE`. 1. The `user-id UUID` is not a user from the source Amazon Connect instance. # Update agent distribution in your Amazon Connect agent workspace across AWS Regions Just as you can use the `UpdateTrafficDistribution` API to [distribute telephony traffic across Regions](update-telephony-traffic-distribution.md), you can also use it to distribute agents across AWS Regions, either fully or gradually as part of regular operational readiness testing. For example, you might keep 40% of agents in one AWS Region to complete active contacts and shift the remaining agents to the replica Region. **Note** When you shift telephony traffic, also shift agents and/or agent sign-ins to ensure they can handle the calls in the other Region. If you don't shift the agents, voice calls will go to the shifted Region but there won't be any agents available to receive the calls. After you have added agents to your traffic distribution group, use the [UpdateTrafficDistribution](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateTrafficDistribution.html) API to distribute agents across linked instances in a given traffic distribution group in 10% increments. Your agents will be able to complete active voice contacts before shifting Regions. **Note** If an agent gets an error when they try to end a contact before shifting Regions, they need to refresh the agent workspace page. For more information, see [Set up Amazon Connect Agent Workspace to support agents shifting across AWS Regions](setup-agentworkspace-switchover.md). **Topics** + [Requirements](#update-agent-traffic-distribution-requirements) + [Enable both Regions during regular operations](#change-signin-weights) + [How to shift all telephony traffic and agents across AWS Regions](#shift-all-traffic) + [Regional switch UI banner](#regional-switch-ui-banner) ## Requirements If the following requirements are not met, your [UpdateTrafficDistribution](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateTrafficDistribution.html) API call will fail with an `InvalidRequestException`: 1. The specified traffic distribution group must exist. 1. The status of the traffic distribution group must be `ACTIVE`. 1. If you are changing the `SignInConfig` distribution, you can only do so for the default traffic distribution group. The default traffic distribution group is created when the replica Amazon Connect instance is created. See the `IsDefault` parameter in the [TrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_TrafficDistributionGroup.html) data type. When you call `UpdateTrafficDistribution` from the source AWS Region you can use either the traffic distribution group ID or Amazon Resource Name (ARN). When you call `UpdateTrafficDistribution` in the replica Region, you must use the traffic distribution group ARN. ## Enable both AWS Regions during regular operations The `UpdateTrafficDistribution` API includes a distribution called `SignInConfig`. It allows you to choose which backend sign-in servers are used to facilitate the agent signing in to their instance group. Regardless of the `SignInConfig` set in your traffic distribution group, agents will be signed in to both instances in the traffic distribution group. For the best experience, we recommend having both AWS Regions enabled during regular operations. To achieve this pass `true` to both `SignInConfig` distributions. If you need to shift your entire telephony traffic and agents across to one AWS Region, we recommend changing the `SignInConfig` to `false` for the Region you are shifting traffic away from. For example, the following call results in agents having a 50% chance of using the us-west-2 sign-in server and a 50% of using the us-east-1 sign-in server for a given login call from the identity provider. ``` aws connect update-traffic-distribution \ --id traffic distribution group ID or ARN \ --cli-input-json \ '{ "SignInConfig":{ "Distributions":[ { "Region":"us-west-2", "Enabled":true }, { "Region":"us-east-1", "Enabled":true } ] } }' ``` Conversely, the following sign-in distribution routes 100% of traffic on the sign-in endpoint to use the us-east-1 sign-in server. ``` aws connect update-traffic-distribution \ --id traffic distribution group ID or ARN \ --cli-input-json \ '{ "SignInConfig":{ "Distributions":[ { "Region":"us-west-2", "Enabled":false }, { "Region":"us-east-1", "Enabled":true } ] } }' ``` This distribution controls only which Region of the sign-in server is used to facilitate logging in the agent to both instances in their instance group. It doesn't affect the distribution of agents controlled by the `AgentConfig` part of the `UpdateTrafficDistribution` API. **Important** If the sign-in endpoint is not responsive during agent sign-in and your `SignInConfig` distribution is split across Regions, then you can resolve the errors by changing distribution to a single AWS Region. Or, if your `SignInConfig` is weighted on one Region and it isn't responsive, you can try shifting the `SignInConfig` to the disabled Region. Regardless of how your `SignInConfig` is configured, agents will still benefit from having a session active in both the source and replica Regions because they will attempt to sign into their Amazon Connect instance in both Regions. ## How to shift all telephony traffic and agents across AWS Regions To shift all new inbound voice contacts, agent sign-in distribution, and agent distribution from us-west-2 to us-east-1, use the following code snippet. ``` aws connect update-traffic-distribution \ --id traffic distribution group ID or ARN \ --cli-input-json \ '{ "SignInConfig":{ "Distributions":[ { "Region":"us-west-2", "Enabled":false }, { "Region":"us-east-1", "Enabled":true } ] }, "AgentConfig":{ "Distributions":[ { "Region":"us-west-2", "Percentage":0 }, { "Region":"us-east-1", "Percentage":100 } ] }, "TelephonyConfig":{ "Distributions":[ { "Region":"us-west-2", "Percentage":0 }, { "Region":"us-east-1", "Percentage":100 } ] } } ' ``` When you call `UpdateTrafficDistribution` from the source AWS Region you can use either the traffic distribution group ID or Amazon Resource Name (ARN). When you call `UpdateTrafficDistribution` in the replica Region, you must use the traffic distribution group ARN. ## Regional switch UI banner Agent Workspace and CCP will provide a UI banner highlighting region switch. If an agent is **on a contact** when their region changes due to traffic distribution group (TDG) adjustments, they will see a banner similar to below. Once they complete the voice contact and close the ACW state, the agent will automatically update to the new region—no action is needed. If the agent has trouble closing the contact, they can select **Continue in Backup** and a popup will appear seeking confirmation to switch over to the alternate region. We recommend you to adjust your run book and agent training guide to reflect this ![\[The Agent Workspace UI showing a banner that highlights regional failover during TDG adjustments.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/acgr-failover-banner.png) ![\[The confirmation popup that appears when an agent selects Continue in Backup.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/acgr-failover-confirmation.png) # Set up Amazon Connect Agent Workspace to support agents shifting across AWS Regions Perform the following steps to enable Amazon Connect Agent Workspace to embed the Contact Control Panel from the replica AWS Region to the source Region, and shift between them as agent's active Region changes. If you have not yet created a replica of your source Amazon Connect instance or set up a traffic distribution group, see [Get started with Amazon Connect Global Resiliency](get-started-connect-global-resiliency.md). 1. Go to the AWS Amazon Connect console to retrieve the **Access URL** for your source instance. Make a note of the URL. 1. In the replica Region, AWS Amazon Connect console to retrieve the **Access URL** for your replica instance. Make a note of the URL. 1. In the same window for your replica Amazon Connect instance, in the left pane choose **Approved origins**. 1. Add domain for source instance **Access URL**, which you noted in step 1. **Note** Do not include a trailing **/** in the access URL. 1. Repeat the above steps on your source instance: Go to **Approved origins**, add the access URL for the replica instance. **Note** Agents must set their status to **Available** after they are shifted across Regions. # Tips for avoiding issues when shifting agents in your Amazon Connect instance across Regions + Whenever you update the traffic distribution for agents be sure to also update the traffic distribution for inbound voice contacts. Otherwise, you might end up in a situation where one Region is heavy on agents while the other is heavy on telephony traffic. + Before associating users to a traffic distribution group, make sure the same username exists in both the source and replica Amazon Connect instances. Otherwise, when you associate a user to a traffic distribution group but the user with the username does not exist in the replica Region, you will get an `InvalidRequestException` error. + You must call the [AssociateTrafficDistributionGroupUser](https://docs.aws.amazon.com/connect/latest/APIReference/API_AssociateTrafficDistributionGroupUser.html) API to associate agents to a traffic distribution group in the source Region. If you attempt to do this while in the replica Region, you will get a `ResourceNotFoundException` error. # Manage traffic distribution groups using Amazon Connect APIs The topics in this section describe how to manage traffic distribution groups by using Amazon Connect APIs. **Topics** + [List traffic distribution groups](list-traffic-distribution-groups.md) + [Delete traffic distribution groups](delete-traffic-distribution-groups.md) # List traffic distribution groups Use the [ListTrafficDistributionGroups](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListTrafficDistributionGroups.html) API to list all traffic distribution groups. You may want to list traffic distribution groups as a way of determining whether a particular Amazon Connect instance is part of any traffic distribution groups. # Delete traffic distribution groups in Amazon Connect Use the [DeleteTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeleteTrafficDistributionGroup.html) API to delete a traffic distribution group that is no longer needed. **Note** You cannot delete a traffic distribution group if phone numbers are claimed to it. You must first release phone numbers from the traffic distribution group by using the [ReleasePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReleasePhoneNumber.html) API. After that, you can delete the traffic distribution group. You cannot release numbers from a traffic distribution group by using the Amazon Connect console. Your [DeleteTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeleteTrafficDistributionGroup.html) API call will fail with an `ResourceInUseException` if phone numbers are still claimed to the traffic distribution group. # Manage phone numbers across Regions using Amazon Connect APIs The topics in this section describe how to manage phone numbers across AWS Regions by using Amazon Connect APIs. **Topics** + [Claim phone numbers to instances across multiple AWS Regions](claim-phone-number-multiple-regions.md) + [Move a claimed phone number to multiple instances across AWS Regions](move-phone-number-multiple-regions.md) + [Release numbers from traffic distribution groups](release-numbers-traffic-distribution-group.md) # Claim phone numbers to Amazon Connect instances across multiple AWS Regions **Note** **New user?** Check out the [Amazon Connect Global Resiliency Workshop](https://catalog.workshops.aws/amazon-connect-global-resiliency/en-US). This online course guides you through the process of onboarding and testing phone number and agent failover using new APIs through the AWS CLI. Global Resiliency is available only for Amazon Connect instances created in the following AWS Regions: US East (N. Virginia), US West (Oregon), Asia Pacific (Osaka), Asia Pacific (Tokyo), Europe (Frankfurt), and Europe (London). You can only create a replica in the US East (N. Virginia) Region if your source is US West (Oregon), or the other way around. You can only create a replica in the Europe (Frankfurt) Region if your source is Europe (London), or the other way around. You can only create a replica in Asia Pacific (Osaka) Region if your source is Asia Pacific (Tokyo). To obtain access to this feature, contact your Amazon Connect Solutions Architect or Technical Account Manager. To place or receive calls to a phone number across instances in multiple AWS Regions, you need to claim a phone number to a traffic distribution group. **To claim a phone number to a traffic distribution group** 1. Create a traffic distribution group by using the [CreateTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateTrafficDistributionGroup.html) API. 1. Describe your traffic distribution group by using the [DescribeTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeTrafficDistributionGroup.html) API to determine whether it has been created successfully (`Status` must be `ACTIVE`). 1. After your traffic distribution group has been created successfully (`Status` is `ACTIVE`), you can claim phone numbers to it by using the [ClaimPhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ClaimPhoneNumber.html) API. # Move a claimed phone number to multiple Amazon Connect instances across AWS Regions **Note** **New user?** Check out the [Amazon Connect Global Resiliency Workshop](https://catalog.workshops.aws/amazon-connect-global-resiliency/en-US). This online course guides you through the process of onboarding and testing phone number and agent failover using new APIs through the AWS CLI. Global Resiliency is available only for Amazon Connect instances created in the following AWS Regions: US East (N. Virginia), US West (Oregon), Asia Pacific (Osaka), Asia Pacific (Tokyo), Europe (Frankfurt), and Europe (London). You can only create a replica in the US East (N. Virginia) Region if your source is US West (Oregon), or the other way around. You can only create a replica in the Europe (Frankfurt) Region if your source is Europe (London), or the other way around. You can only create a replica in Asia Pacific (Osaka) Region if your source is Asia Pacific (Tokyo). To obtain access to this feature, contact your Amazon Connect Solutions Architect or Technical Account Manager. You can move a phone number that was previously claimed to an instance, and instead assign it to multiple instances across AWS Regions. You do this by assigning the phone number to a traffic distribution group. **To assign a phone number to a traffic distribution group** 1. Create a traffic distribution group using the [CreateTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateTrafficDistributionGroup.html) API. 1. Describe your traffic distribution group using the [DescribeTrafficDistributionGroup](https://docs.aws.amazon.com/connect/latest/APIReference/API_DescribeTrafficDistributionGroup.html) API to determine whether it has been created successfully (`Status` must be `ACTIVE`). 1. After your traffic distribution group is created successfully (`Status` is `ACTIVE`), you can assign phone numbers that were previously claimed to other instances or other traffic distribution groups. Use the [UpdatePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdatePhoneNumber.html) API. # Release phone numbers in Amazon Connect from traffic distribution groups To release phone numbers from a traffic distribution group, us the [ReleasePhoneNumber](https://docs.aws.amazon.com/connect/latest/APIReference/API_ReleasePhoneNumber.html) API. The number is released back to inventory for other customers to claim it. You cannot release numbers from a traffic distribution group by using the Amazon Connect console. # Manage chat in your Amazon Connect instance across Regions You manage chat across AWS Regions by creating two custom chat interfaces or two out-of-the-box communication widgets: one in the source Region and another in the replica Region. You manually switch between them depending on which Region's chat interface or out-of-the-box communication widget you want to use. + Custom chat interfaces: Configure the chat interface in the replica Region to use the API endpoint of the replica Region. For examples of custom interfaces, see the [Amazon Connect open source library](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master) on GitHub. For more information, see [Customize chat with the Amazon Connect open source example](download-chat-example.md). + Out-the-box communication widgets: Create a communication widget in the replica Amazon Connect instance. For instructions, see [Configure a communication widget in the replica instance](#communicationswidget-multiple-regions). Following are the chat configuration parameters that are required in your website or app to initiate a client side chat: + **Amazon Connect instance ID** and **flow ID**: These parameters are the same in the source and replica Regions. + **Target AWS Region** and usually an **API endpoint** to start the chat (that is, to acquire the participant token): These parameters are different in the source and replica Regions. For example, the following diagram shows how the chat configuration needs to be updated to point to the API Gateway in the replica Region when chat traffic needs to be moved across Regions. ![\[A digram that shows the source Region and the replica Region.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/chatconfig.png) ## Configure a communication widget in the replica instance 1. On your source Amazon Connect instance, create a communication widget for chat if one doesn't already exist. For instructions, see [Add a chat user interface to your website hosted by Amazon Connect](add-chat-to-website.md). 1. On your replica instance, create another communication widget for chat. Configure the widget with the same flow that is used in the widget on the source instance. The flow is already in the replica instance because Amazon Connect Global Resiliency copies all flows from the source to replica and keeps them continuously synchronized. 1. Copy the new communication widget script that you created in the replica instance. Embed the script on the website or app that should be activated when chat traffic is forwarded to the replica instance. 1. To switch traffic between Regions, replace the source instance communications widget with the replica instance communications widget in your webpage. The following image shows an example widget script. ![\[A sample communication widget script.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/source-comwidget.png) 1. If you make any changes to the communication widget in the source instance at a later time, you also need to make the same changes in the communication widget in the replica instance. ## Option to add more seamlessness To make shifting chat traffic across Regions more seamless, and to require fewer manual changes, following is another way you can customize your chat experience: 1. Add a parameter to a centrally controlled database (for example, DynamoDB Global Table). The purpose of this parameter is to define which Region is currently active. 1. Update your website or application to check the status of the Region parameter in the central database. 1. Depending on which Region is active, the website or application will use that Region's API endpoint or communication widget. 1. This parameter should be updated at the same time that the [UpdateTrafficDistribution](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateTrafficDistribution.html) API is called to shift voice traffic and agents across Regions where applicable. # Metrics, Reports and Search across ACGR Regions The topics in this section describe consolidated metrics, reports and search across AWS Regions for Amazon Connect Global Resiliency (ACGR) customers. **Topics** + [Contact search and contact details](contact-search-and-contact-details.md) + [Consolidated metrics across Regions](consolidated-metrics-across-regions.md) # Contact search and contact details **Important** To enable consolidated contact search for your ACGR instance, please reach out to [AWS Support](https://console.aws.amazon.com/support/home). **Important** When you onboard to this feature, your Amazon Connect alias will be updated to a new sub-domain with the format `region.sourcealias.my.connect.aws`. For example, if your ACGR instance is deployed in US East (N. Virginia) and US West (Oregon) with source alias configured as `source.my.connect.aws` and replica alias as `replica.my.connect.aws`, after onboarding your Amazon Connect instances to this feature, the new sub-domains will be `us-east-1.source.my.connect.aws` and `us-west-2.source.my.connect.aws`. Additionally, supervisors and admins must be authenticated using the [global sign-in endpoint](integrate-idp.md) instead of regional endpoints. When you access the Contact Search page, you see contacts from your paired Amazon Connect Global Resiliency (ACGR) instances by default, giving you a complete view of customer interactions across your organization. This provides a seamless search experience regardless of which Region contacts originate from or which Region you are currently logged into. + **Active region**: The AWS Region where a contact is being processed or was completed. ## Contact search experience ### Active Region Filter You'll see a new 'Active region' filter in the filters dropdown. This allows you to narrow your search specific to a region when needed. To use the Active region filter: 1. On the **contact search page **, choose **Add filter**. 1. Select **Active region** from the dropdown. 1. Choose one or more Regions. ![\[The Active region filter dropdown showing available Regions to select.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/active-region-filter.png) ### Region-Specific Resource Filters When you use the following filters, the dropdown options display only resources that were created in your logged in region: + Custom contact attributes + Contact categories + Evaluation filters + Email address + Custom contact segment attributes **Important** When you manually type filter values instead of selecting from dropdowns, and those resource names are identical across ACGR instances, your results will include contacts from both Regions. Custom contact attributes Email address **Evaluation filters** only return contacts from your current Region, as they search using unique evaluation form IDs that are Region-specific. ### Saved Searches Your saved searches display contacts from both ACGR instances. Any previously saved Region filters continue to work as expected. ## Contact details experience ### Viewing contact information When you open a contact details page, you see comprehensive information regardless of which Region the contact originated from, including: + Overview, connection details, and queue information + Contact tags and attributes + Contact Lens data (conversational analytics, voice transcripts, chat transcripts) + Screen and audio recordings + Chat transcripts and IVR interactions + Email attachments and transcripts The contact's active Region is displayed on the contact details page under **Global resiliency metadata**. ![\[The contact details page showing the Global resiliency metadata section with the active Region information.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/global-resiliency-metadata.png) **Note** If the contact's active Region is impaired, some information may be unavailable, including screen and audio recordings, chat transcripts, IVR interactions, email attachments and transcripts, and Contact Lens data. ### Contact Lens data access You have full access to Contact Lens data across Regions, including: + In-progress contacts: Conversational analytics, voice transcripts (redacted and unredacted), and chat transcripts. + Completed contacts: All conversational analytics, voice transcripts (redacted and unredacted), and chat transcripts. + Recordings: Screen and audio recordings are accessible regardless of the contact's active Region. + Transcripts: Chat, IVR, and email transcripts are available across Regions. ### Contact actions You can perform contact actions such as Transfer, Reschedule, or End contact regardless of the contact's active Region. These actions route to the contact's active Region. ### Contact evaluations Contact evaluations are only available for contacts that are active in your logged in region. You cannot view or perform evaluations for replicated contacts from other regions. ### SearchContacts API If you use the SearchContacts API programmatically, the response includes additional information: + GlobalResiliencyMetadata object: Contains the `ActiveRegion`, `OriginRegion`, and `TrafficDistributionGroupId` fields for all contacts, showing the specific Region where the contact is active. For more information about the SearchContacts API, see the [Amazon Connect API Reference](https://docs.aws.amazon.com/connect/latest/APIReference/API_SearchContacts.html). # Consolidated metrics across Regions **Important** To enable consolidated agent and contact metrics for your ACGR instance, please reach out to [AWS Support](https://console.aws.amazon.com/support/home). When you view metrics in Amazon Connect, you see a consolidated view of agent and contact metrics across all your paired Regions, regardless of which Region you are currently logged into. For example, if you have 5 agents logged into us-east-1 and available for BasicQueue, and 10 agents logged into us-west-2 and available for BasicQueue, the real-time metrics page shows a total of 15 agents online. This consolidated view enables you to monitor your contact center operations within a single interface. ## Available metrics The consolidated view is available across: + Real-time metrics: View current agent activity and contact metrics across your ACGR instances. + Historical metrics: Access historical performance data across ACGR instances. + Metrics APIs: API responses return consolidated metrics across your ACGR instances. **Note** Agent and contact metrics are consolidated across Regions. Other metrics such as analytics remain Region-specific. For more information about Amazon Connect reporting, see [Metrics, dashboards, and reports in Amazon Connect](amazon-connect-metrics.md).