Instant Messaging
Android
Getting Started
Introduction
Overview
Benefits
Features
Features
Account Integration and Login
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Limits
Integration
Interface Overview
Integrate and Initialize SDK
Messaging
Basic Messaging
Message History
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
Push and Message Alert
Superteam
Chat Room
Moderation
Chat Extension
Miscellaneous Features
Best Practice
Traffic Control in Chat Rooms
Reference
API Reference
Status Codes

Chat Room

Update time: 2021/09/25 22:13:59

Read the Chat room FAQ before developing the chat room feature to get a general idea about the feature.

Overview of Chat Room Features

Chat room features:

  • If a user enters a chat room, the new connection must be created. If the user leaves or is removed from the chat room, the connection will be disabled. If the user is disconnected from a chat room, automatic re-connection will be executed. Developers need to monitor the connection status of a chat room to make the correct interface action.
  • The number of online members in a chat room is not limited.
  • A user is allowed to enter multiple chat rooms and create multiple connections.
  • Chat room does not support multi-terminal login. The current login will be invalidated if another login from a different terminal is successful.
  • After disconnecting from a chat room, the user will no longer receive messages related to the chat room from the server.
  • The chat room members include members and guests.
  • At present, server control supports simultaneous entry to up to 10 chat rooms, so when logging into the 11th room, the client will be kicked out from one of the 10 previous rooms.

Initialization and Clearup

To use chat room features, you must perform initialization by calling nim_chatroom::ChatRoom::Init() ,and perform cleanup by calling nim_chatroom::ChatRoom::Cleanup() before exiting the feature. The two operations must be used in pairs. Otherwise, exceptions may occur.

Notification of Chat Room Event

Login, logout, message reception, and other operations in the chat room are all notified to the caller by monitoring global events. You must monitor all chat room event notifications before calling a login operation. We recommend registering the callback function for event monitoring upon the completion of initialization.

Chat Room Login Event

After calling the chat room login interface, the developer is notified of the login progress and result. The login process features 5 steps: local service initialization, server connection, completion of server connection, login being authenticated, and the completion of login authentication. When login authentication is completed, you can get the information of the current chat room and your chat room member.

NIMChatRoomLoginStepEnumeration description

Enumeration Value Description
kNIMChatRoomLoginStepInit 1 Local service initialization
kNIMChatRoomLoginStepServerConnecting 2 Server connecting
kNIMChatRoomLoginStepServerConnectOver 3 End of server connection, connection result is error_code
kNIMChatRoomLoginStepRoomAuthing 4 Chat room in authentication
kNIMChatRoomLoginStepRoomAuthOver 5 End of chat room authentication, the result of which is shown in error_code. If the error_code is not 408, the developer needs to request the chat room login information again.
  • API prototype
static void RegEnterCb(const EnterCallback& cb, const std::string& json_extension = "");

  • Parameter Description
Parameter Description
cb Asynchronous callback notification
json_extension Extension field. Reserved
  • Example
//Monitor login event
nim_chatroom::ChatRoom::RegEnterCb([&](int64_t room_id, NIMChatRoomEnterStep step, int error_code,const ChatRoomInfo& info, const ChatRoomMemberInfo& member_info)
{
    if (step == NIMChatRoomEnterStep::kNIMChatRoomEnterStepRoomAuthOver && error_code == kNIMResSuccess)
    {
        //Successfully enter the chat room
    }
    if (error_code != kNIMResSuccess)
    {
         //Error occurs when entering the chat rooms
    }
});

//Cancel monitoring
nim_chatroom::ChatRoom::RegEnterCb(nullptr);

Leave Chat Room Event

Notification for leaving chat room. Other than being kicked out by other client, host and manager, notification for exiting a chat room will also appear when the chat room is closed or dismissed. After receiving the notification, the chat participant won't automatically reconnect with the chat room. Re-login requires getting the token again.

NIMChatRoomExitReasonEnumeration parameter description

Enumeration Value Description
kNIMChatRoomExitReasonExit 0 If you leave the chat room and want to rejoin the room, you must send a login request for another time.
kNIMChatRoomExitReasonRoomInvalid 1 The chat room has been dismissed, you must send a re-login request before you log in again
kNIMChatRoomExitReasonKickByManager 2 Kicked out by the manager, you must send a re-login request before you log in again
kNIMChatRoomExitReasonKickByMultiSpot 3 Removed due to multiple login attempts from different clients
kNIMChatRoomExitReasonIllegalState 4 Status exception of current link
kNIMChatRoomExitReasonBeBlacklisted 5 Blacklisted by the manager
  • API prototype
