Amazon Connect – Creating a DynamoDB Data Dip
In this blog post we will look at creating a data dip within your Amazon Connect contact call flow. This will involve fetching data from a DynamoDB table and customising responses or routing the call based on the output.
The aim is to welcome the customer by name. We will achieve this by checking their phone number against a user database, to match their name and contact details.
If you have not already got an Amazon Connect instance, check out this blog post to quickly get one up and running.
Preparing the Contact Call Flow for a Data Dip
First of all, create a new contact call flow, or open an existing one if you have one.
Here is my basic call flow:
In order to execute custom code, we need to trigger Lambda functions. To add a Lambda function, click on the Integrate tab, and drag the ‘Invoke AWS Lambda function’ block to your call flow.
Then drag a ‘play prompt’ from the Interact tab, which will hold the custom user welcome message.
You should always add error handling within your contact flow to ensure your customer has the best experience.
The screenshot below shows how to add a ‘play prompt’ and make AWS Polly read out a message to the customer telling them there was an error. In your call flow you should handle this more gracefully, perhaps by routing directly to an agent or even loop back around to execute Lambda again.
Remember to save as you go along! Tip: you cannot save until you give the flow a name in the top left corner.
Finally link up all the blocks inside your contact flow as shown here:
Creating a DynamoDB Table
This blog shows you how to use DynamoDB for data storage.
Using the AWS console, create a new DynamoDB table, per the image below. I called my table ‘blog-data-dip-table’.
For this demo I will be using the customer’s phone number as reference, hence the primary key is going to be name’s ‘phone-number’.
The nature of DynamoDB means you do not have to specify the schema on creation, only the primary key field(s). When you write to the table with a new column, it will be added to the table for future reads.
This leaves the demo open for customisation for your business needs in the future.
Creating the Data Dip Lambda
Next you need to create a new Lambda function from the AWS console.
This example uses Python 2.7.
You will need to create a new Role. It will need to have basic Lambda execution rights as well as DynamoDB access.
The JSON Connect will send to the Lambda function on execution from the ‘Invoke Lambda Function’ block in the contact call flow can be seen below:
For this blog demo, we will be using the customer’s phone number, accessed by ‘Details.ContactData.CustomerEndpoint.Address’.
Lambda Function Logic:
The functionality of the code will extract the customer phone number from the event JSON, and check if there is a match in the DynamoDB table for the event’s customer phone number.
If there is no match in the Database, it means this is the first time the user has called and / or they have not created an account yet. (More on this below)
If there is a match, DynamoDb will return the data attached to it. Meaning the first name of the customer can be retrieved from the DynamoDB lookup.
This function will then either return a generic: ‘Welcome!’ or a customised ‘Welcome, first-name-here!’ back to the Contact call flow for use in our custom play prompt.
Tip: Remember to change the ‘tableName’ in the code snippet below to your table name!
Tip: Remember to create this Lambda function in the same region as the DynamoDB table or modify the boto3 declaration in the code.
This is the full Lambda function code:
Linking the Lambda to the Contact Flow
In order to execute the newly created Lambda function, we need to add the ARN of the Lambda function to the Invoke Lambda block in the Contact call flow.
The Lambda ARN can be found on the top right of the Lambda console editor:
Copy the ARN over to the Invoke Lambda Block in the contact call flow editor.
Click on the Invoke Lambda block and paste the ARN into the ‘Function ARN’ field below:
To ensure the Lambda function can be triggered and executed by the Connect call flow, we need to give this Lambda function permission to be executed by Connect.
There are many ways of doing this, we recommend using the AWS CLI:
aws lambda add-permission \
–function-name function:<LAMBDA_NAME> \
–statement-id 1 \
–principal connect.amazonaws.com \
–action lambda:InvokeFunction \
–source-account <ACCOUNT_ID> \
–source-arn <CONNECT_INSTANCE_ARN> \
To find your AWS Connect Instance ARN, go to the AWS Console for Connect and it can be seen in the screenshot below:
Acting on Lambda Output
To read the custom welcome message returned from Lambda, you need to access it as shown below:
Open up the ‘play prompt’ block after Lambda in your call flow.
Edit the response to ‘Text to speech’, ‘Enter dynamically’, ‘External’ and the variable returned from Lambda, in this case ‘welcomeMessage’.
Testing Our New Data Dip Call Flow
Phone the number you have assigned to your contact call flow.
You should be greeted with the generic welcome message because there is no test data in the database to match your phone number. This is expected working behaviour! Proceed to the next step to fix this!
Add Test Data
As this quick demo does not include adding data to the DynamoDB table, you must first add some data manually.
But for future improvements, you could use an AWS Lex bot in the Contact call flow to ask the user for their name and save it in the DynamoDB table.
In the AWS console, click the ‘create item’ button on your DynamoDB table. Add your phone number and a ‘first-name’ field to use later.
Tip: If you change this field name, or want to use a different field, remember to change the code snippet to read your table field!
Tip: Connect uses the country code! Append +44 to your number for UK.
Testing the Data Dip (Again)
Phone the number that you have assigned to your contact call flow.
This time you should be welcomed by name, assuming you typed your phone number in correctly in the previous step.
Congratulations! You now have your first Data Dip in your AWS Connect Contact Call Flow.
Tip: If it did not work, you likely got your phone number country code wrong! You can find your Connect interpreted phone number by checking the Cloud Watch Logs for the Lambda function logs. The code snippet prints the phone number (and other data!).
Future Improvements and Business Cases
Although this use case is very simple, it’s designed to get you quickly up and running!
You can use this as a basis to extend to more advanced functionality.
For example, finding the user’s current status of support ticket and reading it out: ‘Hi John, I can see you are having a problem with x, would you like to talk directly with that department?’
The customisations are endless and can be defined to suit your individual business needs!