# Manage chat rooms (/en/realtime-media/im/build/build-groups-rooms-and-threads/chat-room/manage-chatrooms/flutter)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Chat rooms enable real-time messaging among multiple users.

    A chat room does not have a strict membership, and members do not retain any permanent relationship with each other. Once going offline, chat room members cannot receive any messages from the chat room and automatically leave the chat room after 2 minutes (members on the chat room allow list remain in the chat room even if they stay offline for 2 minutes or more). A chat room is widely applied in live broadcast use cases such as stream chat in Twitch.

    This page shows how to use the Chat SDK to create and manage a chat room in your app.

    ## Understand the tech [#understand-the-tech-2]

    The Chat SDK provides the `ChatRoom`, `ChatRoomManager`, and `ChatRoomEventHandler` classes for chat room management, which allows you to implement the following features:

    ## Prerequisites [#prerequisites-2]

    Before proceeding, ensure that you meet the following requirements:

    * You have initialized the Chat SDK. For details, see [SDK quickstart](../../../get-started-sdk).
    * You understand the call frequency limit of the Chat APIs supported by different pricing plans as described in [Limitations](../../limitations).
    * You understand the number of chat rooms supported by different pricing plans as described in [Pricing Plan Details](../../../reference/pricing-plan-details).
    * Only the app super admin has the privilege of creating a chat room. Ensure that you have added an app super admin by calling the [super-admin RESTful API](..//en/api-reference/api-ref/im/chatroom-management/manage-chatroom-admins#adding-a-chat-room-super-admin).

    ## Implementation [#implementation-2]

    This section introduces how to call the APIs provided by the Chat SDK to implement the features listed above.

    ### Create a chat room [#create-a-chat-room]

    Only the [app super admin](..//en/api-reference/api-ref/im/chatroom-management/manage-chatroom-admins#adding-a-chat-room-super-admin) can call `createChatRoom` to create a chat room and set the chat room attributes such as the chat room name, description, and maximum number of members. Once a chat room is created, the super admin automatically becomes the chat room owner.

    <CalloutContainer type="info">
      <CalloutDescription>
        You are advised to call the [RESTful API](/en/api-reference/api-ref/im/chatroom-management/manage-chatrooms#creating-a-chat-room) to create a chat room from the server.
      </CalloutDescription>
    </CalloutContainer>

    The following code sample shows how to create a chat room:

    ```dart
    try {
      ChatRoom room = await ChatClient.getInstance.chatRoomManager.createChatRoom(name);
    } on ChatError catch (e) {
    }
    ```

    ### Destroy a chat room [#destroy-a-chat-room]

    Only the chat room owner can call `destroyChatRoom` to disband a chat room. Once a chat room is disbanded, all chat room members receive the `ChatRoomEventHandler#onChatRoomDestroyed` callback and are immediately removed from the chat room.

    The following code sample shows how to destroy a chat room:

    ```dart
    try {
      await ChatClient.getInstance.chatRoomManager.destroyChatRoom(roomId);
    } on ChatError catch (e) {
    }
    ```

    ### Join a chat room [#join-a-chat-room]

    Refer to the following steps to join a chat room:

    1. Call [`fetchPublicChatRoomsFromServer`](#retrieve-the-chat-room-list-from-the-server) to retrieve the list of chat rooms from the server and locate the ID of the chat room that you want to join.

    2. Call `joinChatRoom` to pass in the chat room ID and join the specified chat room. Once a user joins a chat room, all the other chat room members receive the `ChatRoomEventHandler#onMemberJoinedFromChatRoom` callback.

    #### Basic chat room joining [#basic-chat-room-joining]

    The following code sample shows how to join a chat room:

    ```dart
    try {
       await ChatClient.getInstance.chatRoomManager.joinChatRoom(roomId);
    } on ChatError catch (e) {
    }
    ```

    #### Advanced chat room joining with extended information [#advanced-chat-room-joining-with-extended-information]

    Call the `ChatRoomManager#joinChatRoom(String, bool, String)` method to set extended information when joining a chat room and specify whether to exit all other chat rooms. Other members in the chat room receive the `ChatRoomEventHandler.onMemberJoinedFromChatRoom(String roomId, String participant, String? ext)` callback with the extended information.

    ```dart
    ChatClient.getInstance.chatRoomManager.joinChatRoom(
     "roomId",
     leaveOtherRooms: false,
     ext: 'ext',
    );

    // Add chat room event listener
    ChatClient.getInstance.chatRoomManager.addEventHandler(
     "identifier",
     ChatRoomEventHandler(
       onMemberJoinedFromChatRoom: (roomId, participant, ext) {
         // Handle member joined event with extended information
       },
     ),
    );

    // Remove chat room event listener
    ChatClient.getInstance.chatRoomManager.removeEventHandler("identifier");
    ```

    When a user joins a chat room with extended information, other members in the chat room can access this extended information through the `ext` parameter in the `onMemberJoinedFromChatRoom` callback.

    ### Leave a chat room [#leave-a-chat-room]

    All chat room members can call `leaveChatRoom` to leave the specified chat room. Once a member leaves the chat room, all the other chat room members receive the `ChatRoomEventHandler#onMemberExitedFromChatRoom` callback.

    <CalloutContainer type="info">
      <CalloutDescription>
        Unlike chat group owners (who cannot leave their groups), a chat room owner can leave a chat room. After re-entering the chat room, this user remains the chat room owner.
      </CalloutDescription>
    </CalloutContainer>

    The following code sample shows how to leave a chat room:

    ```dart
    try {
       await ChatClient.getInstance.chatRoomManager.leaveChatRoom(roomId);
    } on ChatError catch (e) {
    }
    ```

    By default, after a user leaves a chat room, the Chat SDK removes all chat room messages on the local device. If you do not want these messages removed, set `ChatOptions#deleteMessagesAsExitChatRoom` to `false` when initializing the SDK.

    The following code sample shows how to retain the chat room messages after leaving a chat room:

    ```dart
    ChatOptions options = ChatOptions(
          appKey: "",
          deleteMessagesAsExitChatRoom: false,
        );
    ```

    ### Retrieve the chat room attributes [#retrieve-the-chat-room-attributes]

    All chat room members can call `fetchChatRoomInfoFromServer` to retrieve the attributes of the a chat room, including the chat room ID, name, description, announcements, owner, admin list, maximum number of members, and whether all members are muted.

    The following code sample shows how to retrieve the chat room attributes:

    ```dart
    try {
      ChatRoom room = await ChatClient.getInstance.chatRoomManager.fetchChatRoomInfoFromServer(roomId);
    } on ChatError catch (e) {
    }
    ```

    ### Retrieve the chat room list from the server [#retrieve-the-chat-room-list-from-the-server]

    Users can call `fetchPublicChatRoomsFromServer` to retrieve the chat room list from the server.

    ```dart
    try {
      ChatPageResult result = await ChatClient
          .getInstance.chatRoomManager
          .fetchPublicChatRoomsFromServer(
        // The page number from which to start retrieving chat rooms.
        pageNum: pageNum,
        // The maximum number of chat rooms to retrieve with pagination.
        pageSize: pageSize,
      );
    } on ChatError catch (e) {
    }
    ```

    ### Listen for chat room events [#listen-for-chat-room-events-2]

    To monitor the chat room events, you can listen for the callbacks in the `ChatRoomEventHandler` class and add app logics accordingly. If you want to stop listening for the callback, make sure that you remove the listener to prevent memory leakage.

    The following code sample shows how to add and remove the chat room listener:

    ```dart
        /// Add a chat room event listener.
        ChatClient.getInstance.chatRoomManager.addEventHandler(
           'UNIQUE_HANDLER_ID',,
           ChatRoomEventHandler(),
            /// Occurs when a member is added to the chat room admin list.
            onAdminAddedFromChatRoom: (roomId, admin) {},

            /// Occurs when a member is removed from the chat room admin list.
            onAdminRemovedFromChatRoom: (roomId, admin) {},

            /// Occurs when the state of muting all the chat room members changes.
            onAllChatRoomMemberMuteStateChanged: (roomId, isAllMuted) {},

            /// Occurs when a member is added to the chat room allow list.
            onAllowListAddedFromChatRoom: (roomId, members) {},

            /// Occurs when a member is removed from the chat room allow list.
            onAllowListRemovedFromChatRoom: (roomId, members) {},

            /// Occurs when the chat room announcement is changed.
            onAnnouncementChangedFromChatRoom: (roomId, announcement) {},

            /// Occurs when custom chat room attributes are removed.
            onAttributesRemoved: (roomId, removedKeys, from) {},

            /// Occurs when custom chat room attributes are changed.
            onAttributesUpdated: (roomId, attributes, from) {},

            /// Occurs when the chat room instance is destroyed.
            onChatRoomDestroyed: (roomId, roomName) {},

            /// Occurs when a member leaves the chat room.
            onMemberExitedFromChatRoom: (roomId, roomName, participant) {},

            /// Occurs when a new member joins the chat room.
            onMemberJoinedFromChatRoom: (roomId, participant) {},

            /// Occurs when one or more members are added to the chat room mute list. The muted members receive this event.
            /// Since SDK v1.4.0, mutes is a Map<String, int> of each muted member's user ID to their mute expiration timestamp (a Unix timestamp in milliseconds).
            onMuteListAddedFromChatRoom: (roomId, mutes) {},

            /// Occurs when a member is removed from the chat room mute list.
            onMuteListRemovedFromChatRoom: (roomId, mutes) {},

            /// Occurs when the chat room ownership is transferred.
            onOwnerChangedFromChatRoom: (roomId, newOwner, oldOwner) {},

            ///Occurs when a chat room member is removed.
            onRemovedFromChatRoom: (roomId, roomName, participant, reason) {},

            /// Occurs when the specifications of a chat room is changed.
            onSpecificationChanged: (room) {},
          ),
        );
    // ...
    /// Remove a chat room event listener.
    ChatClient.getInstance.chatRoomManager.removeEventHandler('UNIQUE_HANDLER_ID');
    ```

    ### Update the chat room member count in real time [#update-the-chat-room-member-count-in-real-time-2]

    If many members join or leave a chat room in a very short time, you can update the chat room member count in real time:

    1. When a user joins a chat room, other members in the chat room receive the `onMemberJoinedFromChatRoom` event. When a member leaves or is removed from a chat room, other members in the chat room receive the `onMemberExitedFromChatRoom` event.

    2. After the event is received, you can call the `getChatRoomWithId` method to get local details of the chat room, including the current number of members in the chat room.

       ```dart
       ChatClient.getInstance.chatRoomManager.addEventHandler(
           'UNIQUE_HANDLER_ID',
           ChatRoomEventHandler(
             onMemberJoinedFromChatRoom: (roomId, participant) async {
               ChatRoom? room = await ChatClient.getInstance.chatRoomManager.getChatRoomWithId(roomId);
               debugPrint("current room member count ${room?.memberCount}");
             },
             onMemberExitedFromChatRoom: (roomId, roomName, participant) async {
               ChatRoom? room = await ChatClient.getInstance.chatRoomManager.getChatRoomWithId(roomId);
               debugPrint("current room member count ${room?.memberCount}");
             },
           ));

       // ...
       ChatClient.getInstance.chatRoomManager.removeEventHandler('UNIQUE_HANDLER_ID');
       ```