AWS Contact Center

Programmatically manage phone numbers using APIs in Amazon Connect

Several businesses require dynamic management of their contact center’s Toll free or Direct inward dial (DID)  phone numbers. This need may arise because of use cases such as rapid publishing of marketing hotline numbers, or releasing a new line of sales product or even to set up a brand new area of support. Additionally, associating or updating an IVR experience with these new numbers becomes critical to maintain relevant customer experience. When the need for such new phone numbers diminishes, some businesses may even chose to retire these phone numbers or IVR experiences.

Amazon Connect provides an easy graphical user interface(GUI) based experience to claim, manage and release phone numbers. However, several times organizations want to automate this experience programmatically and manage their phone numbers by APIs which can be triggered based on any use case.

Amazon Connect now provides APIs using which customers can automate this phone number administration. This mean they can programmatically claim a phone number and attach an Amazon Connect contact flow to it. This flow will then be invoked when customers call on the claimed phone number. Customers can also release a phone number that is not required using these APIs.

In this blog post, we will walk you through:- how you can programmatically claim a phone number, associate (or disassociate) a contact flow with a phone number, release a phone number, list phone numbers and describe them. You can use these examples as an extension to your existing solutions or modify them based on your specific needs.  In this post, an ‘art of the possible’, sample web user interface (UI) is used to trigger the API functions and populate different search results. Based on your use case, this web UI can easily be replaced with an in-house application or front-end utilities that need to invoke this API.

Overview of solution

This solution will be deployed using an AWS CloudFormation template. It creates an Amazon S3 bucket and loads all the assets into Amazon CloudFront. As a user, you use the Amazon CloudFront URL to view the web UI mentioned earlier.  Based on the operations you choose, this UI will trigger the appropriate API in Amazon Connect to deliver appropriate results.

This post will cover the following phone number administration in detail:

  1.  List all the claimed numbers associated to your instance
  2.  Claim a phone number into your instance
  3.  Associate a contact flow to a claimed phone number
  4.  Describe specific details of a phone number
  5.  Disassociate the contact flow associated with the claimed phone number
  6.  Release a claimed phone number from your instance

Note: This is a sample project designed to be easily deployed for experimentation. The Identity Access Management(IAM) policy permissions use least privilege> However the Amazon CloudFront and Amazon API Gateway resources deployed will be publicly accessible.

Please take the appropriate measures to secure your CloudFront distribution and API Gateway as required.

Prerequisites
For this walkthrough, it is assumed that you understand and have access to the following resources:

  1. An AWS account
  2. An existing Amazon Connect instance
  3. A few phone numbers claimed in your Amazon Connect instance
  4. Amazon Connect contact flows associated with the above phone numbers
  5. AWS IAM  to create policies and roles
  6. Amazon CloudFront to create a distribution
  7. Amazon S3 to create buckets
  8. AWS CloudFormation to run the stack
  9. Amazon Cognito to create users

Deploy the solution

Note: The CloudFormation template will deploy resources in the US West (Oregon) Region. To deploy in other regions, download the solution from this GitHub repository.

Overview of the steps:

The solution deployment consists of the following three major steps:-

A. Deploy the CloudFormation stack

B. Add users in Amazon Cognito user pool to access the CloudFront web UI

C. Test the solution for managing the phone numbers in your Amazon Connect instance

Let’s begin:-

A. Deploy the CloudFormation stack

  1. Log in to the AWS Management Console in the US West (Oregon) Region.
  2. Click on the Launch Stack button below to create a stack.
  3. Enter a unique Stack name (e.g. phone-number-api).
  4. Under Amazon S3 configuration (e.g. phone-number-api-blog-XXX), enter a globally unique name for a new Amazon S3 bucket that will be created. This bucket will store all the assets that are required for the web UI you access through the Amazon CloudFront URL.
  5. Enter your Amazon Connect instance ARN.
  6. Check the box for “I acknowledge that AWS CloudFormation might create IAM resources.”
  7. Choose Create Stack.
  8. The AWS CloudFormation template may take 15-30 minutes to create all the resources. Once done, it will show the status as CREATE_COMPLETE.
  9. It may take another 15-20 minutes for Amazon CloudFront to complete its deployment of the website assets after the status changes to CREATE_COMPLETE.