static void RegExitCb(const ExitCallback& cb, const std::string& json_extension = "");

  • Parameter Description
Parameter Description
cb Asynchronous callback notification
json_extension Extension field. Reserved
  • Example
void OnExitHandler(long roomId, ResponseCode errorCode, NIMChatRoomExitReason reason)
{
    ...
}
//Monitor event
nim_chatroom::ChatRoom::RegExitCb([&](::int64_t room_id, int error_code, NIMChatRoomExitReason reason)
{
    ...
});

//Cancel monitoring
nim_chatroom::ChatRoom::RegExitCb(nullptr);

Chat Room Connection Status Change Notification

Notify the developer of the connection status of the chat room when the room is disconnected due to network fluctuations. SDK monitors network status and automatically reconnects when possible.

NIMChatRoomLinkConditionEnumeration parameter description

Enumeration Value Description
kNIMChatRoomLinkConditionAlive 0 Normal connection
kNIMChatRoomLinkConditionDeadAndRetry 1 Connection failed, reconnecting
kNIMChatRoomLinkConditionDead 2 Developer needs to re-apply for chat room login information
  • API prototype
static void RegLinkConditionCb(const LinkConditionCallback& cb, const std::string& json_extension = "");

  • Parameter Description
Parameter Description
cb Asynchronous callback notification
json_extension Extension field. Reserved
  • Example
//Monitor event
nim_chatroom::ChatRoom::RegLinkConditionCb([&](::int64_t room_id, NIMChatRoomLinkCondition condition)
{
    ...
});

//Cancel monitoring
nim_chatroom::ChatRoom::RegLinkConditionCb(nullptr);

Receive Message Event

Received a chat room message, the content of which isChatRoomMessage. This notification event covers messages from multiple chat rooms,roomIdcan be used to distinguish between chat rooms. Local storage is not available for all chat room messages

NIMChatRoomMsgTypeEnumeration description

Enumeration Value Description
kNIMChatRoomMsgTypeText 0 Text message
kNIMChatRoomMsgTypeImage 1 Image message
kNIMChatRoomMsgTypeAudio 2 Audio message
kNIMChatRoomMsgTypeVideo 3 Video message
kNIMChatRoomMsgTypeLocation 4 Location message
kNIMChatRoomMsgTypeNotification 5 Activity room notification
kNIMChatRoomMsgTypeFile 6 File message
kNIMChatRoomMsgTypeTips 10 Reminder message
kNIMChatRoomMsgTypeRobot 11 Baud robot message
kNIMChatRoomMsgTypeCustom 100 Custom message
kNIMChatRoomMsgTypeUnknown 1000 Unknown type of message, it is the default value

ChatRoomMessageDescription of key parameters

Type Parameter Description
int64_t room_id_ ID of the chat room the message belongs to (filled out by server)
string from_id_ Message sender
int64_t timetag_ Timestamp of message sending (in milliseconds) (filled out by server)
NIMChatRoomClientType from_client_type_ Sender's client type, filled out by server, no operation required for sender
string from_nick_ Sender's nickname (filled out by server)
string from_avatar_ Sender's avatar (filled out by server)
string from_ext_ Sender's identity extension field (filled out by server)
NIMChatRoomMsgType msg_type_ Message type, seeNIMChatRoomMsgType for details
string msg_attach_ Message content, with a length limit of 2048, if it is agreed to be a json string, it must be an unformatted string that can be parsed as json. In addition to text messages, images, audios, videos, geographic locations, and custom messages also need to be json strings of the currently agreed format. This content is for transparent transmission and essentially the attachment content of theIMmessage. Refer to the corresponding message type in "sending message"
string client_msg_id_ Client message id, filled out by sender
ChatRoomMessageSetting msg_setting_ Message setting, seeChatRoomMessageSettingfor details
string local_res_path_ The local absolute path of the media file (client side) (not yet supported)
string local_res_id_ ID of local media file (client side) (not yet supported)

ChatRoomMessageSettingDescription of key message setting parameters

