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

Last updated: 2020-03-25

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

Do the following:

  • Create a caller ID list in JSON format, and then upload it 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 caller ID phone number from the JSON list in your S3 bucket.
  • Add the AWS Lambda function to your Amazon Connect contact center instance.
  • Configure your Amazon Connect contact flow to invoke the AWS Lambda function.

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


Create the caller ID list

Create a JSON file that contains a country-based list of phone numbers that you want to use for outbound caller ID. The contents of the file should be formatted like this example:

Note: For this example, 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.

    "US": "+12345678901",
    "GB": "+441234567890",
    "Default": "+19876543210"

In this example, when calling a customer who has a United States phone number, Amazon Connect uses +12345678901 for the outbound caller ID. When calling a customer who has a United Kingdom phone number, Amazon Connect uses +441234567890 instead. When calling a customer in a country that's not listed in the JSON file, Amazon Connect uses +19876543210.

Your outbound caller ID phone number doesn't have to be from the country that you're calling. For example, if you're a business based in the United States and you want to use a United Kingdom-based caller ID phone number when you call countries in western Europe, you can do the following:

    "GB": "+441234567890",
    "FR": "+441234567890",
    "DE": "+441234567890",
    "IE": "+441234567890",
    "Default": "+19876543210"

In this example, when calling customers who have phone numbers from the United Kingdom, France, Germany, or Ireland, Amazon Connect uses +441234567890 for your outbound caller ID. For the rest of the world, Amazon Connect uses +19876543210 instead.

Note: During call routing, if the Lambda function fails to invoke for any reason, Amazon Connect uses the queue's default outbound phone number for the caller ID instead. This is the number configured in the queue settings in your Amazon Connect instance. For more information, see Set Up Outbound Caller ID.

Upload the caller ID list to an S3 bucket

After you create the caller ID list JSON file, upload the file to an S3 bucket.

Create a Lambda execution role

Your Lambda function's execution role must have Amazon S3 read access to read the JSON object that you uploaded to an S3 bucket. You can create an execution role in the AWS Identity and Access Management (IAM) console, and then attach the AWS managed policy AmazonS3ReadOnlyAccess to the role.

Tip: 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 and the following example JSON request to a Lambda function:

    "Details": {
        "ContactData": {
            "Attributes": {},
            "Channel": "VOICE",
            "ContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX",
            "CustomerEndpoint": {
                "Address": "+1234567890",
                "Type": "TELEPHONE_NUMBER"
            "InitialContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXXX",
            "InitiationMethod": "INBOUND | OUTBOUND | TRANSFER | CALLBACK",
            "InstanceARN": "arn:aws:connect:aws-region:1234567890:instance/c8c0e68d-2200-4265-82c0-XXXXXXXXXX",
            "PreviousContactId": "4a573372-1f28-4e26-b97b-XXXXXXXXXX",
            "Queue": "QueueName",
            "SystemEndpoint": {
                "Address": "+1234567890",
                "Type": "TELEPHONE_NUMBER"
        "Parameters": {
            "sentAttributeKey": "sentAttributeValue"
    "Name": "ContactFlowEvent"

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 and is provided as is.

If you use the example function code, 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 BUCKET_NAME is "hello" and COUNTRY_ROUTING_LIST_KEY is "world/list.json".

Create a deployment package

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

Note: These commands are valid only for Linux/Unix/macOS systems.

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

For more information, see AWS Lambda Deployment Package in Python.

Add the Lambda function to your instance

In the Amazon Connect console, add your Lambda function to your contact center instance.

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 using your access URL (
    Note: Replace alias with your instance's alias.
  2. In the left navigation pane, pause on Routing, and then choose Contact flows.
  3. On the Contact flows page, next to the Create contact flow button, choose the down arrow, 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, expand 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.

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 the Lambda Function 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, expand 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 Initiate an Outbound Call and 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 also to connect the Success node of the Call phone number block to an End flow / Resume block. You must use at least these blocks:
    Entry point > Invoke AWS Lambda function > Call phone number > End flow / Resume.
  3. Save and publish the contact flow.

For more information, see Create a New Contact Flow.

Configure a queue with the outbound whisper flow

In the routing profile to which your agents are assigned, identify the default outbound queue. For more information, see Create a Routing Profile and RoutingProfile Object.

Edit the queue by doing the following:

  1. In your Amazon Connect instance, in the left navigation pane, pause on 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.