Using the Amazon Chime SDK to Create Automated Outbound Call Notifications

Customers looking to add telephony capabilities to their applications are often faced with the burden of operating their applications as well the telephony infrastructure required to support their use case. Building, operating, and integrating telephony infrastructure with their applications also require teams to have extensive telephony expertise in addition to software development skills. The SIP media applications (SMA) feature of the Amazon Chime SDK allows developers to easily build telephony-driven applications without the need to build, manage, and scale telephony infrastructure. For example, customers can use SIP media applications to build solutions that automate outbound calling and capturing of dual-tone multi frequency (DTMF) digits.

In this blog post, we will look at a how you could use SIP media applications to automate outbound appointment confirmations. For example, many healthcare providers’ offices have appointment scheduling processes that require administrative staff to call patients to confirm their upcoming appointments. Depending on the appointment volume this can be a time-consuming process as staff members call each patient one at a time. This blog post will demonstrate how you can build an appointment confirmation solution that automatically calls a list of provided phone numbers (such as patient phone numbers) and provides the callee with a way to confirm their appointments on the call using their telephone keypad. The solution also includes a portal that provides an interface for you to upload a list of phone numbers in a CSV file and receive immediate feedback about the state of each call as they are being processed.

Overview

This demo will build and configure several services within AWS so that you can send outbound calls to PSTN phone numbers and provide near real-time feedback on the call status and callee response

Note: Deploying this demo and receiving traffic from the demo created in this post can incur AWS charges. Be sure to deprovision unused components when complete to avoid excess charges.

To simplify deployment and testing, the solution includes the option to deploy an Asterisk Private Branch Exchange (PBX) phone system that will automatically accept calls to pre-assigned phone numbers that are defined in a generated CSV file. The PBX will also randomize its responses to simulate the varying responses callers could provide.

How It Works

Making an outbound call using a SIP media application requires several components:

An AWS Lambda that will interface with SIP media application — smaOutbound.js
An Amazon Chime SIP media application that is associated with that Lambda
A request to CreateSipMediaApplicationCall — outboundCall.py

In the included demo, all of these are created for you, but they could be created through the AWS Console as well. The outboundCall.py Lambda function is used to create the SIP media application call with the boto3 SDK client. This Lambda function is triggered with an Amazon API Gateway from the client application.

From the sample code:

response = chime.create_sip_media_application_call(
	FromPhoneNumber=fromNumber,
	ToPhoneNumber=appointmentInfo['phoneNumber'],
	SipMediaApplicationId=sipMediaApplicationId )

This code will make a request to create the outbound call. The response from this includes a Transaction ID that will be used to correlate the call from the client to the SIP media application Lambda function. This information is stored with a GraphQL mutation in the Amazon DynamoDB resource associated with this demo.

transactionId = response['SipMediaApplicationCall']['TransactionId']
params = {
	"note" : {
		"id" : x,
		'phoneNumber' : requester['phoneNumber']['S'],
		'firstName' : requester['firstName']['S'],
		'lastName' : requester['lastName']['S'],
		'message' : requester['message']['S'],
		"transactionId" : transactionId,
		"status" : "Calling User"
	}
}
result = client.execute(query, variable_values=params)

At this point, the outboundCall.py Lambda function is finished with the call and the SIP media application and smaOutbound.js Lambda will begin processing the call. The smaOutbound.js Lambda function is invoked when the call is placed and handled by the code here:

