- Documentation
- In-app Chat
- Guides
- Room
- Manage rooms
Manage rooms
ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of room messaging, allows multiple users to send text or custom messages to a room, and chat and share ideas in real time.
With the room messaging feature, you can build your app to meet different requirements of various scenarios, such as one-to-many classes, online conferences, and more.
Prerequisites
- Create a project in ZEGOCLOUD Console. Then, contact Technical Support to activate the In-app Chat service, and get the AppID and ServerSecret for SDK integration. The ZIM service permission is not enabled by default. Before using it, please activate the ZIM service by yourself in ZEGOCLOUD Console (for details, please refer to Project Management - In-app Chat), if you cannot activate the ZIM service, please contact ZEGOCLOUD technical support to activate it.
- Get the Token that SDK required for login authentication. For details, see Authentication.
- Integrate the ZIM SDK. For details, see the Integrate the SDK chapter of Send and receive messages.
Join a room
Now, we provide two methods to join a room:
Method 1: Manually create a room & Join a room : Call the
createRoom
method with theZIMRoomInfo
info to manually create a room first. And other client users call thejoinRoom
with the roomID to join the room.Method 2: Join a room directly (room will be created automatically): Call the
enterRoom
method withZIMRoomInfo
info to join a room directly (if the room doesn't exist, the room will be created automatically). Other client users can call theenterRoom
method with the roomID to join the room.
For in-room users to send messages to a room, call the sendRoomMessage
method. For details, see Send & Receive messages.
If the room (roomID) already exists:
- Call the
createRoom
method: returns an error code. For details, see Error codes. - Call the
enterRoom
method: you will join the room directly.
If the room (roomID) doesn't exist:
- Call the
createRoom
method: you can create a room, and you will join the room upon creation. - Call the
enterRoom
method: a room will be created automatically, and you will join the room directly.
Method 1: Manually create a room & Join a room
Manually create a room
Let's suppose we have Client A and Client B. The following shows how Client A creates a room, how Client B and other client users join the room.
For Client A to create a room after login, he can call the createRoom
method with the ZIMRoomInfo
info. And he can be told whether the room is created successfully by the ZIMErrorCode
parameter. For related error codes, see Error codes.
- You can customize the roomID and roomName, and we recommend you set the roomID to a meaningful value and associate them with the account system of your application.
- After creating a room by calling the
createRoom
method, you will directly join the room you just created, you don't need to call thejoinRoom
method to join the room.
// Set the room configurations.
ZIMRoomInfo *roomInfo = [[ZIMRoomInfo alloc]init];
roomInfo.roomID = @"" ;
roomInfo.roomName = @"" ;
//Creates a room.
[zim createRoom:roomInfo callback:^(ZIMRoomFullInfo * _Nonnull roomInfo, ZIMError * _Nonnull errorInfo) {
//Implement the event callback for creating a room here.
}];
Join a room
For Client B and other client users to join the room created by Client A, call the joinRoom
method with the roomID of client A's room. And Client B and other client users can be told whether they joined the room successfully by the ZIMErrorCode
parameter. For related error codes, see Error codes.
[zim joinRoom:RoomID callback:^(ZIMRoomFullInfo * _Nonnull roomInfo, ZIMError * _Nonnull errorInfo) {
//Implement the event callback for joining a room here.
}];
To receive notifications when a new room member joins the room, call the setEventHandler
method to set up the callback roomMemberJoined
.
The following shows Client A receives the callback notification when Client B joins the room created by Client A:
- (void)zim:(ZIM *)zim
roomMemberJoined:(NSArray<ZIMUserInfo *> *)memberList
roomID:(NSString *)roomID{
//Implement the event callback for new room members join the room.
}
Method 2: Join a room directly (room will be created automatically)
Let's suppose we have Client A and Client B. The following shows how Client A joins the room without creating a room manually, and how Client B and other client users join the room.
After logs in, Client A calls the
enterRoom
method with theZIMRoomInfo
information. The room will be created automatically when the passed roomID doesn't exist.Client B and other client users call the
enterRoom
method with the roomID to join the room created by Client A.For in-room client users to receive notifications when a new room member joins the room, call the
setEventHandler
method to set up the callbackroomMemberJoined
.
// Set up the configuration of a room.
ZIMRoomInfo *roomInfo = [[ZIMRoomInfo alloc]init];
roomInfo.roomID = @"" ;
roomInfo.roomName = @"" ;
ZIMRoomAdvancedConfig *config = [[ZIMRoomAdvancedConfig alloc] init];
//Join a room directly.
[zim enterRoom:roomInfo config:config callback:^(ZIMRoomFullInfo * _Nonnull roomInfo, ZIMError * _Nonnull errorInfo) {
//Implement the event callback for join a room.
}];
Leave a room
For Client B to leave the room, call the leaveRoom
method with roomID
.
And Client A and other client users in the room will receive notifications through the callback roomMemberLeft
of the setEventHandler
method.
Room members who leave the room cannot receive messages in the room anymore.
[zim leaveRoom:roomID callback:^(ZIMError * _Nonnull errorInfo) {
//Implement the event callback for exisiting users leave the room.
}];
- (void)zim:(ZIM *)zim
roomMemberLeft:(NSArray<ZIMUserInfo *> *)memberList
roomID:(NSString *)roomID{
//Fill in your custom code here when room members leave.
}
The room will be automatically destroyed after all room members left the room. You can also delay the destruction with the room settings.