Type Parameter Description
bool resend_flag Whether resending message is needed, true: needed, false: not needed, the default is false (not yet supported)
string ext_ Third-party extension field, with a length limited to 4096, must be an unformatted string that can be parsed as Json
bool anti_spam_enable_ Whether checking by Yidun Anti-spam is needed, true: needed, false: not needed, the default is false, refer to anti-spam settings of IM messages
string anti_spam_content_ (Optional) Developer-defined anti-spam field, with a length limit of 5000 characters
bool history_save_ Whether to save message history on the cloud. By default, messages are saved on the cloud (not yet supported)
  • API prototype
static void RegReceiveMsgCb(const ReceiveMsgCallback& cb, const std::string& json_extension = "");

  • Parameter Description
Parameter Description
cb Asynchronous callback notification
json_extension Extension field. Reserved
  • Example
//Monitor event
nim_chatroom::ChatRoom::RegReceiveMsgCb([&](::int64_t room_id, const ChatRoomMessage& result)
{
	...
});

//Cancel monitoring
nim_chatroom::ChatRoom::RegReceiveMsgCb(nullptr);

Notification of Message Sending Result

This event informs the user whether the message is sent.

  • API prototype
static void RegSendMsgAckCb(const SendMsgAckCallback& cb, const std::string& json_extension = "");

  • Parameter Description
Parameter Description
cb Asynchronous callback notification
json_extension Extension field. Reserved
  • Example
//Monitor event
nim_chatroom::ChatRoom::RegSendMsgAckCb([&](::int64_t room_id, int error_code,const ChatRoomMessage& result)
{
    ...
});

//Cancel monitoring
nim_chatroom::ChatRoom::RegSendMsgAckCb(nullptr);

Event of Receiving Chat Room Notification

All notifications of a chat room are receive by the event. For example, join or leave a chat room; mute or unmute members;blacklist or unblacklist a member. SeeChatRoomNotificationfor details.

NIMChatRoomNotificationIdEnumeration description

Enumeration value Description
kNIMChatRoomNotificationIdMemberIn Members enter a chat room
kNIMChatRoomNotificationIdMemberExit Members exit from a chat room
kNIMChatRoomNotificationIdAddBlack Blacklist members
kNIMChatRoomNotificationIdRemoveBlack Unblacklist a member.
kNIMChatRoomNotificationIdAddMute Mute a member
kNIMChatRoomNotificationIdRemoveMute Unmute a member
kNIMChatRoomNotificationIdAddManager Designate a manager
kNIMChatRoomNotificationIdRemoveManager Undo the designation of a manager
kNIMChatRoomNotificationIdAddFixed Designate fixed chat room members
kNIMChatRoomNotificationIdRemoveFixed Undo the designation of fixed chat room members
kNIMChatRoomNotificationIdClosed Disable a chat room
kNIMChatRoomNotificationIdInfoUpdated Update the information of a chat room
kNIMChatRoomNotificationIdMemberKicked Kick a member out of a chat room
kNIMChatRoomNotificationIdMemberTempMute Temporary mute
kNIMChatRoomNotificationIdMemberTempUnMute Terminate temporary mute
kNIMChatRoomNotificationIdMyRoleUpdated Chat room members update personal information in the chat room. The information only includes nick, avator, and ext.
kNIMChatRoomNotificationIdRoomMuted : When a chat room is muted, only the manager can send messages.
kNIMChatRoomNotificationIdRoomDeMuted : Unmute all chat room members.

ChatRoomNotificationParameter description

Type Parameter Description
NIMChatRoomNotificationId id_ Notification type
string ext_ The notification extension field of events customized by top-level modules must be parsed as unformatted strings of Json.
string operator_id_ The account ID of the operator
string operator_nick_ The nickname of the operator
std::list< std::string > target_nick_ The nickname list of target members
std::list< std::string > target_ids_ The account ID list of operators
bool muted_ If according to notification type, this value is available upon member entry, then it indicates whether the member is muted, 1: muted, 0: not muted (default)
bool temp_muted_ If according to notification type, this value is available upon member speaking, then it indicates temporary mute status
int64_t temp_mute_duration_ If according to the notification, this value exists when there is temporary mute, then it is the (remaining, if unmute operation) duration of the mute (in seconds); if this value exists upon member entry, then it is the duration of temporary mute (seconds). Other notifications do not carry this data
string queue_change_ Except in notification of chat room queue change event, in which case it represents the changed content (not yet supported).
  • API prototype
 static void RegNotificationCb(const NotificationCallback& cb, const std::string& json_extension = "");
  • Example
