How can I set my Amazon Connect outbound caller ID dynamically based on country?

Last updated: 2022-01-10

I want my Amazon Connect outbound caller ID to change dynamically based on a call recipient's country. How can I set that up?

Short description

To have your Amazon Connect outbound caller ID change dynamically based on a call recipient's country, do the following:

  • Create a caller ID list in JSON format.
  • Upload the caller ID list to an Amazon Simple Storage Service (Amazon S3) bucket.
  • Create an AWS Lambda function that identifies the outbound contact's country code and selects a corresponding phone number from the caller ID list.
  • Add the Lambda function to your Amazon Connect instance.
  • Create an outbound whisper flow to invoke the Lambda function.
  • Configure the default outbound queue in your agents' routing profile to use the outbound whisper flow.

Note: You can customize this solution for your use case. For example, you can store your caller ID list in an Amazon DynamoDB table instead of an S3 bucket. Then, reconfigure the Lambda function and its execution role accordingly.

Resolution

Create a caller ID list in JSON format

Create a JSON file that contains a country-based list of phone numbers that you want to use for your outbound caller ID.

As you create your caller ID list, keep in mind the following:

  • Your outbound caller ID phone number doesn't have to be from the country that you're calling from.
  • For this example setup, the country codes on your list must follow the ISO 3166-1 alpha-2 standard, and the phone numbers must follow the E.164 standard. For more information, see ISO 3166 — COUNTRY CODES on the ISO website and E.164 : The international public telecommunication numbering plan on the ITU website.
  • If the Lambda function fails to invoke during call routing, then Amazon Connect uses the queue's default outbound phone number for the caller ID instead. The default outbound phone number is the number configured in the queue settings in your Amazon Connect instance. For more information, see Set up outbound caller ID.

Example JSON caller ID lists

In this first example caller ID list, Amazon Connect uses the following outbound caller IDs:

  • +12345678901 when calling a customer with a United States ("US") phone number.
  • +441234567890 when calling a customer with a United Kingdom ("GB") phone number.
  • +19876543210 when calling a customer with a phone number in a country that's not listed in the caller ID list ("Default").
{
    "US": "+12345678901",
    "GB": "+441234567890",
    "Default": "+19876543210"
}

In this second example caller ID list, Amazon connect uses the following outbound caller IDs:

  • +441234567890 when calling a customer with a phone number in the United Kingdom ("GB"), France ("FR"), Germany ("DE"), or Ireland ("IE").
  • +19876543210 when calling a customer with a phone number in a country that's not listed in the caller ID list ("Default").
{
    "GB": "+441234567890",
    "FR": "+441234567890",
    "DE": "+441234567890",
    "IE": "+441234567890",
    "Default": "+19876543210"
}

Upload the caller ID list to an Amazon S3 bucket

Follow the instructions in Uploading objects in the Amazon S3 User Guide.

Create an AWS Lambda function that identifies the outbound contact's country code and selects a corresponding phone number from the caller ID list

Create a Lambda execution role

Follow the instructions in Creating an execution role in the IAM console.

As you configure the execution role, keep in mind the following:

Note: You can limit the execution role's access to a particular S3 bucket by creating your own IAM policy. For an example policy, see Amazon S3: Allows read and write access to objects in an S3 bucket.

Create a Lambda function

Create a Lambda function using the execution role that you created in the previous step.

In your function code, include logic that checks an incoming JSON request from Amazon Connect. For more information, see How to reference contact attributes. Also, the example JSON request to a Lambda function in the Amazon Connect Administrator Guide.

Note: As an example, you can use the Python function from DynamicOutboundCallerID on the aws-support-tools GitHub repository. The function code works with the Python 3.6 (or later) runtime. If you use the example function code, then you must configure the following environment variables in your function:

  • BUCKET_NAME: The name of the S3 bucket where the JSON object is stored.
  • COUNTRY_ROUTING_LIST_KEY: The key from the JSON file stored in the S3 bucket.

For example, if the JSON object is stored in s3://hello/world/list.json, then the environment variables would be the following:

  • BUCKET_NAME: "hello"
  • COUNTRY_ROUTING_LIST_KEY: "world/list.json"

