Using websockets to receive messages - Amazon Chime

Using websockets to receive messages

You can use the Amazon Chime JS SDK to receive messages using websockets, or you can also use another websocket client library of your choice.

Establishing a connection

Follow these steps to establish a websocket connection:

  1. Define an IAM policy that gives you permission to establish a websocket connection. The following example policy gives an AppInstanceUser permission to establish a websocket connection.

    "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action: [ "chime:Connect" ], "Resource": [ "arn:aws:chime:us-east-1:{awsAccountId}:app-instance/{appInstanceId}/user/{appInstanceUserId}" ] }, { "Effect": "Allow", "Action: [ "chime:GetMessagingSessionEndpoint" ], "Resource": [ "*" ] } ] }
  2. Use the GetMessagingSessionEndpoint API to retrieve the websocket endpoint.

  3. Use the URL returned by the GetMessagingSessionEndpoint API to construct a Signature Version 4 Signed WebSocket URL. If you need help doing that, you can follow directions in the Connect API.

Receiving messages

In order for anAppInstanceUser to start receiving messages after they successfully establish a connection, they must be added to a Channel. You can add AppInstanceUsers to a Channel via the CreateChannelMembership API.


An AppInstanceUser always receives messages for all channels that they are a member of as long as they have established a connection successfully.

And AppInstanceAdmin and a ChannelModerator do not receive messages on a channel unless you use the CreateChannelMembership API to explicitly add them.

Message structures

Every WebSocket message that you receive adheres to this format:

{ "Headers": {"Key": "Value"}, "Payload": "{\"Key\": \"Value\"}" }


Amazon Chime SDK messaging uses a single header key, x-amz-chime-event-type. The next section lists and describes the header's possible values and payloads.


Websocket messages return JSON strings. The structure of the JSON string depends on the x-amz-event-type headers.The following table lists the possible x-amz-chime-event-type values and payloads:


Payload format


N/A. This message is sent once after the user connects to the websocket. It indicates that any message or event on a channel that arrives after the user recieves the SESSION_ESTABLISHED message is guaranteed to be delivered to the user as long as the WebSocket stays open.


Channel message

















Connect API

Establishes a websocket connection to the back-end server to receive messages for an AppInstanceUser. The request has to be signed using AWS Signature Version 4. For more information about signing a request, see Signing AWS Requests with Signature Version 4 .


To retrieve the endpoint, you can invoke the GetMessagingSessionEndpoint API. You can use the websocket client library of your choice to connect to the endpoint.

Request Syntax

GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fus-east-1%2Fchime%2Faws4_request &X-Amz-Date=20201214T171359Z &X-Amz-Expires=10 &X-Amz-SignedHeaders=host &sessionId={sessionId} &userArn={appInstanceUserArn} &X-Amz-Signature=db75397d79583EXAMPLE

URI Request Parameters

All URI Request Query Parameters must be URL Encoded.


Identifies the version of AWS Signature and the algorithm that you used to calculate the signature. Amazon Chime supports only AWS Signature Version 4 authentication, so the value of this is AWS4-HMAC-SHA256.


In addition to your access key ID, this parameter also provides the AWS region and service—the scope—for which the signature is valid. This value must match the scope you use in signature calculations. The general form for this parameter value is:

<yourAccessKeyId>/<date>/<awsRegion>/<awsService >/aws4_request

For example:



The date and time format must follow the ISO 8601 standard, and must be formatted as yyyyMMddTHHmmssZ. For example if the date and time was 08/01/2020 15:32:41.982-700, then you must first convert it to UTC (Coordinated Universal Time) and submit it as 20200801T083241Z.


Lists the headers that you used to calculate the signature. The following headers are required in the signature calculations:

  • The HTTP host header.

  • Any x-amz-* headers that you plan to add to the request.


For added security, sign all the request headers that you plan to include in your request.


Provides the signature to authenticate your request. This signature must match the signature that Amazon Chime calculates. If it doesn't, Amazon Chime denies the request. For example, 733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7.


Optional credential parameter if using credentials sourced from the STS service.


Indicates a unique Id for the websocket connection being established.


Indicates the identity of the AppInstanceUser that is trying to establish a connection. The value should be the ARN of the AppInstanceUser. For example, arn:aws:chime:us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe