Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

Manage chat rooms

Chat rooms enable real-time messaging among multiple users.

Chat rooms do 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. Chat rooms are 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

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

  • Create and destroy a chat room
  • Join and leave a chat room
  • Retrieve the chat room list from the server
  • Retrieve the attributes of a chat room
  • Listen for chat room events

Prerequisites

Before proceeding, ensure that you meet the following requirements:

  • You have initialized the Chat SDK. For details, see SDK quickstart.
  • You understand the call frequency limit of the Chat APIs supported by different pricing plans as described in Limitations.
  • You understand the number of chat rooms supported by different pricing plans as described in 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.

Implementation

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

The app super admin can call createChatRoom to create a chat room and set the chat room attributes such as the chat room subject, description, and the maximum number of members.


_7
// The app super admin calls createChatRoom to create a chat room.
_7
// Once the chat room is created, the super admin becomes the chat room owner.
_7
ChatRoom chatRoom = ChatClient.getInstance().chatroomManager().createChatRoom(subject, description, welcomMessage, maxUserCount, members);
_7
_7
// Only the chat room owner can call destroyChatRoom to disband the chat room.
_7
// Once the chat room is disbanded, all the chat room members receive the onChatRoomDestroyed callback and are immediately removed from the chat room.
_7
ChatClient.getInstance().chatroomManager().destroyChatRoom(chatRoomId);

Join and leave a chat room

All the chat users can all joinChatRoom to join the specified chat room.


_15
// Once the chat user successfully joins the chat room, all the other chat room members receive the onMemberJoined callback.
_15
ChatClient.getInstance().chatroomManager().joinChatRoom(chatRoomId, new ValueCallBack<ChatRoom>() {
_15
@Override
_15
public void onSuccess(ChatRoom value) {
_15
_15
}
_15
_15
@Override
_15
public void onError(int error, String errorMsg) {
_15
_15
}
_15
});
_15
_15
// All the chat room members can call leaveChatRoom to leave the specified chat room. Once a member leaves the chat room, all the other members receive the onMemberExited callback.
_15
ChatClient.getInstance().chatroomManager().leaveChatRoom(chatRoomId);

By default, when you leave a chat room, the SDK removes all the chat room messages on the local device. If you do not want these messages removed, set setDeleteMessagesAdExitChatRoom in ChatOptions as false.

Retrieve the chat room list and attributes

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.


_6
// Chat room members can call fetchPublicChatRoomsFromServer to get the specified number of chat rooms from the server. The maximum value of pageSize is 100.
_6
PageResult<ChatRoom> chatRooms = ChatClient.getInstance().chatroomManager().
_6
fetchPublicChatRoomsFromServer(pageNumber, pageSize);
_6
_6
// Chat room members can call fetchChatRoomFromServer to get the basic information of the specified chat room by passing the chat room ID.
_6
ChatRoom chatRoom = ChatClient.getInstance().chatroomManager().fetchChatRoomFromServer(chatRoomId);

Listen for chat room events

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.


_116
public interface ChatRoomChangeListener {
_116
/**
_116
* Occurs when the chat room instance is destroyed.
_116
*
_116
* @param roomId The chat room ID
_116
* @param roomName The chat room name
_116
*/
_116
void onChatRoomDestroyed(final String roomId, final String roomName);
_116
_116
/**
_116
* Occurs when a new member joins the chat room.
_116
*
_116
* @param roomId The chat room ID
_116
* @param participant The username of the new chat room member
_116
*/
_116
void onMemberJoined(final String roomId, final String participant);
_116
_116
/**
_116
* Occurs when a member leaves the chat room.
_116
*
_116
* @param roomId The chat room ID
_116
* @param roomName The chat room name
_116
* @param participant The username of the member that leaves the chat room
_116
*/
_116
void onMemberExited(final String roomId, final String roomName, final String participant);
_116
_116
/**
_116
* Occurs when a chat room member is removed.
_116
*
_116
* @param reason The reason why this member is removed, either being kicked by the chat room admin, or being offline due to network conditions
_116
* @param roomId The chat room ID
_116
* @param roomName The chat room name
_116
* @param participant The username of the member that is removed from the chat room
_116
*/
_116
void onRemovedFromChatRoom(final int reason, final String roomId, final String roomName, final String participant);
_116
_116
/**
_116
* Occurs when a member is added to the chat room mute list.
_116
*
_116
* @param chatRoomId The chat room ID
_116
* @param mutes The usernames of the members added to the chat room mute list
_116
* @param expireTime The Unix timestamp when the mute expires, in miliseconds
_116
*/
_116
void onMuteListAdded(final String chatRoomId, final List<String> mutes, final long expireTime);
_116
_116
/**
_116
* Occurs when a member is removed from the chat room mute list.
_116
*
_116
* @param chatRoomId The chat room ID
_116
* @param mutes The usernames of the members removed from the chat room mute list
_116
*/
_116
void onMuteListRemoved(final String chatRoomId, final List<String> mutes);
_116
_116
/**
_116
* Occurs when a member is added to the chat room allow list.
_116
*
_116
* @param chatRoomId The chat room ID
_116
* @param whitelist The usernmaes of the members added to the chat room allow list
_116
*/
_116
void onWhiteListAdded(final String chatRoomId, final List<String> whitelist);
_116
_116
/**
_116
* Occurs when a member is removed from the chat room allow list.
_116
*
_116
* @param chatRoomId The chat room ID
_116
* @param whitelist The usernames of the members removed from the chat room allow list
_116
*/
_116
void onWhiteListRemoved(final String chatRoomId, final List<String> whitelist);
_116
_116
/**
_116
* Occurs when the state of muting all the chat room members changes.
_116
*
_116
* @param chatRoomId The chat room ID
_116
* @param isMuted Whether all the chat room members are muted
_116
*/
_116
void onAllMemberMuteStateChanged(final String chatRoomId, final boolean isMuted);
_116
_116
/**
_116
* Occurs when a member is added to the chat room admin list.
_116
*
_116
* @param chatRoomId The chat room ID
_116
* @param admin The username of the chat room member added to the admin list
_116
*/
_116
void onAdminAdded(final String chatRoomId, final String admin);
_116
_116
/**
_116
* Occurs when a member is removed from the chat room admin list.
_116
*
_116
* @param chatRoomId The chat room ID
_116
* @param admin The username of the chat name member removed from the admin list
_116
*/
_116
void onAdminRemoved(final String chatRoomId, final String admin);
_116
_116
/**
_116
* Occurs when the chat room ownership is transferred.
_116
*
_116
* @param chatRoomId The chat room ID
_116
* @param newOwner The username of the new chat room owner
_116
* @param oldOwner The username of the original chat room owner
_116
*/
_116
void onOwnerChanged(final String chatRoomId, final String newOwner, final String oldOwner);
_116
_116
_116
/**
_116
* Occurs when the chat room announcements change.
_116
* @param chatRoomId The chat room ID
_116
* @param announcement The new chat room announcements
_116
*/
_116
void onAnnouncementChanged(String chatRoomId, String announcement);
_116
}
_116
_116
// Adds a chat room listener to monitor chat room callback events.
_116
ChatClient.getInstance().chatroomManager().addChatRoomChangeListener(chatRoomChangeListener);
_116
_116
// Removes the chat room listener.
_116
ChatClient.getInstance().chatroomManager().removeChatRoomListener(chatRoomChangeListener);

vundefined