Add voice bots to your existing telephony services to using Amazon Chime SDK

How can I add Amazon Lex voice bots my existing telephony services?

Many customers would like to improve the customer contact experience by incorporating voice chatbots. However, customers may not want to disrupt their telephony infrastructure in order to add this capability — for example, they may wish to leverage existing infrastructure, retain telephone numbers, etc. In this blog post, we will demonstrate how customers can use the Session Initiation Protocol (SIP) to connect existing telephony infrastructure to voice bots Amazon Lex using the Amazon Chime SDK. The Amazon Chime SDK PSTN audio service integrates with Amazon Lex, and enables builders to create serverless applications that provide conversational interfaces for calls to or from the public switched telephone network (PSTN) and SIP-based voice services. Twilio provides a voice communications service that supports SIP integration; the examples that follow use Twilio but any SIP-compatible telephony service should work.

Prerequisites for adding Amazon Lex-powered voice bots to Twilio

In order to deploy the solution as described herein, you should have an AWS Account and a Twilio account (with a provisioned phone number). Experience with SIP is not required for this solution but would be necessary in a production deployment. Familiarity with Amazon Lex and AWS Lambda is beneficial but not required. You will need to provision a phone number in Amazon Chime SDK; this phone number will need to be passed as part of the SIP call to Amazon Chime SDK (more info on this below).

Call flow between Twilio, Amazon Chime SDK, and Amazon Lex

The solution will deploy an Amazon Lex Order Flowers chatbot demo (for more info on the Order Flowers demo, see the documentation), Lambda functions for the Amazon Chime SDK PSTN audio service (also known as SIP Media Applications), and an Amazon Chime SDK Voice Connector. With this fully managed infrastructure in place, we can now configure inbound calls to Twilio to trigger a SIP connection to the Lex chatbot via the Amazon Chime SDK.

