Chat Message Review Handler - Amazon Interactive Video Service

Chat Message Review Handler

A message review handler allows you to review and/or modify messages before they are delivered to a room. When a message review handler is associated with a room, it is invoked for each SendMessage request to that room. The handler enforces your application’s business logic and determines whether to allow, deny, or modify a message. Amazon IVS Chat supports AWS Lambda functions as handlers.

Creating a Lambda Function

Before setting up a message review handler for a room, you must create a lambda function with a resource-based IAM policy. The lambda function must be in the same AWS account and AWS region as the room with which you will use the function. The resource-based policy gives Amazon IVS Chat permission to invoke your lambda function. For instructions, see Resource-Based Policy for Amazon IVS Chat (on the Security page of the Amazon IVS User Guide).


                    Workflow to create a lambda function with a resource-based IAM

Request Syntax

When a client sends a message, Amazon IVS Chat invokes the lambda function with a JSON payload:

{ "Content": "string", "MessageId": "string", "RoomArn": "string", "Attributes": {"string": "string"}, "Sender": { "Attributes": { "string": "string" }, "UserId": "string", "Ip": "string" } }

Request Body

Field Description


Attributes associated with the message.


Original content of the message.


The message ID. Generated by IVS Chat.


The ARN of the room where messages are sent.


Information about the sender. This object has several fields:

  • Attributes — Metadata about the sender established during authentication. This can be used to give the client more information about the sender; e.g., avatar URL, badges, font, and color.

  • UserId — An application-specified identifier of the viewer (end user) who sent this message. This can be used by the client application to refer to the user in either the messaging API or application domains.

  • Ip — The IP address of the client sending the message.

Response Syntax

The handler lambda function must return a JSON response with the following syntax. Responses that do not correspond to the syntax below or satisfy the field constraints are invalid. In this case, the message is allowed or denied depending on the FallbackResult value that you specify in your message review handler; see MessageReviewHandler in the Amazon IVS Chat API Reference.

{ "Content": "string", "ReviewResult": "string", "Attributes": {"string": "string"}, }

Response Fields

Field Description


Attributes associated with the message returned from the lambda function.

If ReviewResult is DENY, a Reason may be provided in Attributes; e.g.:

"Attributes": {"Reason": "denied for moderation

In this case, the sender client receives a WebSocket 406 error with the reason in the error message. (See WebSocket Errors in the Amazon IVS Chat Messaging API Reference.)

  • Size Constraints: Maximum 1 KB

  • Required: No


Content of the message returned from the Lambda function. It could be edited or original depending on the business logic.

  • Length Constraints: Minimum length of 1. Maximum length of the MaximumMessageLength you defined when you created/updated the room. See the Amazon IVS Chat API Reference for more information. This applies only when ReviewResult is ALLOW.

  • Required: Yes


The result of review processing on how to handle the message. If allowed, the message is delivered to all users connected to the room. If denied, the message is not delivered to any user.

  • Valid Values: ALLOW | DENY

  • Required: Yes

Sample Code

Below is a sample lambda handler in Go. It modifies the message content, keeps the message attributes unchanged, and allows the message.

package main import ( "context" "" ) type Request struct { MessageId string Content string Attributes map[string]string RoomArn string Sender Sender } type Response struct { ReviewResult string Content string Attributes map[string]string } type Sender struct { UserId string Ip string Attributes map[string]string } func main() { lambda.Start(HandleRequest) } func HandleRequest(ctx context.Context, request Request) (Response, error) { content := request.Content + "modified by the lambda handler" return Response{ ReviewResult: "ALLOW", Content: content, }, nil }

Associating and Dissociating a Handler with a Room

Once you have the lambda handler set up and implemented, use the Amazon IVS Chat API:

  • To associate the handler with a room, call CreateRoom or UpdateRoom and specify the handler.

  • To disassociate the handler from a room, call UpdateRoom with an empty value for MessageReviewHandler.Uri.

Monitoring Errors with Amazon CloudWatch

You can monitor errors occurring in message review with Amazon CloudWatch, and you can create alarms or dashboards to indicate or respond to the changes of specific errors. If an error occurs, the message is allowed or denied depending on the FallbackResult value you specify when you associate the handler with a room; see MessageReviewHandler in the Amazon IVS Chat API Reference.

There are several types of errors:

  • InvocationErrors occur when Amazon IVS Chat cannot invoke a handler.

  • ResponseValidationErrors occur when a handler returns a response that is invalid.

  • AWS Lambda Errors occur when a lambda handler returns a function error when it has been invoked.

For more information on invocation errors and response-validation errors (emitted by Amazon IVS Chat), see the Amazon IVS Chat information in Monitoring Amazon IVS with Amazon CloudWatch. For more information on AWS Lambda errors, see Working with Lambda Metrics.