Welcome

The messaging API for Amazon IVS Chat is designed to be used by your client applications (e.g., web-browser and Android/iOS apps) to interact with chat rooms alongside your live video. This is a WebSockets API using a token-based authentication scheme. WebSockets are widely supported by browsers and mobile client libraries to facilitate fully bidirectional communication between client and server.

Clients connect to a room over WebSockets (WSS) using secure access tokens created by your application with the CreateChatToken endpoint. Clients initiate a handshake to a WebSocket endpoint in the same region as the room they want to connect to. Clients make messaging requests by publishing JSON payloads over the WebSocket connection. Messaging requests are asynchronous. Success should be assumed if an error is not returned.

The API is an AWS regional service. For a list of supported regions, see the Amazon IVS Chat information on the Amazon IVS page in the AWS General Reference.

There are two sets of messaging operations:

• Publish operations are JSON payloads that clients can send to the Amazon IVS Chat service:

  • DeleteMessage — Instructs other clients to delete a message.

  • DisconnectUser — Disconnects another viewer from the Chat room. Use this in conjunction with the CreateChatToken flow to implement time-based or permanent user bans. For example, to permanently ban a user (viewer), precede this operation with a call to your application service, to prevent the application service from creating another token to the same room. To lift the ban (time- or logic-based), simply resume calling CreateChatToken.

  • SendMessage — Sends a message to participants of the room.

• Subscribe operations are JSON payloads that clients will receive from the Amazon IVS Chat service. Error messages are pushed to clients if an action fails.

  • Event — Events are messages generated by client actions or operations; e.g., join or leave notifications. Events may be generated by Amazon IVS Chat or your application. Applications should use the SendEvent HTTP endpoint to push event messages to the room.

  • Message — Messages from other clients that are sent to the room.

All the above are messaging operations. There is a separate API (all HTTP) for managing Chat resources; see the Amazon IVS Chat API Reference.

Connecting to a Room

1. When a viewer wants to connect to a room, the browser or client application requests a chat token from your application.

2. Your application determines whether the viewer should be authorized to chat. If yes, your application calls CreateChatToken to create an encrypted token. The token specifies the room to connect to, attributes for the user, and capabilities the connection will have in the room.

3. The token is returned to the client application. The token must be used to connect to a room within a brief period, and the token can only be used once.

4. The client application connects to the WebSocket endpoint, passing the token as an HTTP header. Tokens must be presented during the WebSocket handshake via the sec-websocket-protocol header.

5. During the WebSocket handshake, the token is securely decrypted and validated by Amazon IVS Chat.

6. If the handshake is successful, Amazon IVS Chat associates the specified user attributes and capabilities with the WebSocket connection.

7. The client application can begin making messaging requests and will receive subscribe operations from the room.