Business Productivity

Build Multiparty Conversations Across Applications and SMS with the Amazon Chime SDK and Amazon Pinpoint

In sales and service, chat messaging is an effective communication channel allowing customers and employees to communicate with each other as easily as they do with friends and family. These asynchronous conversations not only move the sales or service process forward they help develop a relationship between employees and customers. Common use cases include employees that are not directly tied to the contact center and often require multiple parties to be involved. For example, delivery drivers and customers, vacation home owners and guests, real estate agents and clients, financial advisors and clients, maintenance workers and customers, and many more. How a chat participant needs to access a conversation largely depends on their role and current context. An employee who is a frequent traveler may use a mobile app while an office employee may use a web application, and a customer may prefer to use SMS to avoid downloading an application.

Providing the ability to communicate across different devices and clients, often called omni-channel or cross-channel chat, is difficult without the right solution. The Amazon Chime SDK helps enables you to build chat at scale with thousands of users in a single conversation. It also provides you with administrative features like identity integration, archival and retention, and the ability to easily integrate with other services to process messages. Message processing can be used to update messages, translating them or removing potentially sensitive information like profanity and Personally Identifiable Information (PII). Message processing can also be used to send and receive messages to users via SMS or popular over-the-top (OTT) applications like WhatsApp and Facebook Messenger. The Amazon Chime SDK gives you control over how and where messaging data is processed, allowing you to keep data within the security boundary of AWS.

In this blog post, you will learn how to use the Amazon Chime SDK and Amazon Pinpoint to help coordinate the home loan process, allowing different parties to collaborate in chat using a web application and SMS. When you have completed the steps below, you will have a working web application that represents the experience of employees on the lender side working with multiple clients. You will also have a phone number the home buyer can use to communicate with the lending team throughout the buying process. The demo concept starts after a home buyer has been pre-approved for a loan and a loan team has been assigned to help them through the loan process.

Overview

The example app in this post is built around the Amazon Chime SDK and the channel flows feature. Channel flows allow developers to execute business logic on in-flight messages before they are delivered to members of a messaging channel. Using channel flows you can create flows that remove sensitive data such as government ID numbers, phone numbers, or profanity from messages before they are delivered, which may be helpful for implementing corporate communications policies or other communication guidelines. Here, channel flows are used to send and receive messages through SMS via Amazon Pinpoint.

Using the diagram below:

  1. The home buyer sends a message via SMS, which reaches Amazon Pinpoint.
  2. Amazon Pinpoint sends the message to Amazon Simple Notification Service (SNS) and then to AWS Lambda
  3. AWS Lambda
    1. Amazon Lex provides the conversational interface for user verification and adding additional SMS members.
    2. During user verification, AWS Lambda verifies loan numbers against a table in Amazon DynamoDB. Amazon DynamoDB is also used to store the channels and loan IDs associated with phone numbers.
    3. Inbound SMS messages are routed to Amazon Chime SDK messaging channels using the lookup table , matching the sender’s phone number to the channel.
    4. New channel messages, whether originating from SMS or from web app users also go through the channel flow, hitting AWS Lambda. For this demo, the flow results in outbound SMS to recipients participating via SMS and also blocks any messages containing profanity.

architecture

Deploying the Demo

Follow the steps below to set up Amazon Pinpoint, Amazon Lex, and then use AWS CloudFormation to set up the Amazon Chime SDK and other backend services to deploy the example application.

Please note your AWS account will be charged for usage of these services.

