logo
In-app Chat
SDK Error Codes
Powered Byspreading
On this page

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.

Join a room

Now, we provide two methods to join a room:

For in-room users to send messages to a room, call the sendRoomMessage method. For details, see Send & Receive messages.

Note

If the room (roomID) already exists:

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 ZIMError parameter. For related error codes, see Error codes.

Warning
  • 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 the joinRoom method to join the room.
Untitled
ZIMRoomInfo zimRoomInfo = new ZIMRoomInfo();
zimRoomInfo.roomID = roomID;
zimRoomInfo.roomName = roomName;
zim.createRoom(zimRoomInfo, new ZIMRoomCreatedCallback() {
    @Override
    public void onRoomCreated(ZIMRoomFullInfo zimRoomFullInfo, ZIMError error) {
        if (error.code == ZIMErrorCode.SUCCESS) {
            // Room created successfully.            
        } else {
            // Failed to create a room.        
        }                                
    }
});
1
Copied!

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 ZIMError parameter. For related error codes, see Error codes.

Untitled
zim.joinRoom(roomID, new ZIMRoomJoinedCallback() {
    @Override
    public void onRoomJoined(ZIMRoomFullInfo zimRoomFullInfo, ZIMError error) {
        if (error.code == ZIMErrorCode.SUCCESS) {
            // Room joined successfully.
        } else {
            // Failed to join the room.
        }     
    }
});
1
Copied!

To receive notifications when a new room member joins the room, call the setEventHandler method to set up the callback onRoomMemberJoined.

The following shows Client A receives the callback notification when Client B joins the room created by Client A:

Untitled
zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onRoomMemberJoined(ZIM zim, ArrayList<ZIMUserInfo> memberList, final String roomID) {
    // Implement the event callback for new room members join the room.    
    }
});
1
Copied!

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.

  1. After logs in, Client A calls the enterRoom method with the ZIMRoomInfo information. The room will be created automatically when the passed roomID doesn't exist.

  2. Client B and other client users call the enterRoom method with the roomID to join the room created by Client A.

  3. For in-room client users to receive notifications when a new room member joins the room, call the setEventHandler method to set up the callback onRoomMemberJoined.

Untitled
ZIMRoomInfo zimRoomInfo = new ZIMRoomInfo();
zimRoomInfo.roomID = roomID;
zimRoomInfo.roomName = roomName;

ZIMRoomAdvancedConfig config = new ZIMRoomAdvancedConfig();

zim.enterRoom(zimRoomInfo, config, new ZIMRoomEnteredCallback() {
    @Override
    public void onRoomEntered(ZIMRoomFullInfo zimRoomFullInfo, ZIMError error) {
        if (error.code == ZIMErrorCode.SUCCESS) {
            // Room joined successfully.            
        } else {
            // Failed to join the room.            
        }                                
    }
});
1
Copied!

Switch Rooms

If a user wants to switch from one room to another, the user can call the switchRoom method, passing in the ID of the original room (fromRoomID) and the information of the target room (toRoomInfo), which includes the room ID and room name. This will allow the user to switch rooms.

However, it is possible for the room switch to fail if the target room does not exist. To avoid this failure, you can also pass isCreateWhenRoomNotExisted as true (allowing ZIM to create a new room if the target room does not exist) and config (used to configure the new room) when calling the switchRoom method. In this case, when ZIM finds that the target room does not exist, it will create a new room based on toRoomInfo and config (if provided) for the switch.

