Build chat features into your application with Amazon Chime SDK messaging

Overview

We have heard from Amazon Chime SDK customers since our launch in 2019 that they need messaging features in their applications. Telehealth customers want to enable real-time and asynchronous communication between care providers and patients. Live event hosts want participants to discuss content in real-time over messaging while they watch a video stream. Services that host virtual trade shows want to use messaging to connect conference attendees to experts in virtual booths.

In response, we have built messaging into the Amazon Chime SDK. However, we have designed messaging in the Amazon Chime SDK to be more than just basic chat. Customers with chat use cases can create experiences that also connect communities of users through channels. Customers can create channels for scenarios that include 1-to-few members, or create channels with up to 100,000 members. Customers can also build real-time collaboration features that enable multiple users to view and update applications at the same time, using the Amazon Chime SDK for messaging to maintain a consistent state between each users view. Today, messaging is being used by customers like PlayerLync, a mobile workforce enablement service, to enable learning and collaboration at work.

“At PlayerLync, we provide customers like Starbucks, Crocs, and Southern Company Gas with an all-in-one solution to train, learn, and collaborate more efficiently,” said Greg Menard, Chief Technology Officer at PlayerLync. “When we started looking to add additional communication capabilities to our existing features, we chose the Amazon Chime SDK because it offers the control to build features into our existing user experience. We also like that it offers AWS’s security and scalability and integration with familiar AWS services for additional capabilities. Adding voice and video was simple and has worked flawlessly. The new messaging features of the SDK will enable us to provide customers with broadcast messages to keep all of their employees informed about relevant topics and implement one-to-one direct messaging. The Amazon Chime SDK provides fine-grained control over messaging data and user access so we can meet the strict legal and regulatory requirements of our customers.”

Three primary components make up the Amazon Chime SDK messaging. First, the Amazon Chime SDK for Javascript maintains the websocket connection on the client side. Second, the AWS SDK contains messaging APIs from both the client-side and server-side. Finally, React UI components are optionally available to make it easy to add common chat capabilities to your applications.

Introduction to the Amazon Chime SDK Chat Demo Application

The easiest way to get started with messaging in the Amazon Chime SDK is to deploy our chat demo application. By completing the steps below, you will learn how to deploy the Amazon Chime SDK Chat Demo Application, create users and enable them to communicate in chat channels through an interface that will feel familiar to anyone that has used a modern chat messaging application. This application is designed in a way that it can be used as a starting point for your own application, or just a quick way to try out the features of the Amazon Chime SDK for messaging on your own.

Pre-requisites:

For this walkthrough, you should have the following pre-requisites:

An AWS account with administrator access.
Development experience and familiarity with JavaScript.
Install AWS CLI and NPM in your workspace.

Demo Application Architecture

The diagram below explains the architecture for the chat demo application built with Amazon Chime SDK for messaging. Please note your AWS account will be charged for usage of these services.

The Amazon Chime AppInstance, which acts as the data plane for all messages.
An AWS CloudFormation template is used to set up the authentication layer which uses Amazon Cognito with a post authentication Lambda function. This template also sets up an Amazon S3 bucket to store attachments uploaded by users in the demo app.
The chat demo application is deployed and can be launched locally for testing purposes. This application is built using the React framework, and uses the AWS Amplify JavaScript library to store attachments in Amazon S3, authentication with Amazon Cognito, and using the Amazon Chime SDK Client Library to utilize its messaging features.

This diagram shows how the APIs in the Amazon Chime SDK are called from a client-side application. It includes authentication, authorization, messaging lifecycle, and attachments for an application developed with the Amazon Chime SDK.

Deploying the Chat Demo Application

In this section, you will learn how to set up the Amazon Chime SDK for messaging demo application in your AWS account.

The high-level steps are as follows:

Using the available AWS CloudFormation template, set up a secure user directory for chat users using Amazon Cognito, an Amazon Chime app instance for chat, and an Amazon S3 bucket for attachments.
Deploy the Amazon Chime chat demo app locally.
Explore the features of the demo application.

