Business Productivity
Creating read-only chat channels for announcements with Amazon Chime SDK messaging
Amazon Chime SDK messaging provides the building blocks needed to build chat and other real-time messaging features. Available APIs include sending messages, retrieving message history, editing messages, deleting messages, setting retention policies on stored messages, and streaming chat export. These APIs are combined with the Amazon Chime SDK for JavaScript and managed messaging infrastructure so developers don’t have to worry about building and scaling their own.
In this blog, you will learn how to create read-only channels that can be used to broadcast announcements to users. Announcement channels are helpful for a number of different use cases including for enterprise chat applications that want a single channel to send announcements to employees, for education applications that want to send messages to students or teachers, and for application developers that want to engage their customers. This blog covers two different ways to create read-only channels. In example one, we cover the ability to add hidden members to a private channel. These hidden members can read messages in the channel, but they cannot see other members in the same channel, or send messages to the channel. In example two, user privileges are restricted in rooms that are tagged as ‘ReadOnly’, thereby preventing users from sending or updating messages.
Pre-requisites
For this walkthrough, you should have the following pre-requisites:
- An AWS account with administrator access.
- Development experience and familiarity with JavaScript and Amazon Identity and Access Management (IAM).
- Install AWS CLI (make sure you have the latest version) and NPM in your workspace.
Setting up your environment
For simplicity, we will be starting with the chat demo app covered in the Build chat features into your application with Amazon Chime SDK messaging blog post. Before continuing with this blog, you should follow the steps there to get the demo app up and running, and save the AppInstanceARN from Step 1.
Please note your AWS account will be charged for usage of the services used by the demo app.
Once you have the demo app up and running, to prepare your environment to complete the two examples in this blog post, you will also need to follow these steps to set up your environment:
- Create an IAM user with developer access for Amazon Chime SDK messaging
- Create an AppInstanceAdmin to run admin APIs
- Create a server policy for your IAM user with developer access
- Create the IAM policy for your AppInstanceAdmin with a trust policy so that your IAM user can assume the AppInstanceAdmins role
The IAM user with developer access is used to run developer APIs, like creating app instance users, and to run AWS Security Token Service (AWS STS) commands to assume the role of your AppInstanceAdmin to run administrator commands. When using these two users, it is easiest to have two sessions open in your terminal. If your terminal supports tabs, you can open two tabs to create two separate sessions. One session is used for your developer user, and the other for the AppInstanceAdmin.
Creating an IAM user with developer access for Amazon Chime SDK messaging
Once you have the demo app up and running, you will also want to make sure you have an IAM user with access to Amazon Chime SDK messaging, you cannot use your Root user.
Create a new IAM policy called AmazonChimeSDKMessagingDev:
- Open the Identity and Access Management (IAM) Console
- In the left navigation, choose Policies
- Choose Create Policy
- Select the JSON tab
- In the text area paste the policy below
- Choose Next:Tags
- Choose Next:Review
- Enter the name AmazonChimeSDKMessagingDev
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "chime:CreateAppInstance", "chime:DescribeAppInstance", "chime:ListAppInstances", "chime:UpdateAppInstance", "chime:DeleteAppInstance", "chime:CreateAppInstanceUser", "chime:DeleteAppInstanceUser", "chime:ListAppInstanceUsers", "chime:UpdateAppInstanceUser", "chime:DescribeAppInstanceUser", "chime:CreateAppInstanceAdmin", "chime:DescribeAppInstanceAdmin", "chime:ListAppInstanceAdmins", "chime:DeleteAppInstanceAdmin", "chime:PutAppInstanceRetentionSettings", "chime:GetAppInstanceRetentionSettings", "chime:PutAppInstanceStreamingConfigurations", "chime:GetAppInstanceStreamingConfigurations", "chime:DeleteAppInstanceStreamingConfigurations", "chime:TagResource", "chime:UntagResource", "chime:ListTagsForResource" ], "Effect": "Allow", "Resource": "*" } ] }
- Choose Create Policy
- In the left navigation, choose Users
- Select Add User
- Enter the name AmazonChimeSDKMessagingDev
- Select the checkbox for Programmatic Access
- Choose Next:Permissions
- Choose Attach existing policies directly
- Attach each of the policies below:
- IAMFullAccess
- AmazonS3FullAccess
- AmazonChimeSDKMessagingDev (Managed Policy)
- Select Next:Tags
- Choose Next:Review
- Choose Create User
- Download and save the user credentials to configure the AWS CLI
Creating your app instance admin to run admin APIs
Once you have AmazonChimeSDKMessagingDev user created, configure the AWS CLI to use AmazonChimeSDKMessagingDev and us-east-1 and then create an AppInstanceAdmin.
Via CLI, create a user (John)
aws chime create-app-instance-user --app-instance-arn "<AppInstanceArnYouSavedFromDemoApp>" --name "John" --app-instance-user-id "John"
This will return an AppInstanceUserARN, save it.
Promote the user (‘John’) to AppInstanceAdmin
aws chime create-app-instance-admin --app-instance-arn "<AppInstanceArnYouSavedFromDemoApp>" --app-instance-admin-arn "<JohnsArn>"
Creating a server policy for your IAM user with developer access
To enable your AmazonChimeSDKMessagingDev user to assume the role of your AppInstanceAdmin, you will need to create a server policy and attach it to the AmazonChimeMessagingDev user. Create the policy below and attach it to your AmazonChimeSDKMessagingDev user. Follow the same steps used previously to create the policy and attach it to the AmazonChimeSDKMessagingDev user.
To create the policy and attach it to the user:
- Open the Identity and Access Management (IAM) Console
- In the left navigation, choose Policies
- Choose Create Policy
- Select the JSON tab
- In the text area paste the policy below and update with your AWS account id
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sts:AssumeRole", "sts:TagSession" ], "Resource":"arn:aws:iam::<YOURAWSACCOUNTID>:role/ChimeMessagingUserRole" } ] }
- Choose Next:Tags
- Choose Next:Review
- Enter the name ChimeSampleAppServerPolicy
- Choose Create Policy
- In the left navigation choose Users
- Click on AmazonChimeSDKMessagingDev
- Choose Add Permissions
- Choose Attach Existing Policies Directly
- Search for then select ChimeSampleAppServerPolicy
- Choose Add Permissions
Creating an IAM user role with user policy for your AppInstanceAdmin and trust relationship with the AmazonChimeMessagingDev role
So that you are able to assume the role of John from the AWS CLI, you need to create a new IAM role. We will call this role ChimeMessagingUserRole and assign it the ChimeMessagingUserPolicy below.
- Open the IAM Console
- In the left navigation select Policies
- Choose Create Policy
- Select the JSON tab and paste the policy below
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "chime:GetMessagingSessionEndpoint" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "chime:SendChannelMessage", "chime:ListChannelMessages", "chime:CreateChannelMembership", "chime:ListChannelMemberships", "chime:DeleteChannelMembership", "chime:CreateChannelModerator", "chime:ListChannelModerators", "chime:DescribeChannelModerator", "chime:CreateChannel", "chime:DescribeChannel", "chime:ListChannels", "chime:DeleteChannel", "chime:RedactChannelMessage", "chime:UpdateChannelMessage", "chime:Connect", "chime:ListChannelBans", "chime:CreateChannelBan", "chime:DeleteChannelBan", "chime:ListChannelMembershipsForAppInstanceUser" ], "Resource": [ "<AppInstanceArnYouSavedFromDemoApp>/user/${aws:PrincipalTag/username}", "<AppInstanceArnYouSavedFromDemoApp>/channel/*" ] } ] }
Replace the AWS Account ID and AppInstanceArn with your AWS Account ID and your AppInstanceArn
- Select Next:Tags
- Select Next:Review
- Enter ChimeMessagingUserPolicy as the policy name
- Choose Create Policy
- In the left navigation select Roles
- Choose Create Role
- For the type of entity, select Another AWS Account
- For the Account ID, enter your own account ID.
- Choose Next:Permissions
- Search for and select ChimeMessagingUserPolicy
- Choose Next:Tags
- Choose Next:Review
- For role name enter ChimeMessagingUserRole
- Choose Create Role
The ChimeMessagingUserRole then needs to have a trust relationship set up with the ChimeSampleAppServerRole
Still in the IAM console:
- Open the ChimeMessagingUserRole
- Select the Trust Relationships tab
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::<YOURAWSACCOUNTID>:user/AmazonChimeSDKMessagingDev" }, "Action": [ "sts:AssumeRole", "sts:TagSession" ] } ] }
- Choose Edit trust relationship
- Choose JSON and paste the policy below, making sure to add your own AWS Account ID
- Choose Update Trust Policy
Once these steps are complete, you are ready to move on to the examples.
Example One: Creating a private channel with hidden members
When you add new members to channels using CreateChannelMembership, you have the option to add them as ‘HIDDEN.’ When added as hidden, users do not show up as members when other members call ListChannelMemberships. This is useful for bots that need access to channel messages, but don’t need to interact with other members. It can also be useful for support use cases where managers may need to monitor ongoing conversations, but not participate. Because hidden members cannot send messages, using this option also works for creating read-only channels, and has the added benefit of keeping other members private.
Steps
- Open your demo app in your browse https://localhost:9000
- Using the sign in/registration page, create a user ‘Jane’ and verify her in Amazon Cognito using the steps provided in the Build chat features into your application with Amazon Chime SDK messaging post. Follow the same process to create a user ‘Mary’.
- Open your terminal and as the AmazonChimeSDKMessagingDev user, use AWS STS to assume the role of John, your AppInstanceAdmin. It is recommended to run the STS command in one tab, and then open another tab to run the commands as John.
aws sts assume-role --role-arn "arn:aws:iam::<YOURAWSACCOUNTID>:role/ChimeMessagingUserRole" --role-session-name John —tags Key=username,Value=John
- After you run this command, credentials will be returned that include an AccessKeyID, SecretAccessKey, and SessionToken. Open a second terminal tab, and run the following commands with the values returned by STS assume-role to change the credentials used by the AWS CLI. Once this is done, the second terminal tab can be used to run commands as John.
export AWS_ACCESS_KEY_ID=<key_goes_here>
export AWS_SECRET_ACCESS_KEY=<key_goes_here>
export AWS_SESSION_TOKEN=<key_goes_here>
- Now, in the terminal tab you are using to run commands as John, create a new Private channel called ‘Read-Only Example One’ and make it Private and Restricted.
aws chime create-channel --app-instance-arn "<AppInstanceArnYouSavedFromDemoApp>" --name "Announcements Example One" --privacy "PRIVATE" --mode "RESTRICTED" --chime-bearer "<JohnsArn>"
Save the channel ARN. - Add your users Jane and Mary to the channel as hidden members.
aws chime list-app-instance-users —app-instance-arn "<AppInstanceArnYouSavedFromDemoApp>"
- Grab the AppInstanceUserArn for Jane and Mary and run this command once for each user with each of their ARNs.
aws chime create-channel-membership --channel-arn "<AppInstanceArnYouSavedFromDemoApp>" --member-arn "<UserArn>" --chime-bearer "<JohnsArn>" —type HIDDEN
- As your AppInstanceAdmin send a channel message into the channel
aws chime send-channel-message --channel-arn "<SavedChannelArn>" --type "STANDARD" --persistence "PERSISTENT" --content "Hey folks" —chime-bearer "<JohnsArn>"
- As one of your users, sign in to the demo app and confirm the user has access to the channel and the messages, but cannot send.
To keep this demonstration simple, we have not modified the UI to reflect that status of the channel as a Broadcast or Read-Only channel. In a production application, you should make it clear to users that the channel is different so they understand why they are unable to send messages.
Example Two: Denying access to SendChannelMessage and UpdateChannelMessage for channels tagged as ‘ReadOnly’
In Amazon Chime SDK messaging, after a user is authenticated, AWS IAM policies are vended to users and define which APIs they have access to and on which resources. This access can include all APIs within the scope of their assigned role, or a subset of them. This policy can also be used to grant more access or less access on specific resources, such as channels. Using this ability to scope down access is an alternative means of creating read-only channels for announcements.
The steps to create read-only channels with scoped down IAM policies are:
- Modify the CognitoAuthorizedPolicy created for the demo app with a condition that only grants access to SendChannelMessage and UpdateChannelMessage if channels are not tagged as ‘ReadOnly’
- Create a new private channel and tag it with the resource tag ‘ReadOnly’
- Add users to the channel by running this command for Jane and Mary
- As your AppInstanceAdmin send a channel message into the channel
- As one of your users, sign in to the demo app and confirm the user has access to the channel and the messages, but cannot send.
Modify the IAM policy created for the users in the demo app
To eliminate the ability for users to send or update messages in channels labeled as ReadOnly, you will need to modify the IAM policy created with the CloudFormation template for the demo application. This policy will be updated so that access to SendChannelMessage and UpdateChannelMessage is only granted if channels are not tagged as ‘ReadOnly’
You can find this policy by:
- Opening the CloudFormation console
- Choosing amazon-chime-sdk-chat-demo-app under the list of stacks.
- Under resources, choose the link next to CognitoAuthorizedRole
- Attached to this role you will find the ChimeSDKMessagingDemo-ChimeSDKDemoUserPolicy
Below you will find the entire policy, but rather than copy and pasting the policy below and replacing the values in brackets with your own AWS Account ID, Cognito Identity Pool ID, and App Instance ARN you can alternatively just add the condition for the resource tag for SendChannelMessage and UpdateChannelMessage and remove both of those actions from the top section.
ChimeSDKMessagingDemo-ChimeSDKDemoUserPolicy
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"chime:GetMessagingSessionEndpoint"
],
"Resource": "*",
"Effect": "Allow"
},
{
"Action": [
"cognito-idp:ListUsers"
],
"Resource": "<CognitoPoolARN>",
"Effect": "Allow"
},
{
"Action": [
"chime:ListChannelMessages",
"chime:CreateChannelMembership",
"chime:ListChannelMemberships",
"chime:DeleteChannelMembership",
"chime:CreateChannelModerator",
"chime:ListChannelModerators",
"chime:DescribeChannelModerator",
"chime:CreateChannel",
"chime:DescribeChannel",
"chime:ListChannels",
"chime:UpdateChannel",
"chime:DeleteChannel",
"chime:RedactChannelMessage",
"chime:Connect",
"chime:ListChannelMembershipsForAppInstanceUser",
"chime:CreateChannelBan",
"chime:ListChannelBans",
"chime:DeleteChannelBan",
"chime:TagResource"
],
"Resource": [
"<YourAppInstanceArn>/user/${cognito-identity.amazonaws.com:sub}",
"<YourAppInstanceArn>/channel/*"
],
"Effect": "Allow"
},
{
"Action": [
"chime:SendChannelMessage",
"chime:UpdateChannelMessage"
],
"Resource": [
"<YourAppInstanceArn>/user/${cognito-identity.amazonaws.com:sub}",
"<YourAppInstanceArn>/channel/*"
],
"Condition": {
"StringNotLike": {
"aws:ResourceTag/readonly": [
"true"
]
}
},
"Effect": "Allow"
}
]
}
Create a new private channel and tag it with the resource tag ‘ReadOnly’
aws chime create-channel --app-instance-arn "<SavedChannelArn>" --name "Announcements Example Two" --privacy "PRIVATE" --mode "RESTRICTED" --tags Key="readonly",Value="true" --chime-bearer "<JohnsArn>"
Save the channel ARN
Add users to the channel by running this command for Jane and Mary
aws chime create-channel-membership --channel-arn "<AppInstanceArnYouSavedFromDemoApp>" --member-arn "<UserArn>" --chime-bearer "<JohnsArn>" --type HIDDEN
As your AppInstanceAdmin send a channel message into the channel
aws chime send-channel-message --channel-arn "<SavedChannelArn>" --type "STANDARD" --persistence "PERSISTENT" --content "Hello again folks" --chime-bearer "<JohnsArn>"
As one of your users, sign in to the demo app and confirm the user has access to the channel and the messages, but cannot send.
Again, with this example we have not modified the user interface to let users know why the channel is different than others. As a next step, you can modify the interface to show that the channel is for announcements, and remove or disable UI components like the text field for sending messages.
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 of the Build chat features into your application with Amazon Chime SDK messaging blog post.
.
To delete the stack and its resources:
- From the AWS CloudFormation console in the Region, 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 your Amazon Chime app instance using the following commands in AWS CLI:
aws chime delete-app-instance --app-instance-arn <AppInstanceArnYouSavedFromDemoApp>
Conclusion
With Amazon Chime SDK messaging, 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 and scaling a complex infrastructure. In this blog post, you learned how to create read-only channels for broadcast announcements.
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.