The call-flow in this solution starts with a phone call to a Twilio provisioned phone number (#1 in the diagram below). Typically, developers will program a request/response application to handle inbound phone calls. For example, when the call is answered, play a greeting, then request the user to press a key for various menu actions, etc. Twilio also provides TwiML Bins, a quick option to prototype voice applications using an XML-based script. We’ll create a TwiML Bin that answers the call, plays a short greeting, and then makes a SIP connection to Amazon Chime SDK Voice Connector (#2).

Amazon Chime SDK Voice Connector is a communications service that allows customers to connect telephony systems and services to AWS using SIP. The service provides SIP endpoints that can be accessed over the Public Internet (restricted to IP ranges you specify) or AWS Direct Connect. The SIP endpoint has the format of uniqueId.voiceconnector.chime.aws for AWS Regions in the US and uniqueId.regionId.vc.chime.aws for AWS Regions outside of the US.

Amazon Chime SDK SIP rules associate a SIP Media Application (SMA) to the Amazon Chime SDK Voice Connector (#3). The SMA passes the SIP details to a Lambda function in an invocation event. From there, the code in your Lambda can parse and processed the data as desired. In this demo application, the Lambda function will instruct the SMA to play a greeting message (text-to-speech) and then initiate the Amazon Lex Order Flowers bot (#4). In a production solution, the Lex bot would be configured to use a second Lambda function to validate input and fulfill the intent (e.g., create a flowers order, etc.). All AWS services in this solution can output logs and metrics to Amazon CloudWatch for operational visibility — a CloudWatch Dashboard provides a “single pane of glass” to monitor and troubleshoot the solution.

Deployment Walkthrough

To deploy the solution, you will need to clone this GitHub repository which contains an AWS Cloud Development Kit (CDK) application. If you do not have a development environment with the AWS CDK prerequisites installed, the fastest way to deploy the solution is to use AWS CloudShell.

Login to your AWS account, choose an AWS region that supports Amazon Chime SDK (e.g., US East – N. Virginia), and in the search box type “CloudShell” and select “AWS CloudShell.” This will open a web-based terminal session. At the terminal (whether CloudShell or your own development environment) type the following to clone the repo and deploy the solution. The repo includes a .env file that you can use to set the area-code of a specific US state (two-character code). In CloudShell, you can run nano .env to edit the file; it is set to AZ (Arizona) unless you change it.

git clone https://github.com/aws-samples/chimesdk-sip-voicebot.git
cd chimesdk-sip-voicebot
cdk bookstrap
cdk install 
cdk deploy

After the CDK deployment completes, the required AWS resources will be created. These resources will include an Amazon Chime SDK phone number that will be used to “link” the inbound SIP calls (from Twilio in this solution) to your Amazon Chime SDK Voice Connector in your AWS account.

Important: SIP calls will be blocked without specifying an Amazon Chime SDK phone number as described in the Twilio configuration section below.

Review Amazon Chime SDK Resources

Let’s examine the Amazon Chime SDK resources that have been created. In the Amazon Chime SDK Console, choose SIP Trunking > Voice Connectors. Choose the Voice Connector with the name ‘twilio-sip-connector’. The General tab shows the Voice Connector ID (which is used in the URI) and Encryption status (it should be Enabled, which is our recommendation).

The Termination tab shows the Voice Connector outbound hostname URI. This is the URI that Twilio will use to initiate the SIP transfer to Amazon Chime SDK. Please note the Allowed hosts list — this restricts network access to the URI to the IP ranges. This list has been populated with Twilio’s IP ranges (current at time of publish); please check this page to determine if any “signaling IP” ranges have changed. Next, click the Logging tab – the SIP message and Media metric logs should be enabled; these logs will be reviewed in the Monitoring section below.

On the left side of the console under PSTN Audio, choose SIP media applications. In the Name column, you should see ‘twilio-sip-mediapp’ and the Endpoint column should contain a Lambda function ARN. Select the name to view additional details about the SMA. The Rules tab should contain two rules – one rule for the Amazon Chime SDK phone number that was provisioned and one for ‘Request URI hostname’, which is the SIP endpoint. Both of these Rules point to the same Lambda function, which will be reviewed in the next section. In the Logging tab, make sure SIP Media Application Logs is enabled.

SMA Handler (Lambda function)

The CDK deploys a Lambda function with the prefix ‘ChimesdkSipVoicebotStack-ChimeSDKHandler’. This function provides a bridge between Amazon Chime SDK (SIP and Phone calls) and the Amazon Lex chatbot. The function handles new call events, hang-up events. The start_bot_conversation_action starts the Lex box integration (the Bot ID and Alias are configured as Lambda Environment variables). The CDK solution deploys a sample an Amazon Lex Order Flowers chatbot. If you would like to use an existing Lex bot, update the environment variables with the Bot ID and Alias. Review the documentation to learn more about routing calls and events to the Lambda function.

Update Twilio Configuration

The CDK provides the following TwiML Bin xml file (src/twiliobin.xml). This file contains 3 placeholders – ChimePhoneNumber, TwilioPhoneNumber, and VoiceConnectorId. Copy the XML below into a text editor, and replace the placeholders with the information from your deployment. Note the x-callerid query string. The SIP standard allows passing data via query string parameters. Amazon Chime SDK will pass the query strings to the Lambda function. For example, your SIP environment may provide or collect caller data prior to initiating the SIP integration. In the TwilML sample below, the x-callerid query string is set to a generic number, but in a production system it could pass in the caller’s actual phone number to Chime SDK Lambda function.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Thank you for calling Your Flower Company. Transferring to the Order chatbot.</Say>
  <Pause length="2"/>
    <Dial callerId="+1ChimePhonenumber">
        <Sip>
           sip:+1TwilioPhoneNumber@voiceConnectorId.voiceconnector.chime.aws;secure=true?x-callerid=+1123-555-1212
        </Sip>
    </Dial>
</Response>

Login into your Twilio account, navigate to TwiML Bins console, and create a configuration by specifying a ‘Friendly Name’ and pasting in the updated XML file in the text editor. Click the Create button. Now navigate to the Phone Numbers – Manage – Active numbers console. Assign a phone number to the TwiML Bin you just created (select ‘Buy a number’ if needed).

Testing the Solution

To test the solution, dial the Twilio number you assigned to the TwilML Bin. Let’s walk through the call flow and map each response to the corresponding resource in the solution.

Step	Text Prompt or User dialog	Resource/Notes
1	—	User dials Twilio phone number
2	Thank you for calling Your Flower Company…	Twilio Bin – “Say” verb.
3	Welcome to the Order Flowers SIP Integration Demo using Amazon Chime SDK…	SMA Handler function – line 120
4	“I’d like to order flowers.”	User would like to order flowers.
5	What type of flowers would you like to order?	Amazon Lex bot (OrderFlowers Intent). The bot will then request when the flowers should be delivered (date and time).

Let’s look at the AWS CloudWatch Logs to view the SIP details. Amazon Chime SDK Voice Connector provides two logging capabilities that can be enabled. Searching the Log Groups for the prefix /aws/ChimeVoiceConnector should display the two Log Groups. These Log Groups can assist with SIP integration troubleshooting. The Amazon Chime SDK SIP Media App Log Group prefix is /aws/ChimeSipMediaApplicationSipMessages. This Log Group records SMA messages such as ‘Executing action speak’, etc. The SMA Lambda function will log call details, including SIP query strings to CloudWatch Logs. See the example below. To learn how to create a CloudWatch Dashboard displaying Amazon Chime SDK metrics, please review this blog.

{
    "SchemaVersion": "1.0",
    "Sequence": 1,
    "InvocationEventType": "NEW_INBOUND_CALL",
    "CallDetails": {
        "TransactionId": "e0bce31c-6733-4048-9057-66d8ce162ade",
        "AwsAccountId": "6....",
        "AwsRegion": "us-east-1",
        "SipRuleId": "d0620c4f-f001-4615-b14a-...",
        "SipMediaApplicationId": "9a82d39f-790a-4a54-bb4c-...",
        "Participants": [
            {
                "CallId": "b4221461-026f-4798-a5cd-...",
                "ParticipantTag": "LEG-A",
                "To": "+1aaabbbcccc", //Twilio phone number
                "From": "+1aaabbbcccc",
                "Direction": "Inbound",
                "StartTimeInMilliseconds": "1699297959483",
                "SipHeaders": {
                    "x-callerid": "1zzzqqqwwww", //query string with caller's number
                    "X-Twilio-AccountSid": "ACdf506166a9a0b9823c8aa6f2d43...",
                    "X-Twilio-CallSid": "CA3bb8db702424fc040f024b1d63afa..."
                }
            }
        ]
    }
}

Clean up

This concludes the solution walkthrough. Please delete the solution by returning to CloudShell (or your dev environment) and running the command cdk destroy and selecting the named stack; this will delete all AWS resources in this solution. You may also wish to delete the Twilio phone number if you allocated one for this solution.

Conclusion

In this blog post we reviewed how to quickly provision AWS resources to build a SIP interface to connect existing telephony systems and services to Amazon Lex. The example solution uses Twilio but any SIP compatible telephony environment can be used integrate with Amazon Lex voice bots. There are several benefits to using the Amazon Chime SDK SIP endpoint. First, all AWS services used in this solution are “serverless” — that means AWS is responsible for the infrastructure. This allows you to focus on the chat bot experience for your customers. Additionally, you can pass call data and context to the Lambda function using SIP headers. To learn more about the PSTN Audio conversational voice experience and call bridging, refer to the Amazon Chime SDK PSTN Audio Developer Guide.

Related Resources:

Amazon Chime SDK SIP Trunking Configuration Guides

How to build a smart interactive voice response (IVR) call routing system

Business Productivity