B. Add users in Amazon Cognito user pool to access the CloudFront UI

  1. Log into Amazon Cognito and under  User pools, select the one that starts with the {CloudFormation-stack-name}-blog-user-pool.
  2.  Choose Create user on the bottom right.
  3. Choose Send an email invitation.  You can modify this to be  Send an SMS invitation or Send both email and SMS invitation depending on your user choice
  4. Enter User name and a valid Email address  (on which you will receive an email).
  5. Choose Set a password under Temporary password and enter 8 character(s) or digit(s) or combination of both.
  6. Choose Create user on the bottom left.
  7. You will receive an email with the username and temporary password that you entered with subject Your temporary password. If you don’t see the email in your inbox, check in the junk folder.
  8. Log in to your AWS Management Console and navigate to AWS CloudFormation by typing the service name in the search bar.
  9. Select the stack you just created.
  10. Go to the Outputs section of the newly created stack.
  11. Copy the CloudFrontEndpoint URL from the Value column.
  12. Paste the URL in a new web browser tab /window to navigate to the CloudFront web UI.
  13. Enter the username and password that you received in the email and click on the Login button .
  14. You will be prompted to change the password, as this is your first time logging in.
  15. Enter the new password and click on Change password button.
  16. Your password will be changed and will prompted once again to enter your username and  the new password.
  17. Enter the details and click Login. 
  18.  After a successful login, you will automatically be presented with a list of all the phone numbers that are configured in your Amazon Connect instance. This is obtained using the ListPhoneNumbersV2 API.

C. Test the solution for managing the phone numbers in your Amazon Connect instance

Let us now test the solution based on different scenarios. On the left side of the web UI you will see options based on the different API actions available.

  1. DescribePhoneNumber:
    • Select a phone number of choice in the middle pane of the UI and click on the Describe phone number button on the left.
    • You will observe the details of the phone number(eg. Country code, phone number type etc.)  in the JSON output tab on the right.
  2. ClaimPhoneNumber:
    • Click on the Claim a phone number button on the left.
    • You will be presented with a screen with options to claim a number number from a specific country, prefix and type (DID/TFN).
    • For the Country list box, the solution is written to support US, Australia and France.  However this can be expanded to all the countries that is supported by Amazon Connect.
    • Choose  Type, Country and Prefix (optional) as per choice and click on the Search phone number(s) button.
    • This will execute the ClaimPhoneNumber API and populate the Phone Number list box.
    • Choose a number of choice and enter the description (optional).
    • Click on the Claim phone number button, and the number selected will be available in the web UI and also under Phone Numbers your Amazon Connect admin dashboard.
  3. AssociatePhoneNumberContactFlow
    • Choose the number in the list box that you just claimed and click the Associate contact flow button.
    • This will bring up a screen listing the contact flows that are available in your instance.
    • Choose a contact flow that you want to associate with the phone number and click on Associate Contact Flow button.
    • This will execute the AssociatePhoneNumberContactFlow API and provide a confirmation Successfully associated flow to the selected number.
    • You can check in your Amazon Connect admin dashboard and see the phone number has been associated with the chosen contact flow.
  4. DisassociatePhoneNumberContactFlow
    • Choose the number in the list box that you just claimed and click Disassociate contact flow button.
    • This will execute the DisassociatePhoneNumberContactFlow API and provide a confirmation Successfully disassociated flow from the selected number.
    • You can check in your Amazon Connect admin dashboard and see the phone number has been disassociated from it’s assigned contact flow.
  5. ReleasePhoneNumber
    • Choose the number in the list box that you just claimed, click Release phone number button.
    • This will execute the ReleasePhoneNumber API and provide a confirmation Successfully released the selected number from your instance.
    • You can check in your Amazon Connect admin dashboard and see the phone number has been released.

Cleaning up
To avoid incurring future charges, remove all the contents in the Amazon S3 bucket that you created, delete the bucket. You can  remove all created resources by deleting the AWS CloudFormation stack.

Conclusion
This post demonstrated examples of how one can use Amazon Connect’s new phone number APIs to programmatically manage phone numbers.

To learn more about how this solution was built and see how the APIs were performed, refer to the GitHub repository.