AWS Contact Center

Using WhatsApp and Amazon Lex to escalate to voice via Amazon Connect

Today, enterprises are revamping their existing channels, such as contact centers based on interactive voice response (IVR), to provide an enhanced, seamless experience to customers. They are motivated to create an omni-channel experience, using services like Amazon Connect and Amazon Lex to enrich customer experience at a low cost.

They are also using channels like WhatsApp, a popular communication choice. With the introduction of the WhatsApp API for business, enterprises engage with customers through WhatsApp for text communication to increase reachability.

This post outlines steps for enhancing the customer experience by linking WhatsApp with Amazon Lex for text. It then links with an Amazon Connect contact center for seamless voice transfer using the Amazon Connect API and the Twilio WhatsApp API.

Amazon Connect is a self-service, cloud-based contact center service that makes it easy for any business to deliver better customer service at a lower cost. Amazon Connect is based on the same contact center technology used by Amazon customer service associates around the world to power millions of customer conversations.

Amazon Lex is a service for building conversational interfaces into any application using voice and text. You can add a voice or text chat interface to create bots on any application that helps customers with many basic tasks.

The following components are used for this integration:

  • An Amazon Connect contact center
  • An Amazon Lex chatbot
  • The Twilio Sandbox for WhatsApp
  • An AWS Lambda function

Please Note: Twilio and WhatsApp are third-party services subject to additional terms and charges. Amazon Web Services isn’t responsible for any third-party service that you use to send messages.

Integrating WhatsApp with Amazon Lex and Amazon Connect

The following diagram depicts a high-level integration architecture between the WhatsApp API provided by Twilio, Amazon Lex, AWS Lambda, and Amazon Connect.

Initially, the customer initiates chat conversation with WhatsApp. The initial support is provided by an Amazon Lex chatbot integrated with WhatsApp using the Twilio WhatsApp API. When a user initiates a request to speak to a customer service agent, Amazon Lex invokes an outbound API call request to Amazon Connect using AWS Lambda. Finally, Amazon Connect initiates a contact flow to place an outbound call to a customer.

How it works

The following are the high-level steps involved in this integration:

  1. Set up the contact flow on Amazon Connect.
  2. Set up Amazon Lex for chatbot integration with WhatsApp.
  3. Create the Lambda function to initiate the outbound API call to Amazon Connect.
  4. Modify the Amazon Lex fulfillment behavior.
  5. Set up the Twilio API integration on Amazon Lex.

When a user initiates a chat in WhatsApp, the integrated Amazon Lex bot responds to the user’s queries. When the user must talk to a contact center agent:

  • The corresponding utterance is captured.
  • The intent is triggered.
  • The user is prompted to provide a telephone number at which the conversation continues, along with additional slot values, if required.
  • To fulfill the intent, the mapped Lambda function is invoked.
  • The Lambda function calls the Amazon Connect outbound API.
  • The outbound API calls the user’s telephone number and connects the call to the contact flow ID provided in the API.
  • When an agent receives the call, the agent has the necessary details about the conversation from the attributes, allowing the user to connect to the right agent.

Set up the contact flow on Amazon Connect

Follow these steps to set up the contact flow, as shown in the following diagram. This example uses a simple flow, which places the call in a queue.

  1. Create an Amazon Connect instance.
  2. Log in to your Amazon Connect instance, and
  3. choose Routing, Contact flows.
  4. Choose Create contact flow
  5. , which enables you to create an interactive flow when the call lands in Amazon Connect.
  6. To specify how the call flow should be handled after it’s placed in the queue, drag and drop the Set customer queue flow block.
  7. To set the queue, drag and drop the Set working queue block.
  8. To transfer the call to the queue, set the Transfer to queue block.
  9. To end the flow, use the Disconnect/hang up block.

After the desired flow is complete, save the flow and publish it.

Because this example uses the Outbound API call to trigger the flow, it does not need to be assigned to any phone number.

