Build presence and typing indicators with Amazon Chime SDK messaging

Amazon Chime SDK is a set of real-time communications components that developers can use to quickly add messaging, audio, video, and screen sharing capabilities to their applications. Amazon Chime SDK messaging helps enable developers to connect communities of users with secure, scalable, and persistent messaging.

Using the existing APIs and capabilities of Amazon Chime SDK messaging, including channel flows and message types, developers can build channel presence and typing indicator features in to their applications.

Presence

Presence is a common feature for messaging applications and serve to maintain a status that indicates whether contacts are present and available to send and receive messages.

Some of the most common presence use cases include:

1. Telehealth – In a virtual waiting room, you may want to build a feature where patients check in on their mobile devices and wait to be called for their telehealth appointment. Presence allows their care provider to monitor the status of their doctor if it’s “With a patient” or “Running 5 minutes late”, and initiate the televisit when it is updated to “Available”.
2. Education – In distance education use cases, teachers or staff may want to track the presence or custom status of students to know if they are present in a particular channel, or if they are busy “Taking a test”, “In breakout session.”
3. Collaboration – In the context of collaboration, presence and user status can indicate to customers and colleagues when a user is present and a fast response can be expected or not. For example, users can let colleagues know when they are away, busy on a call, etc.
4. Help Desk/ Support – If you have an online help desk system, you may need to track if the customers you are chatting with are still connected based on their responsiveness or activity on your website to keep the chat session alive. The sessions for disconnected customers can be dropped, or the agents can follow up with the customers offline.
5. Gaming – In gaming, it is important for users to know which friends are online and available to play. When friends are online, it is also useful to know if they are busy playing a game currently or are between games. This allows users to join friends in a particular game, or invite friends to join them in a new game session.
6. Intelligent Message Routing – In many of the use cases where presence is used, it can also be used for intelligent routing of communications. For example, in a chat with a customer, an enterprise user might set their status to “Away”. This status can then be used to route messages that would otherwise be delivered in a chat room to the enterprise user’s phone via SMS. Another use could be to silence ad-hoc call notifications when a user has their status set to “Busy”, instead delivering a message to the user indicating they had a missed call or allowing the caller to leave a brief message which is then translated to text and delivered as a text message with attached recording to the user to check when they are free.

In this blog, you will learn how to implement automatic and custom presence statuses, as well as typing indicators, in a channel.

Note: Deploying and using the demo created in this post can incur AWS charges. See the prerequisites section for more information.

High Level Architecture

Automatic Presence

Automatic status events are ephemeral control messages as they are short-lived based on the activity of the user. The client application publishes automatic presence statuses in a channel – i.e. “Online”, “Idle”, “Busy” and “Offline”, when a user connects to the application, stays active/inactive in a channel, starts/joins a meeting, and disconnects from the application, respectively.

In the demo code,

1. Automatic presence statuses are published in a channel as non-persistent control messages.
2. The sender’s client-side application tracks the user activity, for instance, when they login and logout, switch between channels, join a meeting, etc, and sends events to the channel.
3. The recipients’ application parses the event and renders the status of the sender as “Online”, “Idle”, or “Busy”. The application also regularly checks the age of the last received event and marks the sender as “Offline” if it stops receiving new signals from the sender within the specified interval.

await sendChannelMessage({
    Content: "P|Auto|Online",
    Type: "CONTROL",
    Persistence: "NON_PERSISTENT",
    LastUpdatedTimestamp: "2021-10-26T02:49:11.096Z",
    ...
})

Custom Presence

With custom presence, users can set their preferred status in a channel – e.g. “Working from Home” or “I’m in Hawaii.”

Custom presence statuses are persisted to support on-demand retrieval of member presence information in a channel, and this is achieved by utilizing channel flows and channel metadata for processing and storage.

In the demo code,

1. We create a channel flow and associate it to the channel beforehand to process the custom presence messages.
2. We also create an AWS Lambda function to process the channel flow events and update the channel metadata with the custom status.
3. Then, we use the sendChannelMessage API with STANDARD message type to publish custom presence changes.

await sendChannelMessage({
    Content: 'changed status to "In Hawaii!"',
    Type: "STANDARD",
    Persistence: "PERSISTENT",
    Metadata: JSON.stringify({IsPresenceInfo: true, Status: "C|In Hawaii!"}),
    ...
})

Note that there is a 1KB limit for metadata storage, so this method should only be used for small channels with 10 members or less.

Typing Indicators

Typing indicators are a common feature to provide additional status, allowing users to see when someone is actively typing a message in a chat channel.

The demo application utilizes control messages to implement a typing indicator in a channel. Using Amazon Chime SDK messaging’s sendChannelMessage API, the application transmits signals within a channel when members start typing a message.

High Level Architecture

In the client application, there is an event listener to detect users typing a message and make an API call to send a typing indicator signal within a channel. It’s recommended to use a debounce function to limit the rate of API calls and also improve the performance of your client application.

debounce(()=>{
    sendChannelMessage({
        Content: JSON.stringify({Typing: 'Indicator'}),
        Type: "CONTROL",
        Persistence: "NON_PERSISTENT",
        LastUpdatedTimestamp: "2021-10-26T02:49:11.096Z",
        ...
    })
}, 500);

Prerequisites

