AWS.IVSChat reference

CreateChatToken

Source: src/AWS/IVSChat/CreateChatToken.ts

Mint an encrypted chat token that an end user presents to open a WebSocket connection to the bound room — the effectful call made from a deployed Lambda or Task. The capabilities field grants SEND_MESSAGE, DELETE_MESSAGE, and/or DISCONNECT_USER to the token holder (a token with no capabilities can only view chat); attributes attaches profile data (display name, icon, …) to every message the user sends. The returned token is sensitive and surfaces as a Redacted value.

CreateChatToken: Minting Chat Tokens

Provide the CreateChatTokenHttp implementation layer on the Function effect, bind the room in the init phase, then call the returned client at runtime. The binding grants ivschat:CreateChatToken on the room and injects its ARN as the roomIdentifier automatically.

// init
const room = yield* IVSChat.Room("LiveChat");
const createChatToken = yield* IVSChat.CreateChatToken(room);

return {
  fetch: Effect.gen(function* () {
    // runtime
    const { token, sessionExpirationTime } = yield* createChatToken({
      userId: "user-123",
      capabilities: ["SEND_MESSAGE"],
      sessionDuration: "30 minutes",
      attributes: { displayName: "Sam" },
    });
    return HttpServerResponse.json({
      token: token !== undefined ? Redacted.value(token) : undefined,
      sessionExpirationTime,
    });
  }),
};
// on the Function effect:
// .pipe(Effect.provide(IVSChat.CreateChatTokenHttp))

DeleteMessage

Source: src/AWS/IVSChat/DeleteMessage.ts

Moderate the bound room by deleting a message — the effectful call made from a deployed Lambda or Task. It broadcasts a DELETEMESSAGE event to every connected client, directing them to remove the message (id is the ID from the WebSocket SendMessage response); an optional reason is attached to the event.

DeleteMessage: Moderating Messages

Provide the DeleteMessageHttp implementation layer on the Function effect, bind the room in the init phase, then call the returned client at runtime. The binding grants ivschat:DeleteMessage on the room and injects its ARN as the roomIdentifier automatically.

// init
const room = yield* IVSChat.Room("LiveChat");
const deleteMessage = yield* IVSChat.DeleteMessage(room);

return {
  fetch: Effect.gen(function* () {
    // runtime
    const { id } = yield* deleteMessage({
      id: flaggedMessageId,
      reason: "abusive content",
    });
    return HttpServerResponse.json({ deleted: id });
  }),
};
// on the Function effect:
// .pipe(Effect.provide(IVSChat.DeleteMessageHttp))

DisconnectUser

Source: src/AWS/IVSChat/DisconnectUser.ts

Moderate the bound room by disconnecting all WebSocket connections of a user — the effectful call made from a deployed Lambda or Task. The userId is the one the user’s chat token was minted with; disconnection does not prevent reconnection, so revoke by not minting further tokens. The call succeeds even when the user has no open connections.

DisconnectUser: Moderating Users

Provide the DisconnectUserHttp implementation layer on the Function effect, bind the room in the init phase, then call the returned client at runtime. The binding grants ivschat:DisconnectUser on the room and injects its ARN as the roomIdentifier automatically.

// init
const room = yield* IVSChat.Room("LiveChat");
const disconnectUser = yield* IVSChat.DisconnectUser(room);

return {
  fetch: Effect.gen(function* () {
    // runtime
    yield* disconnectUser({ userId: "user-123", reason: "spam" });
    return HttpServerResponse.json({ ok: true });
  }),
};
// on the Function effect:
// .pipe(Effect.provide(IVSChat.DisconnectUserHttp))

LoggingConfiguration

Source: src/AWS/IVSChat/LoggingConfiguration.ts

An Amazon IVS Chat logging configuration — records the chat messages of the rooms it is attached to into S3, CloudWatch Logs, or a Kinesis Data Firehose delivery stream.

LoggingConfiguration: Creating Logging Configurations

CloudWatch Logs Destination

import * as IVSChat from "alchemy/AWS/IVSChat";
import * as Logs from "alchemy/AWS/Logs";

const logGroup = yield* Logs.LogGroup("ChatLogGroup");
const logging = yield* IVSChat.LoggingConfiguration("ChatLogs", {
  destinationConfiguration: {
    cloudWatchLogs: { logGroupName: logGroup.logGroupName },
  },
});

S3 Destination

