Provide WhatsApp messaging as a channel with Amazon Connect

EDITOR NOTE: This blog is an example starter project designed to provide a demonstration and basis for builders to create their own solutions. It should not be considered Production-ready. If you plan to deploy and use this in a Production environment please review Using this in Production for additional guidance. If you need additional support to take this solution further, contact AWS Professional Services or one of our Amazon Connect Partners.

Join us for AWS Contact Center Day, a free virtual event where you’ll learn about the future of customer service, how machine learning can optimize customer and agent experiences—and more. Register now »

Organizations are striving to provide more personalized experiences to meet customer expectations. Today, consumers can pick from a range of rich digital messaging applications to communicate with friends and family and WhatsApp is one of the most commonly used globally. Increasingly, consumers expect options to communicate via digital channels of their choice for convenience and flexibility. It’s important for organizations, of any size, to consider this in their digital communication strategy to meet their customers’ evolving communication preferences.

Now, using Amazon Connect’s message streaming APIs, you can easily integrate digital channels into your Amazon Connect contact center. Integrating additional channels enables you to provide personalized, real-time, support to your customers on the digital channels they prefer. 

This blog post will walk you through how to integrate WhatsApp with your Amazon Connect contact center. The steps and architecture outlined can also be applied to integrating with other digital channels. Once you set up WhatsApp following the steps in this post, your agents can start receiving and replying to customer messages on that channel from the same agent desktop they already use for Amazon Connect voice, chat, and tasks.

Solution overview and architecture

In this blog post, you will deploy an example project from our Github repository. This project includes end to end infrastructure to support the WhatsApp messenger channel. 
To learn how to use these APIs to integrate Amazon Connect Chat with SMS, check out our blog on Building personalized customer experiences over SMS through Amazon Connect.

Figure 1 : Solution architecture

1. Customer sends a message from the digital messaging channel to the webhook hosted on Amazon API Gateway
2. API Gateway sends the message to AWS Lambda
3. Lambda writes the chat contact context to Amazon DynamoDB
4. If this is the first message for the contact, Lambda calls the APIs in the following order: StartChatContact, StartContactStreaming, and CreateParticipantConnection. If there is an existing chat, Lambda will send the message to Amazon Connect
5. Amazon Connect streams Agent/System messages to Amazon SNS
6. Amazon SNS invokes AWS Lambda
7. AWS Lambda queries Amazon DynamoDB for chat contact context.
8. AWS Lambda delivers the reply message to the customer through APIs from the source channel.

Prerequisites 

For this walkthrough, it is assumed that you understand and have access to the following resources:

• An AWS account with administrator access to following services – Amazon Connect, Amazon API Gateway, AWS Lambda, Amazon DynamoDB, Amazon Simple Notification Service, AWS Secrets Manager, AWS CloudFormation.
• An Amazon Connect Instance
• An Amazon Connect Contact Flow setup for Amazon Connect (include Disconnect flow)
• AWS CLI setup in your local environment
• A Meta (Facebook) developer account, for more details please go to the Meta for Developers console.
• Node.js installation on the developer machine with NPM. For more details go to nodejs downloads

Deployment walkthrough

Meta for Developers console

1. Navigate to the Meta for Developers console.
2. Click My Apps
3. Click Create App (or use an existing App)
4. Select an app type for your business, for this walk through please choose Business which supports WhatsApp. Click Next

5. Provide a display name, contact email and choose whether or not to attach Business Account, then click Create App.

6. Navigate to the Dashboard and select Set Up in the WhatsApp service in the Add product to your app section