Make a note of the contact flow ID and the Amazon Connect instance ID, because these IDs are used while invoking the Amazon Connect API.

Set up Amazon Lex

An intent is a particular goal that the user wants to achieve. In this case, the intent of the user is to connect with a human agent. Add additional intents and sample utterances or phrases that the user can speak or type to invoke the intent, as per the functionality of the bot.

Slots are the fields containing information that is necessary for an intent to be fulfilled. Slot types can be newly created, or chosen from existing slot types. The prompts are used to get slot values from the user.

  1. In the Amazon Lex console, choose Custom bot and configure the following fields. For more information, see Getting Started with the Amazon Lex Console.
    • For Bot name, enter WhatsappBot.
    • For Output voice, choose Kendra. You can test the voice with sample text.
    • For Session timeout, enter 2 min.
    • For IAM role, enter AWSServiceRoleForLexBots.
  2. Choose Create intent, name the intent AgentTransfer, and choose Add.
  3. Enter some sample utterances, like the following:
    • connect with human agent
    • transfer me to agent
    • connect to agent
    • connect me to a representative
    • Transfer to agent
    • Connect me to an agent
  4. Enter the following slot names, types, and prompts:
Name Slot type Prompt
name Name Please enter your name
Number AMAZON.Phone Please enter your phone number

5. For Fulfillment, leave the default as Return parameters to client.

      6. Response: Enter a response message, to be sent to the user, as shown in the following screenshot.

      7. Build and test the chatbot: Save the intent and build the bot to test it, then test the bot by choosing Test bot, as shown in the following screenshot.

Create the Lambda function

Fulfilling the intents in Amazon Lex requires a Lambda function.

  1. In the Lambda console, choose Create Function, Author from scratch.
  2. Enter a name for the function, such as AgentTransferFunction.
  3. Choose Create a new role with basic Lambda permission.
  4. For Runtime, choose Python 2.7.
  5. Choose Create Function.
  6. To ensure that the function has access to Amazon Connect, go to the IAM console and choose Roles.
  7. Search for your Lambda function name, and choose Attach Policies.
  8. Search for AmazonConnectFullAccess, and attach the policy.
  9. Refresh the Lambda console. You should see all the additional permissions.

10. Modify the Lambda function to use theAmazon Connect outbound API action StartOutboundVoiceContact. Replace the attached example code in your Lambda function and choose Save.

For more information how to set up and test a bot, as well as additional samples, see Getting Started with Amazon Lex.

import math
import dateutil.parser
import datetime
import time
import os
import logging
import boto3

client = boto3.client('connect')

logger = logging.getLogger()

contactflowid='REPLACE YOUR Contact Flow ID'
connectinstanceid='REPLACE YOUR Connect Instance ID'
sourcephonenumber='REPLACE YOUR CALLER ID phone number for outbound call'

""" --- Helpers to build responses which match the structure of the necessary dialog actions --- """

def get_slots(intent_request):
    return intent_request['currentIntent']['slots']