1. Understanding of messaging types – Amazon Chime SDK messaging currently supports two types of messages, CONTROL and STANDARD.Standard messages are bigger in size and are most commonly used to send chat messages. Control messages are smaller in size and cheaper to send.Control messages are typically used for signaling use cases such as typing indicators, reactions, and polls. You can also use control messages to send and receive short messages in your messaging application to build features such as presence and user status.Please take a look at the Amazon Chime SDK pricing page for more information on pricing.
2. Understanding of messaging channel flows
3. Other pre-requisites to run this demo
   • An AWS account with administrator access.
   • Development experience and familiarity with JavaScript.
   • Install AWS Command Line Interface (AWS CLI) and NPM in your workspace.

Demo application

With the Amazon Chime SDK chat demo app, you can quickly experiment with various messaging features, such as, creating a channel and adding members, sending and receiving messages, and starting and joining a meeting within a channel. For this blogpost, the chat demo app has been updated to demonstrate how to build presence and typing indicator features within a channel for a messaging application.

This demo includes the following major components:

1. An AWS CloudFormation template is used
   • to set up the authentication layer with the option to use Amazon Cognito or AWS Security Token Service (AWS STS) to vend user credentials with a post authentication Lambda function,
   • bootstrap the demo application resources, including a Chime SDK App Instance and a Channel Flow processor AWS Lambda function.
2. The chat demo client side application that is built using the React framework, Amazon Chime SDK client library for JavaScript, and AWS Amplify JavaScript library.

Deploying the demo application

Step 1: Create the AWS resources

1. 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.
2. Go to the AWS CloudFormation Create stack page, choose Upload a template file and upload the template.yaml file located in the demo app. Then, click Next.
3. On the Specify Details page, enter a name for the stack: ChimeSDKMessagingDemo and DemoName: ChimeSDKMessagingDemo. Then, click Next.
4. On the Configure stack options page, click Next.
5. On the Review page, check the I acknowledge that AWS CloudFormation might create IAM resources check box. Then click Create.
6. Creating the stack exports outputs, including apiGatewayInvokeUrl, appInstanceArn, attachmentsS3BucketName, cognitoAppClientId, cognitoIdentityPoolId, and cognitoUserPoolId. Note these values for the demo app configuration in the next step.

Step 2: Deploy the chat demo app locally

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

1. Clone the project from GitHub.
   git clone https://github.com/aws-samples/amazon-chime-sdk.git
2. Run the following commands to navigate to the root folder of the Amazon Chime SDK chat demo:
   cd amazon-chime-sdk/apps/chat
3. Run the following commands to install all the dependencies for the Amazon Chime SDK chat demo:
   npm install
4. Open src/Config.js with the editor of your choice. Add the following configuration to it updating the values with the output from the AWS CloudFormation stack:

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

Step 3: Explore the chat demo app

1. On the homepage, you have the option to register a user for the chat application. Enter a username and password, then choose the Register button.
2. 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.

3. To confirm the user, go to User Pools and confirm the user by clicking on the username, and choosing Confirm User.

4. Once a user is confirmed, go back to the login screen and click on the Sign In button. Click again on the Sign In button.
5. Then, you will land on the home page of the chat demo app and you can start exploring the features.

Step 4: Experiment with automatic channel presence

1. Create a new channel, or open an existing channel.
2. Open a separate browser and join the same channel as a second user. Notice the channel presence status for both users is “Online”. Note: presence status change is published regularly within a specified interval (i.e 10 to 20 seconds in the demo app), so if you don’t see the status updates instantly, make sure to wait for some time.

3. Create another channel and open it. This makes the user inactive on the first channel. Notice the presence status for the user in the first channel is now changed to “Idle”.

4. Start a meeting on the first channel and join. Notice the presence status for the user in the first channel is changed to “Busy”.

5. Log out one of the users, or simply close the browser tab. Notice their presence status is changed to “Offline”.

Step 5: Experiment with the ‘Working from Home’ persistent status

1. Log back in and open the channel you have previously created.
2. Open a separate browser and join the same channel as a second user.
3. Enable “Presence Channel Flow” for the channel you have created.

4. Open the channel menu for one of the users and change their status to “Working from Home”.
5. Notice the channel member presence for that user is now updated to “Working from Home”.

6. Log out the same user, or simply close their browser tab. Notice their presence within the channel is unchanged.

Step 6: Set your own custom persistent status

1. Log back in and open the channel you have previously created.
2. Open a separate browser and join the same channel as a second user.
3. Open the channel menu for one of the users and change status to custom.

4. Notice the channel presence status for that user is updated to the custom status provided.

5. Log out the same user, or simply close their browser tab. Notice their presence status is unchanged.

Step 7: Experiment with the typing indicator feature

1. Log back in and open the channel you have previously created.
2. Open a separate browser and join the same channel as a second user.
3. As the first user, try typing a message in the channel.
4. Notice the typing indicator shown for the second user.

Clean Up

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 AWS CloudFormation stack and resources created in the section for deploying the demo application.

To delete the stack and its resources:

1. From the AWS CloudFormation console in the region you used in the step 1, 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 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

In this blog, you learned how to utilize the Amazon Chime SDK messaging capabilities to build presence and typing indicator features in your messaging applications. To get started with Amazon Chime SDK messaging, read our developer guide.