7. Create or select an existing Meta Business Account and select Continue.
8. Navigate to Settings, Basic, next to App Secret click Show. Store the revealed value as it will be needed when creating secrets in Amazon Secrets Manager with key WA_APP_SECRET.
9. Navigate to WhatsApp/Getting Started and take a note of the Phone number ID, which will be needed as a secret (WA_PHONE_NUMBER_ID) in AWS Secrets Manager later on. 
10. Also take a note of the Test Number, which you will need to send messages to from your test phone once the solution is deployed. This is the business phone number for your Amazon Connect deployment.
11. Also, on the WhatsApp/Getting Started. page, add your “customer” phone number you are going to use for testing in the Select a recipient phone number dropdown. Follow the instructions to add and verify your phone number.
    Note: You must have WhatsApp registered with the number and the WhatsApp client installed on your client device. Verification message could appear in the Archived list in your WhatsApp client and not in the main list of messages.

Create a new user to access WhatsApp via API

1. Open Meta’s Business Manager and select business you created or associated your app with earlier.
2. Below Users, click System Users.
3. Click Add to create a new system user.
4. Give a name to the system user and set their role as Admin and click Create System User.
5. Use the Add Assets button to associated the new user with your WhatsApp app. From the Select asset type list, select Apps, then in the Select assets, select your WhatsApp app’s name. Enable the Test app Partial access for the user, click Save Changes and click Done.
6. Click on the Generate new token button, select the WhatsApp app created earlier.
7. Select whatsapp_business_messaging and whatsapp_business_management from the list of Available Permissions and click Generate token at the bottom.
8. Copy and save your access token. This will be used as a secret WA_ACCESS_TOKEN in the next section. Make sure you copied the token before clicking on OK.

For more details on creating the access token, you can navigate to WhatsApp/Configuration and click on Learn how to create a permanent token.

Setup AWS Secrets Manager

1. Navigate to Secret Manager console, Store a new secret, Other type of secret. If you are using the Facebook Messenger integration as well, the secret can be shared between both solutions, but keys within the secret must be created for each solution individually.
2. Under Secret key/value add WA_PHONE_NUMBER_ID, WA_ACCESS_TOKEN, WA_APP_SECRET and WA_VERIFY_TOKEN
3. For WA_PHONE_NUMBER_ID, WA_ACCESS_TOKEN and WA_APP_SECRET use the values you got from the previous steps. For the WA_VERIFY_TOKEN, you can use any random string (generate one yourself), this will be added to the WhatsApp webhook in a later step.

4. Select the default encryption key – aws/secretsmanager. Click Next.
   1. Note: feel free to add a new key, however, make sure to modify the CDK project to provide permissions to that encryption Key.
5. Provide Secret name, description and Click Next.
   1. Note: If you add any additional resource permission and other settings please make sure the CDK stack resources are given permissions to this secret.
6. Click Next, and Store the secret.
   1. Note: you can configure automatic rotation setting based on your requirements, however, for our walkthrough we will keep the default values.
7. In the Secret manager console, search for the secret you just created and note down the Secret ARN, this is required later to deploy the code via CDK.

Get Amazon Connect instance details

1. Navigate to AWS Amazon Connect console
2. Choose the Amazon Connect instance and note down the Instance ARN
3. Login to your Amazon Connect Admin console, contact flows, and choose the contact flow you would like the WhatsApp channel to start the chat contact in and note down the Contact Flow ID

Install AWS CDK and Bootstrap CDK environment (skip if you have CDK installed)

npm -g install typescriptnpm -g install aws-cdk
cdk bootstrap aws://ACCOUNT_ID/AWS_REGION

Deploy the project

Make sure you have the following variables from the previous steps before continuing

• Amazon Connect Instance ARN
• Amazon Connect Contact flow ID
• AWS Secret Manager ARN which stores the values for WA_PHONE_NUMBER_ID, WA_ACCESS_TOKEN, WA_APP_SECRET and WA_VERIFY_TOKEN

1. Using Git, clone the repository from GitHub.

git clone git@github.com:amazon-connect/amazon-connect-message-streaming-examples.git

2. In your terminal move into the root of the directory

cd amazon-connect-message-streaming-examples

3. Install the dependencies for the CDK project and AWS Lambda functions