Step 1. Set up a secure user directory for chat users using Amazon Cognito and an Amazon S3 bucket for attachments

Sign in to the AWS Management Console with your primary account. Switch to the us-east-1 (N. Virginia) Region. Note: The AWS CloudFormation template in this section needs to be launched in US east (N. Virginia) Region.
Click on the Launch Stack image below this sentence to launch a Cloudformation template that will setup the required infrastructure for the Amazon Chime SDK chat demo app in your AWS account.
On the Create Stack page, click Next.
On the Specify Details page, enter the following information:
DemoName– Unique Demo Name for Amazon Cognito resources, such as ‘ChimeSDKMessagingDemo’
Choose Next, and then Next on the Configure stack options page.
On the Review page, check the I acknowledge that AWS CloudFormation might create IAM resources check box. Then click Create.
Creating the stack generates 4 outputs- cognitoAppClientId, attachmentsS3BucketName, cognitoIdentityPoolId, appInstanceArn, and cognitoUserPoolId. Note these values for the demo app configuration in the next step.

Step 2. Deploy the Amazon Chime SDK chat demo app locally

In this section, you deploy a simple web app written in the React framework in your local environment. This app demonstrates the Amazon Chime messaging SDK features. Once you set up the app locally, you are able to get started.

Clone the project from GitHub.

git clone https://github.com/aws-samples/amazon-chime-sdk.git

Run the following commands to navigate to the root folder of the Amazon Chime SDK chat demo:cd ./amazon-chime-sdk/apps/chat
Run the following commands to install all the dependencies for the component library
```
npm install
```

Open ./src/Config.js with the editor of your choice. Add the following configuration to it:

const appConfig = {
cognitoUserPoolId: '<COGNITO USER POOL ID FROM STEP 1>',
cognitoAppClientId: '<COGNITO APP CLIENT ID FROM STEP 1>',
cognitoIdentityPoolId: '<COGNITO IDENTITY POOL ID FROM STEP 1>',
appInstanceArn: '<COGNITO APP INSTANCE ARN FROM STEP 1>',
region: 'us-east-1',
attachments_s3_bucket_name: '<S3 BUCKET NAME FROM STEP 1>'
};
export default appConfig;

Once the configuration for the application is entered, run the following commands in the demo/chat folder to set up your front-end server locally.
```
npm start
```
Open your browser and navigate to https://localhost:9000 to start testing.

Step 3: Explore the Amazon Chime SDK chat demo

In this section, you walk through using the demo app and its features.

User registration
On the homepage, you have the option to register a user for the chat application.

User confirmation
During user registration, a user is created in the secure Amazon Cognito directory you set up in step 2. 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.

Note: 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.

Other features
In this demo app, you are also able to create channels for specific conversations and add members to it. These channels can be public (non-members can read messages and add themselves as members) or private (only members can read and send messages). Additionally, private channels can be restricted, which only allows moderators to add new members, or unrestricted, which allows any current member to add additional members. Moderators of a channel are able to edit channel details, manage members, and delete the channel.Once a channel is created, members can send, edit, or delete their messages in the channel. These messages can be plaintext or attachments. In this demo, attachments are securely stored in an Amazon S3 bucket created in your AWS account in step 2. They can be up to 5mb each in size.
Note: We’ve used Amazon S3 for attachments, but the Amazon Chime SDK supports your choice of storage

Cleanup

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

To delete the stack and its resources:

From the AWS CloudFormation console in the Region you used in the step 2, select the stack that you created.
Click Delete Stack.
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 app instance created in step 1 using the following commands in CLI:

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

Conclusion

With the Amazon Chime SDK messaging features, customers are easily able to build and customize their own messaging capabilities for their applications. They don’t have to worry about the heavy lifting of managing a complex backend infrastructure. In this blog post, you learned about the Amazon Chime SDK for messaging, how to use it, and how to to quickly spin up a chat application.

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.

Business Productivity