def close(session_attributes, fulfillment_state, message):
    response = {
        'sessionAttributes': session_attributes,
        'dialogAction': {
            'type': 'Close',
            'fulfillmentState': fulfillment_state,
            'message': message

    return response

def delegate(session_attributes, slots):
    return {
        'sessionAttributes': session_attributes,
        'dialogAction': {
            'type': 'Delegate',
            'slots': slots

""" --- Helper Functions --- """
def connect_outbound_api(customerName,customerphone):
    response = client.start_outbound_voice_contact(
            'Customer Name': customerName

""" --- Functions that control the bot's behavior --- """
def transfer_call_to_agent(intent_request):
    Performs dialog management and fulfillment for transerf call.
    customerName = get_slots(intent_request)["name"]
    customerphone = get_slots(intent_request)["number"]
    response = connect_outbound_api(customerName,customerphone)
    return close(intent_request['sessionAttributes'],
                 {'contentType': 'PlainText',
                  'content': 'Okay, our representative will call you shortly. Thanks.'})

""" --- Intents --- """
def dispatch(intent_request):
    Called when the user specifies an intent for this bot.
    logger.debug('dispatch userId={}, intentName={}'.format(intent_request['userId'], intent_request['currentIntent']['name']))
    intent_name = intent_request['currentIntent']['name']

    # Dispatch to your bot's intent handlers
    if intent_name == 'AgentTransfer':
        return transfer_call_to_agent(intent_request)    

    raise Exception('Intent with name ' + intent_name + ' not supported')

""" --- Main handler --- """
def lambda_handler(event, context):
    Route the incoming request based on intent.
    The JSON body of the request is provided in the event slot.
    # By default, treat the user request as coming from the America/New_York time zone.
    os.environ['TZ'] = 'America/New_York'
    return dispatch(event)


Replace the values for contactflowid, connectinstanceid, and sourcephonenumber based on your values in the following code. The destination phone number is the user’s telephone number, which Amazon Connect calls.

Modify Amazon Lex fulfillment

Now that you have created the Lambda function for fulfillment, modify the bot fulfillment behavior to Lambda on the Amazon Lex console.

  1. Open the Amazon Lex console.
  2. Select the AgentTransfer intent.
  3. Under Fulfillment, choose AWS Lambda function, and configure the following fields:
    • For Lambda function, enter AgentTransferFunction.
    • For Version or alias, choose Latest.
  4. Choose Save.

With the Lambda function mapped, build and publish the bot by assigning an alias. On the Publish TransferToAgent page, for Create an alias, enter a value ‘Prod’ and choose Publish.

Create a Twilio account

Next, create a Twilio account.

  1. Sign up for a Twilio account and record the following account information:



2. After you have signed up, your account SID and authentication token can be found in the dashboard, as shown in the following screenshot.

Integrating Amazon Lex with Twilio

To integrate with Twilio, follow these steps.

  1. In the Amazon Lex console, choose Channels.
  2. Under Chatbots, choose Twilio SMS.
  3. On the Twilio SMS page, provide a name, such as BotTwilioAssociation, and description, and then configure the following fields:
    • For KMS key, choose AWS/Lex.
    • For Alias, choose the bot alias.
    • For Authentication Token, enter the AUTH TOKEN for your Twilio account.
    • For Account SID, enter the ACCOUNT SID value for your Twilio account.
  4. Choose Activate. The console creates the bot channel association and returns a callback URL. Record this URL.
  5. In the Twilio console, in the left navigation pane, choose WhatsApp.
  6. Under Sandbox Configuration, for When a message comes in, paste the URL generated from the Amazon Lex channel configuration page. You are provided with a Twilio number and sandbox name to join from WhatsApp.

You are now set to use the Amazon Lex chatbot in WhatsApp.

Follow the steps in Twilio to join the sandbox environment. Remember that this is a sandbox. After you register your number with WhatsApp for business, the same process can be followed to integrate the Amazon Lex chatbot.

For more details about the Twilio WhatsApp API and how to include a WhatsApp number in Twilio, see the Twilio site.


This post walked you through the process of setting up an Amazon Lex chatbot, integrating it with the Twilio Sandbox for WhatsApp API and integrating the chatbot with Amazon Connect using the outbound API.

Feel free to leave suggestions or approaches to integration in the comments.

About the Authors

Thilak Udhagairajagopal is a contact center consultant with Tata Consultancy Services. He has years of experience in setting up contact centers and IVR development activities. Amazon Connect has been his favorite service for the past few years. He likes to learn new technology, enjoy traveling and exploring new cuisines when he is free.



Karthik Thirugnanasambandam is a Partner Solutions Architect at Amazon Web Services. He works with large Global System Integrators on AWS cloud adoption. He is a DevOps and Serverless enthusiast. When not working, he enjoys reading and spending time with his family.