Amazon Pinpoint

  1. Open the Amazon Pinpoint console
  2. Select create a project
  3. Enter a project name
  4. Choose Create
  5. Choose Configure under SMS and Voice
    1. Under General Settings, choose on Enable the SMS channel for this project
    2. Change default message type to TRANSACTIONAL
    3. Keep other settings as it is and choose Save changes
  6. Go to Settings on left navigation then SMS and Voice
  7. Choose Request Phone number under Phone numbers → Number settings

    1. Choose United States as the Country (Other countries will work as long as you configure them for 2-way SMS.)
    2. Select Toll Free number type
    3. Only enable SMS capability check box
    4. Default message type as TRANSACTIONAL
    5. Quantity 1, choose Next then click on Request
  8. Find and select your new phone number under Number settings
    1. At the bottom of the form, select Enable 2 way SMS
    2. For Incoming message destination select Create a new SNS topic
    3. Provide AmazonChimeSDKSMSBlogSetup as your Amazon SNS topic name or choose your own
    4. Select Save
    5. Note the Amazon SNS topic ARN by going back into the phone number detail and expand the Two-way SMS section
  9. Add at least one destination phone number. We recommend adding two phone numbers so you can see the experience with multiple channel members using SMS.
    1. Add Phone Number
    2. Provide verification code received
  10. Go back to the Amazon Pinpoint main console and note down the project id

Amazon Lex

  1. Go to Amazon Lex V2 console, the import will not work in the Amazon Lex V1 console then Actions → Import
  2. Provide name SMSBlogBot or another name you choose
  3. Upload the AmazonChimeSDKSMSBlogLex.zip file
  4. Choose Create a role with basic Amazon Lex permissions
  5. For COPPA, select No
  6. Set timeout to 10 minutes
  7. Choose Import
  8. Select the newly created bot and note down the Bot ID in the Bot details section
  9. Choose View Alias → TestBotAlias and note down the Bot Alias ID
  10. Go to Bot versions → Draft version → English
  11. Select Build

AWS CloudFormation

  1. Click on the Launch Stack image below this sentence to launch a Cloudformation template that will setup the rest of the required infrastructure for the Amazon Chime SDK chat demo app in your AWS account
    Launch Stack
  2. Enter Information as following
    1. Stack Name – The default is AmazonChimeSDKSMSBlogSetup
    2. ChimeAppInstanceUserPrefix – The default is loanConsultant, when you create users with this prefix, they are designated as part of the loan team and will be added to new channels.
    3. DemoName – The default is AWSSDKChimeChannelFlowSMSDemo
    4. LexBotAliasId – Enter the bot alias ID you noted earlier
    5. LexBotId – Enter the Lex bot ID you noted earlier
    6. PinpointOriginationNumber – The toll free number you requested. Please provide it in the format +185585xxxxx, without spaces and hyphens.
    7. PinpointProjectId – The ID for the project you created
    8. PinpointRegisteredKeyword – Registered keyword for the Amazon Pinpoint project you created.
    9. PinpointSNSTopic – The Amazon SNS topic ARN you noted earlier when creating the Amazon Pinpoint project
  3. Select Create Stack
  4. Note down the outputs

Deploy the web app

Follow these steps to deploy the web app.

  1. git clone https://github.com/aws-samples/amazon-chime-sdk.git
  2. cd amazon-chime-sdk/apps/chat
  3. npm install
  4. Open src/Config.js (Note: You do not need an API Gateway URL)
  5. Modify values provided in Output of the AWS CloudFormation stack creation
  6. npm start

Exploring the demo

Create the loan team

  1. Open https://localhost:9000
  2. User registration
    On the homepage, you have the option to register a user for the chat application. To register a user, enter a username and password, then choose the Register button
    registering maryNOTE: For the purpose of this demo, you must register loan consultants with a the prefix used in the Amazon CloudFormation template. The prefix is “loanConsultant” by default.
  3. User confirmation
    When you choose Register, a user is created in the secure Amazon Cognito directory. However, this user is in unconfirmed state after registration. To confirm the user, an administrator logs into their Amazon Cognito directory (CognitoAuthenticator). The administrator confirms the user by clicking on the username, and choosing Confirm User.
    Confirm MaryNote: You can automate the user confirmation in Amazon Cognito using multiple mechanisms. Read documentation for more details.Once a user is confirmed in Amazon Cognito, they can log in to the chat application and start using its features.
  4. Return to your browser with https://localhost:9000 open. Enter your username and password, then choose the Sign in button.
  5. Repeat this process for as many users as you would like. Confirmed users given the appropriate prefix will automatically be added to new channels triggered by home buyers (SMS users) automatically as long as they have signed in at least once.