After a successful room switch, other users in the original room can be notified of a user leaving the room through the onRoomMemberJoined callback, and other users in the target room can be notified of a user joining the room through the callback interface onRoomMemberLeft.

  • Please refer to the following flowchart for the complete process:

    %%{ init: { 'flowchart': { 'curve': 'stepAfter' } } }%% flowchart TD Start([Start]) --> A[User A calls switchRom to \nswitch from Room1 to Room2] A --> B[User A receives the onRoomStateChanged event \nindicating the user is connecting to Room2] B --> C{Is Room2 \navailable?} C -->|No| D{Is the number of rooms\nin the server at its limit?} C -->|Yes| E[Room switched successfully. \nRoom2 users receive the onRoomMemberJoined event] D -->|Yes| K[Room switch failed.\nUser A receives the onRoomStateChanged event \nindicating the failure to switch to Room2.] D -->|No| F{Is isCreateWhen\nRoomNotExisted \n true?} F -->|No| K F -->|Yes| G[Room2 is created. \nRoom switched successfully.\nRoom2's parameters align with \nthose provided in the switchRoom call.] G --> H[User A receives onRoomStateChanged event twice\nindicating the connection to Room2 and the disconnection from Room1] E --> H H --> I{Are there\nother members \nin Room1?} I -->|Yes| J[Room1 users receive onRoomMemberLeft event] I -->|No| L[Room1 is destroyed when \nthe destruction delay time is reached] J --> End([End]) L --> End K --> End

    As shown in the figure above, users will receive the onRoomStateChanged event multiple times when switching rooms. Based on the triggering timing, the relevant parameters in this event are as shown in the following table:

    Triggering Time
    roomID value
    state value
    event value
    Event Meaning
    After calling the switchRoom interface.Room2CONNECTINGACTIVE_SWITCHConnecting to Room2.
    After calling the switchRoom interface, when Room2 does not exist, in any of the following cases:
    • The number of rooms in the server has reached the limit.
    • The number of rooms in the server has not reached the limit, but the isCreateWhenRoomNoteExisted parameter is set to false when calling the switchRoom method.
    Room2DISCONNECTEDSWITCH_FAILEDFailed to switch because Room2 does not exist.
    In any of the following cases, the user will receive the event twice:
    • After calling the switchRoom interface, when Room2 exists.
    • After calling the switchRoom interface, when Room2 does not exist, the number of rooms in the server has not reached the limit, and the isCreateWhenRoomNoteExisted parameter is set to true when calling the switchRoom interface.
    • First time: Room2
    • Second time: Room1
    • First time: CONNECTED
    • Second time: DISCONNECTED
    • First time: SUCCESS
    • Second time: SUCCESS
    • First time: Successfully connected to Room2.
    • Second time: Successfully disconnected from Room1.
  • Sample code:

Untitled
String fromRoomID = "fromRoomID";
ZIMRoomInfo toRoomInfo = new ZIMRoomInfo();
roomInfo.roomID = "toRoomID";
roomInfo.roomName = "toRoomName";

// Whether to create a room if it does not exist.
// Only when this is true and the target room does not exist, the toRoomName and config in toRoomInfo are meaningful
boolean isCreateWhenRoomNotExisted = true;

// Advanced configuration for creating a room
ZIMRoomAdvancedConfig config = new ZIMRoomAdvancedConfig();
config.roomAttributes.put("key1", "value1");
config.roomDestroyDelayTime = 90;

// Switch rooms
zim.switchRoom(fromRoomID, toRoomInfo, isCreateWhenRoomNotExisted, config, new ZIMRoomSwitchedCallback() {
    @Override
    public void onRoomSwitched(ZIMRoomFullInfo roomInfo, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // Room switch successful, you can obtain information about the switched room from roomInfo
        }
    }
});
1
Copied!

Leave the 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 onRoomMemberLeft of the setEventHandler method.

Room members who leave the room cannot receive messages in the room anymore.

Untitled
zim.leaveRoom(roomID, new ZIMRoomLeftCallback() {
     @Override
     public void onRoomLeft(String roomID, ZIMError errorInfo) {
                
     }
});
1
Copied!
Untitled
zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onRoomMemberLeft(ZIM zim, ArrayList<ZIMUserInfo> memberList, final String roomID) {
    // Implement the event callback for exisiting users leave the room. 
    }
});
1
Copied!
Note

The room will be automatically destroyed after all room members left the room. You can also delay the destruction with the room settings.

Leave all rooms

Call the leaveAllRoom method to leave all joined rooms and obtain a list of the rooms. If a user logs in to multiple platforms, calling this method on a platform lets the user leave rooms on the that platform only. Other platforms are not affected.

Untitled
ZIM.getInstance().leaveAllRoom(new ZIMRoomAllLeftCallback() {
    @Override
    public void onRoomAllLeft(ArrayList<String> roomIDList, ZIMError errorInfo) {
        if(errorInfo.code == ZIMErrorCode.SUCCESS){
        // `roomIDList` contains the IDs of all rooms that the user have left from.
    }else{
        // Handle the error based on the corresponding error code table.
    }
}];
1
Copied!

Other users in the room receive the member change notification in the setEventHandler callback of the onRoomMemberLeft method.

After leaving all rooms, the user receives the onRoomStateChanged callback multiple times based on the number of rooms. The value of ZIMRoomState is DISCONNECTED , and the value of ZIMRoomEvent is SUCCESS .

After leaving a room, the user no longer receives messages in the room.

Previous

Online Status Subscription

Next

Manage room info