# Manage chat rooms (/en/realtime-media/im/build/build-groups-rooms-and-threads/chat-room/manage-chatrooms/ios)
> 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-1]
The Chat SDK provides the `IAgoraChatroomManager`, `AgoraChatroomManagerDelegate`, and `AgoraChatRoom` classes for chat room management, which allows you to implement the following features:
## Prerequisites [#prerequisites-1]
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-1]
This section introduces how to call the APIs provided by the Chat SDK to implement the features listed above.
### Create and destroy a chat room [#create-and-destroy-a-chat-room-1]
The [app super admin](..//en/api-reference/api-ref/im/chatroom-management/manage-chatroom-admins) can create a chat room and set the chat room attributes such as the chat room subject, description, and the maximum number of members. Once a chat room is created, the super admin automatically becomes the chat room owner.
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.
Only the chat room owner can disband a chat room. Once a chat room is disbanded, all the chat room members receive the `didDismissFromChatroom` callback and are immediately removed from the chat room.
```objc
// The super admin can call createChatroomWithSubject to create a chat room.
AgoraChatError *error = nil;
AgoraChatroom *retChatroom = [[AgoraChatClient sharedClient].roomManager createChatroomWithSubject:@"aSubject" description:@"aDescription" invitees:@[@"user1",@"user2"]message:@"aMessage" maxMembersCount:aMaxMembersCount error:&error];
// The chat room owner can call destroyChatroom to disband a chat room.
AgoraChatError *error = nil;
[[AgoraChatClient sharedClient].roomManager destroyChatroom:self.chatroom.chatroomId error:&error];
```
### Join and leave a chat room [#join-and-leave-a-chat-room-1]
All chat users can call `joinChatroom` to join the specified chat room. Once a chat user joins a chat room, all the other chat room members receive the `userDidJoinChatroom` callback.
All chat room members can call `leaveChatroom` to leave the specified chat room. Once a chat room member leaves a chat room, all the other members receive the `userDidLeaveChatroom` callback and all the local data is deleted by default. To retain data on the local device, set the `isDeleteMessagesWhenExitChatRoom` parameter of `AgoraChatOptions` to `NO`.
```objc
// All chat users can call joinChatroom to join the specified chat room.
AgoraChatError *error = nil;
[[AgoraChatClient sharedClient].roomManager joinChatroom:@"aChatroomId" error:&error];
// All chat room members can call leaveChatroom to leave the specified chat room.
AgoraChatError *error = nil;
[[AgoraChatClient sharedClient].roomManager leaveChatroom:@"aChatroomId" error:&error];
```
### Retrieve the chat room list and attributes [#retrieve-the-chat-room-list-and-attributes-1]
All chat users can get the chat room list from the server and retrieve the basic information of the specified chat room using the chat room ID.
```objc
// Chat room members can call getChatroomsFromServerWithPage to retrieve the specified number of chat rooms from the server by page. The maximum value of pageSize is 1,000.
AgoraChatError *error = nil;
[[AgoraChatClient sharedClient].roomManager getChatroomsFromServerWithPage:1 pageSize:50 error:&error];
// Chat room members can call chatroomWithId to get the basic information of the specified chat room by passing the chat room ID.
AgoraChatroom *chatRoom = [AgoraChatroom chatroomWithId:@"chatroomId"];
```
### Listen for chat room events [#listen-for-chat-room-events-1]
To monitor the chat room events, you can listen for the callbacks in the `ChatRoomManager` 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.
```objc
// Listen for the callback.
[[AgoraChatClient sharedClient].roomManager addDelegate:self delegateQueue:nil];
// Stop listening for the callback.
[[AgoraChatClient sharedClient].roomManager removeDelegate:self];
```
```objc
/**
* Occurs when a user joins a chat room.
* @param aChatroom The chat room ID
* @param aUsername The username of the new chat room member
*/
- (void)userDidJoinChatroom:(AgoraChatroom *)aChatroom
user:(NSString *)aUsername{
}
/**
* Occurs when a member leaves a chat room.
* @param aChatroom The chat room ID
* @param aUsername The username of the member that leaves the chat room
*/
- (void)userDidLeaveChatroom:(AgoraChatroom *)aChatroom
user:(NSString *)aUsername {
}
/**
* Occurs when a member is removed from a chat room.
* @param aChatroom The chat room ID
* @param aReason The reason why this member is removed
*/
- (void)didDismissFromChatroom:(AgoraChatroom *)aChatroom
reason:(AgoraChatroomBeKickedReason)aReason {
}
/**
* Occurs when one or more members are added to the chat room mute list. The muted members receive this event.
* Available since SDK v1.4.0.
* @param aChatroom The chat room ID
* @param aMutes A dictionary that maps each muted member's user ID to their mute expiration timestamp (a Unix timestamp in milliseconds)
*/
- (void)chatroomMuteListDidUpdate:(AgoraChatroom *)aChatroom
addedMutedMembers:(NSDictionary *)aMutes {
}
/**
* Occurs when a member is added to the chat room mute list.
* Deprecated since SDK v1.4.0. Use chatroomMuteListDidUpdate:addedMutedMembers: instead.
* @param aChatroom The chat room ID
* @param aMutedMembers The username of the member added to the mute list
* @param aMuteExpire The Unix timestamp when the mute expires
*/
- (void)chatroomMuteListDidUpdate:(AgoraChatroom *)aChatroom
addedMutedMembers:(NSArray *)aMutes
muteExpire:(NSInteger)aMuteExpire {
}
/**
* Occurs when a member is removed from the chat room mute list.
* @param aChatroom The chat room ID
* @param aMutedMembers The username of the member removed from the mute list
*/
- (void)chatroomMuteListDidUpdate:(AgoraChatroom *)aChatroom
removedMutedMembers:(NSArray *)aMutes {
}
/**
* Occurs when a member is added to the chat room admin list.
* @param aChatroom The chat room ID
* @param aAdmin The username of the member added to the admin list
*/
- (void)chatroomAdminListDidUpdate:(AgoraChatroom *)aChatroom
addedAdmin:(NSString *)aAdmin {
}
/**
* Occurs when a member is removed from the chat room admin list.
* @param aChatroom The chat room ID
* @param aAdmin The username of the admin removed from the admin list
*/
- (void)chatroomAdminListDidUpdate:(AgoraChatroom *)aChatroom
removedAdmin:(NSString *)aAdmin {
}
/**
* Occurs when the chat room owner is changed.
* @param aChatroom The chat room ID.
* @param aNewOwner The username of the new chat room owner.
* @param aOldOwner The username of the original chat room owner.
*/
- (void)chatroomOwnerDidUpdate:(AgoraChatroom *)aChatroom
newOwner:(NSString *)aNewOwner
oldOwner:(NSString *)aOldOwner {
}
// Occurs when basic information of the chat room is changed.
- (void)chatroomSpecificationDidUpdate:(EMChatroom *)aChatroom {
}
/**
* When custom chat room attributes are set or changed, all room members receives this callback.
* @param roomId The chat room ID.
* @param attributeMap The newly set or changed custom attributes.
*/
- (void)chatroomAttributesDidUpdated:(NSString *_Nonnull)roomId
attributeMap:(NSDictionary *_Nullable)attributeMap
from:(NSString *_Nonnull)fromId;
}
/**
* When custom chat room attributes are removed, all room members receives this callback.
* @param roomId The chat room ID.
* @param attributes The removed custom attributes.
*/
- (void)chatroomAttributesDidRemoved:(NSString *Nonnull)roomId
attributes:(NSArray *_Nullable)attributes
from:(NSString *_Nonnull)fromId;
// Occurs when basic information of the chat room is changed.
- (void)chatroomSpecificationDidUpdate:(EMChatroom *)aChatroom {
}
/**
* When custom chat room attributes are set or changed, all room members receives this callback.
* @param roomId The chat room ID.
* @param attributeMap The newly set or changed custom attributes.
*/
- (void)chatroomAttributesDidUpdated:(NSString *_Nonnull)roomId attributeMap:(NSDictionary *_Nullable)attributeMap from:(NSString *_Nonnull)fromId {
}
/**
* When custom chat room attributes are removed, all room members receives this callback.
* @param roomId The chat room ID.
* @param attributes The removed custom attributes.
*/
- (void)chatroomAttributesDidRemoved:(NSString *_Nonnull)roomId attributes:(NSArray *_Nullable)attributes from:(NSString *_Nonnull)fromId {
}
```
### Update the chat room member count in real time [#update-the-chat-room-member-count-in-real-time-1]
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 `userDidJoinChatroom:user:` event. When a member leaves or is removed from a chat room, other members in the chat room receive the `userDidLeaveChatroom:user:` event.
2. After the event is received, you can call the `occupantsCount` method to get the current number of members in the chat room.
```objc
extension ViewController: AgoraChatroomManagerDelegate {
func userDidJoin(_ aChatroom: AgoraChatroom, user aUsername: String) {
let memberCount = aChatroom.occupantsCount
}
func userDidLeave(_ aChatroom: AgoraChatroom, user aUsername: String) {
let memberCount = aChatroom.occupantsCount
}
}
AgoraChatClient.shared().roomManager?.add(self, delegateQueue: nil)
```