Create a Lambda deployment package for the Lambda runtime that you're using

Follow the instructions in Lambda deployment packages.

Note: The example Python function from DynamicOutboundCallerID uses the phonenumbers Python library. For more information, see phonenumbers on the Python Package Index (PyPI) website.

To include a third-party library in your function, you must create a deployment package. You can create the deployment package by running the following commands in the folder that contains lambda_function.py:

$ pip install phonenumbers --target ./
$ zip -r9 function.zip ./

These commands are valid for Linux, Unix, and macOS operating systems only.

For more information on deploying Python Lambda functions, see Deploy Python Lambda functions with .zip file archives.

Add the Lambda function to your Amazon Connect instance

Create an outbound whisper flow to invoke the Lambda function

Create an outbound whisper flow

If you haven't already, create an outbound whisper contact flow.

Important: To create and edit a contact flow, you must log in to your Amazon Connect instance as a user that has sufficient permissions in their security profile.

1.    Log in to your Amazon Connect instance at https://instance_name.my.connect.aws/.
Note: Replace instance_name with your instance's alias.

2.    In the left navigation pane, hover over Routing, and then choose Contact flows.

3.    On the Contact flows page, choose the arrow icon next to Create contact flow, and then choose Create outbound whisper flow.

4.    In the contact flow designer, for Enter a name, enter a name for the contact flow.

5.    Choose Save.

For more information, see Create a new contact flow.

Add an Invoke AWS Lambda function block

1.    In the contact flow designer, choose Integrate.

2.    Drag and drop an Invoke AWS Lambda function block onto the canvas.

3.    Choose the block title (Invoke AWS Lambda function). The block's settings menu opens.

4.    Under Function ARN, choose Select a function, and then choose the Lambda function that you added to your instance.

5.    (Optional) For Timeout (max 8 seconds), enter a number of seconds that Amazon Connect waits to get a response from Lambda before timing out.

6.    Choose Save.

Note: When Amazon Connect invokes your Lambda function, the function returns a JSON response similar to the following:

{
    "customer_number": "<Customer's phone number that you're calling>",
    "customer_country": "<Country of the customer's phone number>",
    "outbound_number": "<Outbound phone number that Lambda loads from Amazon S3 and sends to Amazon Connect>",
    "outbound_country": "<Country of the outbound phone number that Lambda sends to Amazon Connect>",
    "default_queue_outbound_number": "<Default outbound phone number set up for the queue>",
    "default_queue_outbound_country": "<Country of the default outbound phone number>"
}

For more information, see Invoke a Lambda function from a contact flow and Contact Block: Invoke AWS Lambda function.

Add a Call phone number block

Configure this block to use the outbound_number from Lambda as the caller ID phone number.

1.    In the contact flow designer, choose Interact.

2.    Drag and drop a Call phone number block onto the canvas.

3.    Choose the block title (Call phone number). The block's settings menu opens.

4.    Do the following:
Select the Caller ID number to display (optional) check box.
Choose Use attribute.
For Type, choose External.
For Attribute, enter outbound_number.

5.    Choose Save.

For more information, see Contact Block: Call phone number.

Finish the contact flow

1.    Add and connect more contact blocks as needed for your use case. For example use cases, see Sample contact flows.

2.    Connect all the connectors in your contact flow to a block. Be sure to connect the Success node of the Invoke AWS Lambda function block to the Call phone number block. Be sure to also connect the Success node of the Call phone number block to an End flow / Resume block. You must use at least these blocks. For example: Entry point > Invoke AWS Lambda function > Call phone number > End flow / Resume.

3.    To save a draft of the flow, choose Save.

4.    To activate the flow, choose Publish.

Configure the default outbound queue in your agents' routing profile to use the outbound whisper flow

In your agents' routing profile, identify the default outbound queue.

Edit the queue by doing the following:

1.    In your Amazon Connect instance, in the left navigation pane, hover over Routing, and then choose Queues.

2.    On the Queues page, choose the name of the queue that you identified as the default outbound queue.

3.    On the Edit queue page, for Outbound whisper flow (optional), search for and choose the name of the outbound whisper flow that you created.

4.    Choose Save.

For more information, see Create a routing profile and RoutingProfile object.