npm install
cd src/lambda/inboundMessageHandler
npm install
cd ../../..
cd src/lambda/outboundMessageHandler
npm install
cd ../../..
cd src/lambda/digitalChannelHealthCheck
npm install
cd ../../..

4. Deploy the CDK project using your AWS CLI profile. Pass in the context environment variables amazonConnectArn, contactFlowId and waSecretArn, which are required for the cdk stack.

Note: WhatsApp, SMS and Facebook Messenger channels are all part of the same CDK project. If you are would like to deploy the SMS or Facebook channels, you need to supply additional context parameters. 

For SMS, the pinpointAppId and smsNumber (the phone number) and for Facebook the fbSecretArn. for more details, please refer the SMS blog and the Facebook blog.

cdk deploy \
--context waSecretArn=<YOUR SECRET ARN> \
--context amazonConnectArn=<YOUR AMAZON CONNECT INSTANCE ARN> \
--context contactFlowId=<YOUR CONTACT FLOW ID

5. Once the CDK deployment has finished, note down the WhatsAppApiGatewayWebhook from the CDK output.

Meta console

1. In the CDK output in the terminal, find the API Gateway invoke URL, WhatsAppApiGatewayWebhook
2. Navigate back to Meta for Developers console.
3. Select WhatsApp and Configuration to access the webhook configuration page.
4. Under Webhook, click Edit.
   1. Callback URL as your API gateway invoke URL
   2. Verify token as the random string you created in the secret manager in step 2.
   3. Verify and save
5. Click Manage in the Webhook fields section
6. Click Subscribe in the messages row.
7. Click Done.

Congrats! You’ve successfully added WhatsApp as a digital channel to your Amazon Connect instance. Add the WhatsApp business Test Number as a contact in your WhatsApp account and send a message to the contact, you’ll be connected to your Amazon Connect instance!

Clean up 

1. Delete Whatsapp App by navigating to Meta for Developers, Select MyApps, Remove the Whatsapp App by selecting Remove App

2. Delete Meta for Developers developer account
3. Navigate to the AWS Secret Manager Console and delete the secret
4. Destroy the CDK stack

cdk destroy \
--context waSecretArn=<YOUR SECRET ARN> \
--context amazonConnectArn=<YOUR AMAZON CONNECT INSTANCE ARN> \
--context contactFlowId=<YOUR CONTACT FLOW ID>

Conclusion

In this blog, we showed you how to build a digital channel for Amazon Connect using the Amazon Connect Chat message streaming APIs and WhatsApp as the example. By implementing WhatsApp integration following the steps in this blog, your agents can start receiving and replying to customer messages on WhatsApp from the same agent desktop they already use for Amazon Connect voice, chat, and tasks.
To get started, visit our Github repository and deploy the project!

Please note: This is a sample project designed to be easily deployable for experimentation. The IAM policy permissions use least privilege, however AWS API Gateway deployed will be publicly accessible. Please take the appropriate measures to secure your AWS API Gateway following the public documentation Security in Amazon API Gateway.

TAGS: WhatsApp, messaging, digital channels, chat, Amazon Connect, Contact Center , API, agent, Amazon Connect Chat

Author Bio

Abhishek Pandey is a Senior Solutions Architect with Amazon Web Services. With over 16 years of enterprise IT experience, Abhishek is passionate about diving deep with customers to architect creative solutions that support business innovation across different industries. Abhishek inspires builders to unlock the value of the AWS Cloud, using his secret blend of passion, enthusiasm, customer advocacy, curiosity, and creativity.

Attila is an Amazon Connect Consultant with Amazon Web Services Professional Services group. Besides contact center experience, he has also had software development and enterprise networking background. Attila is always looking at innovative ways of enhancing product capabilities to deliver customer benefits.

Join us for AWS Contact Center Day, a free virtual event where you’ll learn about the future of customer service, how machine learning can optimize customer and agent experiences—and more. Register now »