Using Amazon Chime SDK messaging - Amazon Chime

Using Amazon Chime SDK messaging

You use this section of the Amazon Chime Developer Guide to help create messaging applications that run on the Amazon Chime service. This SDK provides the conceptual and practical information needed to create a basic messaging app.

Messaging prerequisites

You need the following to use Amazon Chime SDK messaging.

  • The ability to program.

  • An AWS account.

  • Permissions to configure IAM roles for the applications using Chime SDK messaging.

For the majority of cases, you also need:

  • A client application – Displays messaging UI, connects to web sockets using the Amazon Chime Client SDKs, manages state.

  • A server application – Manages identity and users.

Messaging concepts

To use Amazon Chime SDK messaging effectively, you must understand the following terminology and concepts.


To use Amazon Chime SDK messaging, you must first create an AppInstance. An AppInstance contains AppInstanceUsers and Channels. Typically, you create a single AppInstance for your application. An AWS account can have multiple AppInstances. You make app level settings, such as message retention and streaming configuration, at the AppInstance level. AppInstances are identified by a unique ARN in this format: arn:aws:chime:us-east-1:AWS_ACCOUNT_ID:app-instance/APP_INSTANCE_ID.


AppInstanceUsers are the entities that send messages, create channels, join channels, and so on. Typically, you create a one-to-one mapping of an AppInstanceUser to a user of your app. You can also create anAppInstanceUser to connect to backend services, which allows users to identify messages as coming from a backend service. AppInstanceUsers identified by an ARN, such as arn:aws:chime:us-east-1:AWS_ACCOUNT_ID:app-instance/APP_INSTANCE_ID/user/APP_INSTANCE_USER_ID. You control the APP_INSTANCE_USER_ID, and as a best practice, re-use the IDs that your application already has.


When you add an AppInstanceUser to a channel, that user becomes a member and can send and receive messages. Channels can be public, which allows any user to add themselves as a member, or private, which allows only channel moderators to add members. You can also hide channel members. Hidden members can observe conversations but not send messages, and they aren't added to the channel membership.


An AppInstanceUser who belongs to a channel can send and receive user messages. The AppInstanceUser can send STANDARD or CONTROL messages. STANDARD messages can contain 4KB of data and 1KB of metadata. CONTROL messages can contain only 30 bytes of data. Messages can be PERSISTENT or NON_PERSISTENT. You can retrieve PERSISTENT messages from the channel history. NON_PERSISTENT messages are only seen by channel members currently connected to Amazon Chime SDK messaging.

System Message

Amazon Chime generates system messages in response to events such as members joining or leaving a channel.

Messaging architecture

You can use Amazon Chime SDK messaging as a server-side and a client-side SDK. The server-side APIs create an AppInstance and AppInstanceUser. You can use various hooks and configurations to add application specific business logic and validation. For more information about doing that, see Streaming export of messaging data. Additionally, server-side processes can call APIs on behalf of an AppInstanceUser, or control a dedicated AppInstanceUser that represents backend processes.

Client-side applications represented as an AppInstanceUser can call the Amazon Chime SDK messaging APIs directly. Client-side applications connect via WebSocket to the messaging SDK when they are online. When connected, they receive real-time messages from any channel that they are a member of. When disconnected, an AppInstanceUser still belong to the channels it was added to, and it can load the message history of those channels by using the SDK's HTTP based APIs.

Client-side applications have permissions to make API calls as a single AppInstanceUser. To scope IAM credentials to a single AppInstanceUser, client side applications assume a parameterized IAM role via AWS Cognito Identity Pools, or by a small self-hosted backend API. For more information about authentication, see Authenticating end-user client applications. In contrast, server side applications typically have permissions tied to a single app instance user, such as a a user with administrative permissions, or they have permissions to make API calls on behalf of all app instance users.

Message types

You send messages through channels. You can send STANDARD, CONTROL, or SYSTEM messages.

  • STANDARD messages can be up to 4KB in size and contain metadata. Metadata is arbitrary, and you can use it in a variety of ways, such as containing a link to an attachment.

  • CONTROL messages are limited to 30 bytes and do not contain metadata.

  • STANDARD and CONTROL messages can be persistent or non-persistent. Persistent messages are preserved in the history of a channel and viewed by using a ListChannelMessages API call. Non persistent messages are sent to every AppInstanceUser connected via WebSocket.

  • Amazon Chime sends automated SYSTEM messages for events such as members joining or leaving a channel.

Messaging quotas

The Amazon Chime SDK messaging enforces the following quotas.



Eligible for increase

App Instances per AWS Account



Users per App Instance



Admins per App Instance



Channels per App Instance



Memberships per Channel



Moderators per Channel



Max concurrent connections per user (Amazon Chime messaging only, does not apply to meetings)



ChannelFlows per App Instance



Channel processors in a channel flow



Endpoints per App Instance User