//Monitor event
nim_chatroom::ChatRoom::RegNotificationCb([&](::int64_t room_id, const ChatRoomNotification& notification)
{
	...
});

//Cancel monitoring
nim_chatroom::ChatRoom::RegNotificationCb(nullptr);

Enter A Chat Room

Get Token

The chat room relies on IM. Before entering a chat room, you must get authorization information required for entering the room by calling the IM module interface, and this information is input into the chat room login when it is called by the developer. You can log in to multiple chat rooms at the same time, but each chat room requires different authorization information, depending on itsroomId.

Note: The interface called here belongs to IM SDK module.

  • API prototype
static void ChatRoomRequestEnterAsync(const int64_t room_id, const ChatRoomRequestEnterCallback &callback, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
callback Result notification callback
json_ext Extension information, reserved
  • API example
//Take test room 3001 as an example
int64_t roomId = 3001;
string _token = "";

nim::PluginIn::ChatRoomRequestEnterAsync(roomId, [&](int error_code, const std::string& result)
{
	if (error_code == kNIMResSuccess)
    {
    	_token = result; //This token is the required authorization information
        //nim_chatroom::ChatRoom::Enter, please try operating by throwing way an asynchronous task, the operations are shown as follows;
        scheduleOnce([&](float dt)
        {
        	ChatRoomEnterInfo loginData;
            loginData.SetNick("nickName");
            loginData.SetIcon("https://xxxx.png");//image url
            loginData.SetExt("{\"myExt\:\"111\"}");
            loginData.SetNotifyExt("{\"myNotifyExt\:\"2222\"}") ;
			nim_chatroom::ChatRoom::Enter(roomId,_token,loginData);
		});
    }
});

Log in to Chat Room

When entering the chat room, you can useChatRoomEnterInfoto set your nickname, avatar in the chat room, and deliver notification information and extension information, etc. The developer is informed of the login process through the log-in chat room event.

ChatRoomEnterInfoParameter description

Type Parameter Description
string SetNick Nickname displayed after entering the chat room, optionals
string SetIcon Avatar in the chat room, filled out with the url of the avatar, optional
string SetExt Extension field information, must be a json string, optional
string SetNotifyExt Notification extension field for chat room entry, must be a json string, optional
  • API prototype
static bool Enter(const int64_t room_id, const std::string& request_login_data, const ChatRoomEnterInfo& info = ChatRoomEnterInfo(), const std::string& json_extension = "");

  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
requestrequest_login_data Get the authorization information by the interface of Get the token. Required.
info Personal information attached upon chat room entry, optional
json_extension Extension information, reserved
  • Example

View sample code

Exit from Chat Room

When exiting from chat room, the user will disconnect with chat room and will not receive any message from the chat room. The user can leave a chat room by manually calling the exit chat room interface.

  • API prototype
static void Exit(const int64_t room_id, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
json_extension Extension information, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
nim_chatroom::ChatRoom::Exit(roomId);

Send Chat Room Message

First create the message content Message, then usenim_chatroom::ChatRoom::SendMsginterface to deliver the message sending result to the users. You can send various types of messages, including text, image, audio, video, geographic location and other custom messages. For specific message content, please refer to IM messaging. No local storage for message history record, you can query message history in the cloud.

Create Chat Room Message

  • API prototype
static std::string CreateRoomMessage(const NIMChatRoomMsgType msg_type, const std::string& client_msg_id, const std::string& attach, const std::string& msg_body, const ChatRoomMessageSetting& msg_setting, int64_t timetag = 0);

  • Parameter Description
Parameter Description
msg_type Message type)
client_msg_id Message id)
attach Message content, for details see the descriptionattachof ChatRoomMessage
msg_body Text message content (not supported for now)
msg_setting Message setting, seeChatRoomMessageSettingfor details
timetag Current UNIX timestamp, in milliseconds

Send Message

  • API prototype