Connecting the home buyer with the loan team

To make this demo easier to set up and run, the user is required to initiate the conversation to be connected to their home team. Most production applications would likely create this connection automatically and initiate the conversation with the customer.

Follow the steps below to initiate the conversation with the loan team.

  1. From your mobile phone, send a message to the number you have connected with your Amazon Pinpoint Project. Send the message “I want to connect to my loan team”
  2. When asked, provide loan number, either 1234567890, 2345678901, or 3456789012
  3. Provide your full name and date of birth when prompted
  4. When asked if you want to proceed, enter “Yes.”
  5. In your browser, signed in as one of the loan consultants you have created, observe that a new channel has been created and the customers input displayed.
  6. Send a message as the loan consultant. You should receive the message on your phone.
  7. Note that if you send a message containing the words “profanity,” “swear,” “obscenity,” or “heck” the message will be blocked. For more information on detecting potentially sensitive content in messages see the previous post Use channel flows to remove profanity and sensitive content from messages in Amazon Chime SDK messaging.

Adding another SMS user

When people purchase a home, they often make the purchase with their partner. To add an additional SMS user to the chat, follow the steps below:

  1. From your mobile phone, send the message “I want to add a new member” to the number you have connected to your Amazon Pinpoint project
  2. Provide the name, date of birth, and phone number of the user you are adding. Make sure you have registered the number with Amazon Pinpoint if you are Sandboxed.
  3. Confirm you want to add the user.
  4. Once confirmed, the user will be added to the chat and they will receive a message on their phone.

Clean Up

If you don’t want to continue to be charged for the use of the example application, you can clean up by deleting the stack and resources created.

To delete the stack and its resources:

  1. From the AWS CloudFormation console in the Region you used in the Deploying the Demo section, select the stack that you created.
  2. Click Delete Stack
  3. In the confirmation message that appears, click Yes, Delete.
    At this stage, the status for your changes to DELETE_IN_PROGRESS. In the same way you monitored the creation of the stack, monitor its deletion by using the Events tab. When AWS CloudFormation completes the deletion of the stack, it removes the stack from the list.

Finally, delete the Amazon Chime SDK App Instance, delete the Amazon Pinpoint Project, and remove the associated phone number.

Enter the following commands in the CLI to delete the App Instance.

aws chime delete-app-instance --app-instance-arn <ARN FROM STEP 1>

To delete the Amazon Pinpoint project in the CLI enter the following command.

aws pinpoint delete-app --application-id <AMAZON PINPOINT APP ID>

Alternatively, open the Amazon Pinpoint console then:

  1. Select your Amazon Pinpoint project
  2. In the left navigation, choose Settings → General Settings
  3. Choose Delete project
  4. Confirm you want to delete the project

To remove the phone number:

  1. Open the Amazon Pinpoint console
  2. From the navigation, choose SMS and Voice → Phone Numbers
  3. Choose the phone number you used for the demo
  4. Select Remove phone number
  5. Confirm you want to remove the phone number

Conclusion and Next Steps

In this blog post you learned how to create a long-lived conversation between users in a web application, and users on SMS. This example can be further extended to support additional use cases, and add additional intelligence to enhance the experience for customers and employees without sending potentially sensitive data outside the security boundary of AWS. Some examples include:

  1. Create a process that steps through each phase of the loan process and adds new people from the lender side as needed until everything is closed.
  2. Extend the bot functionality to facilitate the conversation as the loan process progresses. The bot can be added as a member in the channel, introduce new team members as they are added to the chat, and answer additional questions from users like clarifying what the next step is and when it will happen.
  3. Create new channels along the way to separate content for each step, so those involved with each step only have access to the portion of the conversation that applies to their work.
  4. Add redaction of sensitive data like personally identifiable information (PII) or expand the profanity filter.
  5. Add sentiment analysis to messages to prioritize certain messages.
  6. Automate translation of messages into each users preferred language.

The Amazon Chime SDK messaging features are available today in the US East (N. Virginia) region at low per-message rates. To get started with Amazon Chime SDK messaging, read our developer guide.