Claim phone numbers to traffic distribution groups using Amazon Connect - Amazon Connect
Example workflowWhy a ClaimPhoneNumber call failsPhone number statuses defined

Claim phone numbers to traffic distribution groups using Amazon Connect

Note

New user? Check out the Amazon Connect Global Resiliency Workshop. 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), 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. Similarly, you can only create a replica in the Europe (Frankfurt) Region if your source is Europe (London), or the other way around.

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 to search for available phone numbers and ClaimPhoneNumber to claim them.

Before you claim a phone number to your traffic distribution group, we recommend using the DescribeTrafficDistributionGroup 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 API. You can also use the UpdatePhoneNumber 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 API.

  2. Create a traffic distribution group that links these instances together:

    1. Call the CreateTrafficDistributionGroup API.

  3. Find available phone numbers that can be claimed to your traffic distribution group:

    1. Call the SearchAvailablePhoneNumbers API in the Region where the traffic distribution group was created. Provide the traffic distribution group ARN for the TargetArn parameter.

  4. In the Region where the traffic distribution group was created, call the ClaimPhoneNumber API:

    1. Provide your traffic distribution group ARN for the TargetArn parameter.

    2. Provide the E164 phone number value that was returned by the SearchAvailablePhoneNumbers API call in step 3.

    A PhoneNumberId and PhoneNumberArn are returned. You can use these values for follow-up operations.

  5. Verify that the phone number status is CLAIMED:

    1. Call the DescribePhoneNumber 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.

  6. Repeat steps 3-5 for all phone numbers you need to claim to your traffic distribution group.

  7. 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 API. Provide the InstanceId that corresponds to the instance that was replicated.

      2. A list of flow ARNs is returned. Use these flow ARNs to associate a flow to a phone number; call the AssociatePhoneNumberContactFlow API.

    2. In the replicated Amazon Connect instance in the other AWS Region, do the following steps:

      1. Call ListContactFlows API. Provide the InstanceId that corresponds to the instance that was replicated.

      2. A list of flow ARNs is returned. Use these flow ARNs to associate a flow to a phone number; call the AssociatePhoneNumberContactFlow API.

Why a ClaimPhoneNumber call fails

Your ClaimPhoneNumber 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 may have been claimed by another customer.

ClaimPhoneNumber 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 or UpdatePhoneNumber operation succeeded.

  • IN_PROGRESS means a ClaimPhoneNumber, UpdatePhoneNumber operation is still in progress and has not yet completed. You can call DescribePhoneNumber at a later time to verify if the previous operation has completed.

  • FAILED indicates that the previous ClaimPhoneNumber or UpdatePhoneNumber 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.