static void SendMsg(const int64_t room_id, const std::string& json_msg, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
json_msg Message content See ChatRoomMessage for details, can be created by using the interface for creating chat room message
json_extension Extension information, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
//Message settings
ChatRoomMessageSetting setting;
setting.ext_ = "{\"ext\":\"Custom extension content\"}";
...

std::string msg = nim_chatroom::ChatRoom::CreateRoomMessage(kNIMChatRoomMsgTypeText,"unique uuid of message","This is a text message","",setting);
nim_chatroom::ChatRoom::SendMsg(roomId,msg);

Query Cloud-based Message History

SDK supports querying chat room message records stored in the cloud.

ChatRoomGetMsgHistoryParametersParameter description

Type Parameter Description
int64_t start_timetag_ Start time, in milliseconds
int limit_ The maximum number of query entries, must be greater than 0
bool reverse_ Is the query in reverse order
  • API prototype
static void GetMessageHistoryOnlineAsync(const int64_t room_id,	const ChatRoomGetMsgHistoryParameters &parameters,	const GetMsgHistoryCallback &callback,const std::string& json_extension = "");

  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
parameters Get parameters of chat room message history
callback Result callback notification
json_extension Extension information, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
ChatRoomGetMembersParameters params;
params.limit_ = 20;
params.startTimetag = 1520391909233;//13-bit timestamp (in milliseconds)
params.reverse_ = false;
nim_chatroom::ChatRoom::GetMessageHistoryOnlineAsync(roomId, params, [&](::int64_t room_id, int error_code, const std::list<ChatRoomMessage>& messages)
{
   ...
});

Chat Room Management

Get Chat Room Information

Chat room information is available through the event of entering chat room or separate interface. SDK doesn't provide local cache for chat room information. It only provide the interface for query from server, the use of which is subject to limitations on frequency of server interface usage.

ChatRoomInfoDescription of key parameters

Type Parameter Description
int64_t id_ Chat Room id, i.e. the room number
string name_ Chat room name, can be updated by manager
string announcement_ Chat room announcement
string broadcast_url_ Address of video live streaming
string creator_id_ Account id of Chat room creator
int valid_flag_ Chat room validity tag, 1: valid, 0: invalid
string ext_ Third-party extension field, must be an unformatted string that can be parsed as Json, with a length of 4000
int online_count_ Number of online members
bool mute_all_ Tag for chat room mute, 1: muted 0: not muted
  • API prototype
static void GetInfoAsync(const int64_t room_id,const GetChatRoomInfoCallback& callback,const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
callback Result callback notification
json_extension Extension information, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
nim_chatroom::ChatRoom::GetInfoAsync(roomId, [&](int64_t room_id, int error_code, const ChatRoomInfo& info)
{
	...
});

Update Chat Room Information

SDK supports updating chat room information, but it can only done by the manager. For now, only four attributes of ChatRoomInfo can be updated, namelyname_,announcement_,broadcast_url_,ext_ . You can determine whether chat room broadcast notification is needed for the update.

  • API prototype
static void UpdateRoomInfoAsync(const int64_t room_id, const ChatRoomInfo& info, bool need_notify, const std::string& notify_ext, const UpdateRoomInfoCallback& callback, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required
info Information of chat room update
need_notify Whether to enable chat room broadcast notification, true: enable, if sonotify_extcan’t be null, false: disable
notify_ext Custom field in the notification, with a length not exceeding 2048
callback Result callback notification
json_extension Extension information, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
ChatRoomInfo info;
info.id_ = roomId,
info.announcement = "Chat room announcement",
info.name_ = "newName",
info.broadcast_url_ = "http://xxxxx",
info.ext_ = "{\"test"\:\"1111\"}", //Custom extension string
nim_chatroom::ChatRoom::UpdateRoomInfoAsync(roomId, info,false,null,[&](::int64_t room_id, int error_code)
{
    ...
});

Get List of Chat Room Members

This interface can be used to get ChatRoomMessage information of fixed members, online only fixed members, and visitors, the extended field in which is filled out by the user when entering the chat room. There are four types of fixed members: creator, manager, normal user, and restricted user. Muted and blacklisted users are all restricted users. The member list information is not cached locally, and can be directly obtained from the cloud.

ChatRoomMemberInfoDescription of key parameters

Type Parameter Description
int64_t room_id_ Chat Room id, i.e. the room number
string account_id_ Member account
ChatRoomMemberType type_ Member type, -1: restricted user; 0: normal user; 1: creator; 2: manager, see ChatRoomMemberType for details
int level_ Member level: >=0, indicates the level can be customized by user/developer
string nick_ Chat room nickname field, can be submitted by the user upon entering the chat room
string avatar_ Chat room avatar, can be submitted by the user upon entering the chat room
string ext_ Third-party extension field, must be an unformatted string that can be parsed as Json, with a length of 4000
NIMChatRoomOnlineState state_ Whether the member is online, only special members can be offline, visitors/anonymous users can only be online, 0: offline 1: online
NIMChatRoomGuestFlag guest_flag_ Whether the user is an ordinary visitor, 0: no, 1: yes; the identity of a visitor is not persisted in the chat room, and would only be in memory when the user is online
int64_t enter_timetag_ The timestamp of chat room entry (in milliseconds), this field is null for offline members
bool is_blacklist_ Blacklisted? 1: Yes 0: No
bool is_muted_ Muted? 1: Yes 0: No
bool is_valid_ Valid? 1: Yes 0: No
bool temp_muted_ Temporarily muted? 1: Yes 0: No
int64_t temp_muted_duration_ Remaining time of temporary mute, in seconds
int64_t update_timetag_ Timestamp of updating fixed member history, used for sorting and query of fixed member list

NIMChatRoomGetMemberTypeEnumeration description

Enumeration Value Description
kNIMChatRoomGetMemberTypeSolid 0 Fixed members, fixed members, including creators, managers, normal users, restricted users (muted + blacklisted), even if they are not online, they are still in the list, but there is a limit on the number of fixed members
kNIMChatRoomGetMemberTypeTemp 1 Non-fixed members, non-fixed members, also known as temporary members, can only be seen in the list when they are online, and there is no limit on the number of these members

ChatRoomMemberTypeEnumeration description

Enumeration Value Description
Restricted -1 Restricted member
Normal 0 Normal members
Creator 1 Creator

ChatRoomGetMembersParametersParameter description

Type Parameter Description
NIMChatRoomGetMemberType type_ Member type, see NIMChatRoomGetMemberType for details
int64_t timestamp_offset_ Timestamp from current time
int limit_ The maximum number of query entries, must be greater than 0
  • API prototype
static void GetMembersOnlineAsync(const int64_t room_id,const ChatRoomGetMembersParameters &parameters,const GetMembersCallback& callback,const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
parameters Query parameter settings, see ChatRoomGetMembersParameters for details
callback Result callback notification
json_extension Extension information, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
ChatRoomGetMembersParameters params;
params.limit_ = 20;
params.timestamp_offset_ = 0;//Timestamp from the current time
params.type_ = kNIMChatRoomGetMemberTypeSolid;
nim_chatroom::ChatRoom::GetMembersOnlineAsync(roomId, params, [&](::int64_t room_id, int error_code, const std::list<ChatRoomMemberInfo>& infos)
{
    ...
});

Get Information of Specified Chat Room Member

This interface can be used to get member information ChatRoomMemberInfo of multiple specified accounts from the cloud.

  • API prototype
static void GetMemberInfoByIDsAsync(const int64_t room_id,const std::list<std::string>& ids,const GetMembersCallback& callback,const std::string& json_extension = "");

  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
ids Collection of member ids
callback Result callback notification
json_extension Extension information, reserved
  • Example
//Take chat room members test1, test2 in test room 3001 as an example
int64_t roomId = 3001;
std::list<string> ids;
ids.push_back("test1");
ids.push_back("test2");

nim_chatroom::ChatRoom::GetMemberInfoByIDsAsync(roomId,ids, [&](::int64_t room_id, int error_code, const std::list<ChatRoomMemberInfo>& infos)
{
	...
});

Update Personal Chat Room Information

Currently, you can only update your own chat room member information. Only nickname, avatar and extension field can be updated now. You can enable or disable notification of the update, if it is enabled, the users will be notified of the update through the event of receiving chat room notification.

  • API prototype
static void UpdateMyRoomRoleAsync(const int64_t room_id, const ChatRoomMemberInfo& info, bool need_notify, const std::string& notify_ext, const UpdateMyRoomRoleCallback& callback, const std::string& json_extension = "");

  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
info Member information, only update the fields that need to be modified, currently you can only update three attributes of ChatRoomMemberInfo ,which are Nick, MemberIconandExtension . See ChatRoomMemberInfo for details
callback Result callback notification
notify Whether to enable chat room broadcast notification, true: enable, if sonotify_extcan’t be null, false: disable
notify_ext Custom field in the notification, with a length not exceeding 2048
json_extension Reserved field
  • Example
//Take test room number 3001 as an example
int64_t roomId = 3001;
ChatRoomMemberInfo ri;
ri.room_id_ = roomId;
ri.avatar_ = "http://xxxx/newIcon.png";
ri.nick_ = "newNick";

nim_chatroom::ChatRoom::UpdateMyRoomRoleAsync(roomId,ri,false,null, [&](::int64_t room_id, int error_code)
{
	...
});

Chat Room Permission Management

Set Member ID Tag

When setting as manger or removing a manager, the users will be notified of the event through the event of receiving chat room notification. See description of notification type). If a visitor is set as a manager and then removed from the manager role, he will become a normal member but not a visitor.

NIMChatRoomMemberAttributeEnumeration description

Enumeration Value Description
kNIMChatRoomMemberAttributeAdminister 1 Manager (fixed member), only the creator has the permission to increase operation level
kNIMChatRoomMemberAttributeNomalSold 2 Normal member, the operator must be a creator or manager
kNIMChatRoomMemberAttributeBlackList -1 Blacklist member, the operator must be a creator or manager
kNIMChatRoomMemberAttributeMuteList -2 Permanently muted member, the operator must be a creator or manager

ChatRoomSetMemberAttributeParametersParameter description

Type Parameter Description
string account_id_ Member account id
NIMChatRoomMemberAttribute attribute_ Membership ID tag, see NIMChatRoomMemberAttribute for details
bool opt_ Set the corresponding membership ID tag, 1: set 0: cancel setting
int level_ User level, valid only when opt_= 1 or 2
string notify_ext_ Developer-customized extension field in the notification event generated by the operation, must be a json string
  • API prototype
static void SetMemberAttributeOnlineAsync(const int64_t room_id,const ChatRoomSetMemberAttributeParameters& parameters,const SetMemberAttributeCallback& callback,const std::string& json_extension = "");

  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
parameters Member attribute information, seeChatRoomSetMemberAttributeParametersfor details
callback Operation result callback
json_extension Reserved field
  • Example
//Take chat room member test1 in test room 3001 as an example
int64_t roomId = 3001;

// Confirm/Undo the designation of a manager.
ChatRoomSetMemberAttributeParameters ri;
ri.account_id_ = "test1",
ri.attribute_ = kNIMChatRoomMemberAttributeAdminister,
ri.opt_ = true,//set to false means to revoke the setting

nim_chatroom::ChatRoom::SetMemberAttributeOnlineAsync(roomId,ri,[&](::int64_t room_id, int error_code, const ChatRoomMemberInfo& info)
{
	...
});

// Confirm/revoke "permanent mute"
ChatRoomSetMemberAttributeParameters prop;
prop.account_id_ = "test1",
prop.attribute_ = kNIMChatRoomMemberAttributeMuteList,
prop.opt_ = true,//set to false means revoking the mute

nim_chatroom::ChatRoom::SetMemberAttributeOnlineAsync(roomId,prop, [&](::int64_t room_id, int error_code, const ChatRoomMemberInfo& info)
{
	...
});

Temporarily Mute Members

This interface provides the feature of temporarily muting members and revoking the mute. To permanently mute the user, set the user as a muted user by using the set member ID tag interface. The mute will be automatically revoked upon expiration of the mute duration. The duration in notification message after successfully setting temporary mute is remaining time of mute. If the mute duration is set to 0, it means to cancel temporary mute. If the first mute duration has not ended and the second temporary mute is set, then the time is counted by the second settings.

  • API prototype
static void TempMuteMemberAsync(const int64_t room_id, const std::string& accid, const int64_t duration, bool need_notify, const std::string& notify_ext, const TempMuteMemberCallback& callback, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
accid Member account, required)
duration Temporary mute duration (in seconds), set to 0 if the mute is released
callback Operation result callback
notify Enable broadcast notification in the chat room?
notify_ext Custom field in the notification, with a length not exceeding 2048, json string
json_extension Reserved field
  • Example
//For example, mute chat room member test1 in test room 3001 for 60s
int64_t roomId = 3001;
nim_chatroom::ChatRoom::TempMuteMemberAsync(roomId,"test1", 60,false,null,[&](::int64_t room_id, int error_code, const ChatRoomMemberInfo& info)
{
	...
});

Kick Online Members Out

Kick out member Only manager can kick out normal member, only creator can kick out manager. The extension field of kickout notification can be added. This field will be covered in extension field of kickout notification. The notification of chat room kick-out is sent to the developer through the Chat room notification event.

  • API prototype
static void KickMemberAsync(const int64_t room_id,const std::string& id,const std::string& notify_ext,const KickMemberCallback& callback,const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
id Member account)
notify_ext Extension field placed in the event notification
callback Operation result callback
json_extension Reserved field
  • Example
//Take chat room member test1 in test room 3001 as an example
int64_t roomId = 3001;
nim_chatroom::ChatRoom::KickMemberAsync(roomId,"test1","notify" ,[&](::int64_t room_id, int error_code)
{
	...
});

Chat Room Queue Service

Chat room provides a queue service for the scene of live streaming with mic link.

New (Updated) Quene Element of Mic Queue

Chat room queue service: add or update queue elements (only for chat room manager).When key doesn’t exist , calling this interface means adding a new element. If key exists,calling this interface means updating key in value.

ChatRoomQueueElementDescription of mic queue elements

Type Parameter Description
string key_ Unique key of the element, with a length not exceeding 128 bytes
string value_ Content of the element, with a length not exceeding 4096 bytes
  • API prototype
static void QueueOfferAsync(const int64_t room_id, const ChatRoomQueueElement& element, const QueueOfferCallback& callback, const std::string& json_extension = "");

  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required
element Data of mic queue elements
callback Operation result callback
json_extension Extension parameter, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
ChatRoomQueueElement element;
element.key_ = "key1";
element.value_ = "value1";
nim_chatroom::ChatRoom::QueueOfferAsync(roomId,element, [&](::int64_t room_id, int error_code)
{
	...
},null);

Take out Mic Queue Elements

element_keyis the unique key,ifelement_key is null, it means to take out the head element. If it is not null, it means to take out a specified element. After the operation, the key and value of the element can be obtained from the callback notificationresult.

  • API prototype
 static void QueuePollAsync(const int64_t room_id, const std::string& element_key, const QueuePollCallback& callback, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
element_key Unique key of the element, with a length not exceeding 128 bytes
callback Operation result callback
json_extension Extension parameter, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueuePollAsync(roomId,"key1", [&](::int64_t room_id, int error_code, const ChatRoomQueueElement& element)
{
    //result: json string of the queue element, as obtained, example {"key":"key1","value":"value1"}
	...
});

Get All Queue Elements

Lists all the queue elements in order, and returns the json array of the queue elements in result.

  • API prototype
static void QueueListAsync(const int64_t room_id, const QueueListCallback& callback, const std::string& json_extension = "");

  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
callback Operation result callback
json_extension Extension parameter, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueueListAsync(roomId,[&](::int64_t room_id, int error_code, const ChatRoomQueue& queue)
{
    //result: json array of queue elements, as obtained, examples include [{"key":"key1","value":"value1"},{"key":"key2","value":"value2"}]
	...
});

Delete Mic Queue

Manager permissions are required to delete the entire mic queue.

  • API prototype
static void QueueDropAsync(const int64_t room_id, const QueueDropCallback& callback, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
room_id Chat room id, i.e. room number, required)
callback Operation result callback
json_extension Extension parameter, reserved
  • Example
//Take test room 3001 as an example
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueueDropAsync(roomId,[&](::int64_t room_id, int error_code)
{
	...
});

Was this topic helpful?
Yes
No
  • Overview of Chat Room Features
  • Initialization and Clearup
  • Notification of Chat Room Event
  • Chat Room Login Event
  • Leave Chat Room Event
  • Chat Room Connection Status Change Notification
  • Receive Message Event
  • Notification of Message Sending Result
  • Event of Receiving Chat Room Notification
  • Enter A Chat Room
  • Get Token
  • Log in to Chat Room
  • Exit from Chat Room
  • Send Chat Room Message
  • Create Chat Room Message
  • Send Message
  • Query Cloud-based Message History
  • Chat Room Management
  • Get Chat Room Information
  • Update Chat Room Information
  • Get List of Chat Room Members
  • Get Information of Specified Chat Room Member
  • Update Personal Chat Room Information
  • Chat Room Permission Management
  • Set Member ID Tag
  • Temporarily Mute Members
  • Kick Online Members Out
  • Chat Room Queue Service
  • New (Updated) Quene Element of Mic Queue
  • Take out Mic Queue Elements
  • Get All Queue Elements
  • Delete Mic Queue