exports.handler = async(event, context, callback) => {
	const details = await query(event.CallDetails.TransactionId)
		switch (event.InvocationEventType) {
			case "NEW_OUTBOUND_CALL":
			console.log("OUTBOUND");
			break;

No action is returned to the SIP media application at this point as we are waiting for the called party to answer. When the call is answered, the InvocationEventType will match ‘CALL_ANSWERED’ and be processed here

exports.handler = async(event, context, callback) => {
	const details = await query(event.CallDetails.TransactionId)
		switch (event.InvocationEventType) {
			case "CALL_ANSWERED":
			console.log("ANSWERED");
			actions = await newCall(event, details);
			break;

async function newCall(event, details) {
	const transactionId = event.CallDetails.TransactionId;
	var updatedDatabase = await update(details, "Call Answered")
	playAudioAction.Parameters.AudioSource.Key = transactionId + '.wav';
	playAudioAndGetDigitsAction.Parameters.AudioSource.Key = 'requestResponse.wav'
	return [playAudioAction, playAudioAndGetDigitsAction];
}

This function updates the DynamoDB resource with the new status and creates a list of actions to respond back to the SIP media application with. These actions will play an audio file (playAudioAction) and then play another audio file and get digits (playAudioAndGetDigitsAction). The call will progress through the rest of the smaOutbound.js Lambda function until the call completes.

Prerequisites

Before getting started, you must have the following:

node V12+/npm installed
yarn installed
python3/pip installed
AWS Command Line Interface (AWS CLI) installed
AWS Cloud Development Kit (AWS CDK) installed
AWS CDK bootstrapped
Ability to create Amazon Chime SIP media applications and Phone Numbers (ensure your [Service Quota] in us-east-1 for Phone Numbers have not been reached)
Deployment must be done in us-east-1 or us-west-2 to align with SIP media applications resources

Deployment

Deploy Back-end Resources

Clone this repo: git clone https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications
cd amazon-chime-sma-outbound-call-notifications
Run deployment script:
- Standard deployment without Asterisk:./deploy.sh
- Optional deployment with Asterisk for automatic call answering use: ./deploy.sh -o withAsterisk
Accept the prompts for the AWS CDK deployment

Deploy the local client

cd client-app
yarn
yarn start

The AWS Cloud Development Kit (AWS CDK) deployment will deploy the following resources:
outboundCall – Python Lambda that creates wav files for SMA playback and calls the create_sip_media_application_call to make outbound calls

smaOutbound – The Lambda function that is associated with the SIP media application. This Lambda function will handle invocations from the SIP media application and return actions.
graphqlResolver – Lambda resolver for graphQL queries and mutations. This allows our client portal to interact with our application and receive real-time status on calling
outgoingWav – Amazon Simple Storage Service (Amazon S3) bucket to store wav files for playing customized messages
requesterInfo – DynamoDB table used to store numbers to call and status of those calls
AWS AppSync API – Used to process DynamoDB Table and handle queries and mutations from Lambdas
API Gateway – Used to invoke the outboundCall Lambda with the phone numbers to be called
ChimeSMA – Amazon Chime SIP media application used to make outbound calls. Associated with smaOutbound Lambda
Asterisk Server on Public VPC (Optional) – Used to answer calls and reply with DTMF. Please note – Asterisk can take ~5 minutes to create and configure during AWS CDK deployment
Amazon Chime Voice Connector (Optional) – used to associate a Phone Number with the Asterisk server

Additional Resources

utils\createWav.py – Python script to create wav files using Polly
utils\CreateCsv.js – Node script to create csv file with random names to call Asterisk server
wav_files\* – wav files uploaded to outgoingWav bucket for use with SMA

Walkthrough

After deploying the local client, your default browser will load the React client application that allows you to upload a CSV file that contains the following fields: phoneNumber,message,firstName,lastName.

NOTE: If you chose to deploy the optional Asterisk server, a CSV file will be generated in the client-app folder. This CSV file (phoneNumbers.csv) will be pre-populated with fictious names and an Amazon Chime Voice Connector phone number assigned to the Asterisk server.

Once you have selected a source CSV file, it will populate the fields on the client app and also upload the fields to a DynamoDB table using GraphQL for later processing and updating.

When you’re ready to initiate the outbound call notifications, click the Send Calls button. This will make an Axios call to an API Gateway triggering the outboundCall Lambda function. This Lambda function will make calls to the number requested and update the DynamoDB table using GraphQL. This will update the React app using a subscription to give immediate feedback about the state of the call.

Cleanup

To clean up this demo, please use the following steps:

From the repo directory, run: cdk destroy --all to remove the deployment.
Manually remove Amazon Chime configuration in the Amazon Chime Console:
Delete SIP Rules
Delete SIP media applications
Delete phone numbers
Delete Amazon Chime Voice Connectors

Conclusion

This blog post has demonstrated how Amazon Chime SIP media applications can be used to build solutions that interact with a wide variety of AWS services to create simple yet powerful, telephony-driven solutions such as this outbound call notification and confirmation application.

Next steps and resources

– Visit the GitHub Repository
– Learn about Amazon Chime SDK

Business Productivity