const logging = yield* IVSChat.LoggingConfiguration("ChatLogs", {
  destinationConfiguration: {
    s3: { bucketName: bucket.bucketName },
  },
});

LoggingConfiguration: Attaching to Rooms

const room = yield* IVSChat.Room("LiveChat", {
  loggingConfigurationIdentifiers: [logging.loggingConfigurationArn],
});

Room

Source: src/AWS/IVSChat/Room.ts

An Amazon IVS Chat room — a virtual space where chat participants exchange messages over WebSocket connections.

Clients connect with chat tokens minted at runtime via CreateChatToken; message rate/length limits, a Lambda review handler, and logging configurations are all managed on the room.

Room: Creating Rooms

Basic Room

import * as IVSChat from "alchemy/AWS/IVSChat";

const room = yield* IVSChat.Room("LiveChat");

Room with Message Limits

const room = yield* IVSChat.Room("LiveChat", {
  maximumMessageRatePerSecond: 5,
  maximumMessageLength: 200,
});

Room: Logging

const logging = yield* IVSChat.LoggingConfiguration("ChatLogs", {
  destinationConfiguration: {
    cloudWatchLogs: { logGroupName: logGroup.logGroupName },
  },
});
const room = yield* IVSChat.Room("LiveChat", {
  loggingConfigurationIdentifiers: [logging.loggingConfigurationArn],
});

Room: Message Review

// inside a Lambda Function's effect — the handler reviews every message
// sent to the room before delivery (allow / modify / deny)
const room = yield* IVSChat.Room("LiveChat");
yield* IVSChat.onReviewMessage(room, (event) =>
  Effect.succeed(
    event.Content.includes("banned-word")
      ? { ReviewResult: "DENY", Attributes: { Reason: "moderated" } }
      : undefined,
  ),
);
// on the Function effect:
// .pipe(Effect.provide(Lambda.RoomMessageReviewEventSource))

RoomMessageReviewEventSource

Source: src/AWS/IVSChat/RoomMessageReviewEventSource.ts

Event source connecting an IVS Chat Room’s message review handler to the hosting Lambda function — every message sent to the room is synchronously reviewed (allow / modify / deny) by the handler before delivery.

At deploy time the Lambda implementation (Lambda.RoomMessageReviewEventSource) injects the function ARN into the room’s messageReviewHandler (via the room’s binding contract) and creates the lambda:InvokeFunction Permission for ivschat.amazonaws.com; at runtime it dispatches review invocations for the bound room to the handler and returns the verdict to IVS Chat.

Use the onReviewMessage helper rather than the service directly, and provide Lambda.RoomMessageReviewEventSource on the hosting function.

RoomMessageReviewEventSource: Reviewing Messages

export default ChatFunction.make(
  { main: import.meta.url },
  Effect.gen(function* () {
    const room = yield* IVSChat.Room("LiveChat");

    // deploy: sets the room's messageReviewHandler + invoke Permission
    // runtime: reviews every message sent to the room
    yield* IVSChat.onReviewMessage(room, (event) =>
      Effect.succeed(
        event.Content.includes("banned-word")
          ? { ReviewResult: "DENY", Attributes: { Reason: "moderated" } }
          : { ReviewResult: "ALLOW", Content: event.Content.trim() },
      ),
    );

    return {};
  }).pipe(Effect.provide(Lambda.RoomMessageReviewEventSource)),
);

SendEvent

Source: src/AWS/IVSChat/SendEvent.ts

Send an application-defined event to every client connected to the bound room — the effectful call made from a deployed Lambda or Task. Use it to broadcast state changes (poll results, stream metadata, moderation notices) alongside user chat messages; attributes carries the payload as string key-value pairs.

SendEvent: Broadcasting Events

Provide the SendEventHttp implementation layer on the Function effect, bind the room in the init phase, then call the returned client at runtime. The binding grants ivschat:SendEvent on the room and injects its ARN as the roomIdentifier automatically.

// init
const room = yield* IVSChat.Room("LiveChat");
const sendEvent = yield* IVSChat.SendEvent(room);

return {
  fetch: Effect.gen(function* () {
    // runtime
    const { id } = yield* sendEvent({
      eventName: "app:poll-result",
      attributes: { question: "q1", winner: "option-b" },
    });
    return HttpServerResponse.json({ id });
  }),
};
// on the Function effect:
// .pipe(Effect.provide(IVSChat.SendEventHttp))