聊天室

开发者中心

IM 即时通讯（含 UI）

了解产品

聊天室

更新时间： 2022/12/06 12:05:19

聊天室功能概述

聊天室特点：

进入聊天室时必须建立新的连接，退出聊天室或者被踢会断开连接，在聊天室中掉线会有自动重连，开发者需要监听聊天室连接状态来做出正确的界面表现。
支持聊天人数无上限。
支持同时进入多个聊天室，会建立多个连接。
不支持多端进入同一个聊天室，后进入的客户端会将前一个踢掉。
断开聊天室连接后，服务器不会再推送该聊天室的消息给此用户。
聊天室成员分固定成员和游客两种类型。
目前服务器控制最多支持同时进入10个聊天室，超过10个服务器会将之前登录的聊天室踢出一个

初始化与清理

使用聊天室功能时必须调用 nim_chatroom::ChatRoom::Init() 进行初始化，退出使用聊天室功能时需调用 nim_chatroom::ChatRoom::Cleanup() 进行清理工作。两者必须配对使用，避免造成不必要的异常。

聊天室事件通知

聊天室的登录、登出，收到消息等等操作都是通过监听全局事件来通知给调用者。必须在调用登录操作之前，先监听所有的聊天室事件通知。建议在初始化完成后就注册事件监听。

登录聊天室事件

在开发者调用登录聊天室接口后，通过此事件通知开发者登录进度和结果。登录步骤按本地服务初始，连接服务器中，服务器连接完成，登录鉴权中，登录鉴权完成五个步骤顺序进行，当登录鉴权成功后，可以获取得到当前聊天室的信息和本人在聊天室中的成员信息。

NIMChatRoomLoginStep枚举说明

枚举	值	说明
kNIMChatRoomLoginStepInit	1	本地服务初始化
kNIMChatRoomLoginStepServerConnecting	2	服务器连接中
kNIMChatRoomLoginStepServerConnectOver	3	服务器连接结束,连接结果error_code
kNIMChatRoomLoginStepRoomAuthing	4	聊天室鉴权中
kNIMChatRoomLoginStepRoomAuthOver	5	聊天室鉴权结束,鉴权结果见error_code, error_code非408则需要开发者重新请求聊天室登录信息

API 原型

static void RegEnterCb(const EnterCallback& cb, const std::string& json_extension = "");

参数说明

参数	说明
cb	异步回调通知
json_extension	扩展字段，预留

示例

//监听登录事件
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)
    {
        //进入聊天室成功
    }
    if (error_code != kNIMResSuccess)
    {
         //进入聊天室出错
    }
});

//取消监听
nim_chatroom::ChatRoom::RegEnterCb(nullptr);

退出聊天室事件

通知已经退出聊天室，除了主动退出聊天室之外，还包括被多端、主播和管理员踢出，以及聊天室被关闭或者被解散也会收到离开聊天室的通知。收到该通知后，该聊天不再自动重连进入聊天室。重新登录需要重新获取token

NIMChatRoomExitReason枚举参数说明

枚举	值	说明
kNIMChatRoomExitReasonExit	0	自行退出，重登前需要重新请求登录
kNIMChatRoomExitReasonRoomInvalid	1	聊天室已经被解散,重登前需要重新请求登录
kNIMChatRoomExitReasonKickByManager	2	被管理员踢出,重登前需要重新请求登录
kNIMChatRoomExitReasonKickByMultiSpot	3	多端登录被踢
kNIMChatRoomExitReasonIllegalState	4	当前链接状态异常
kNIMChatRoomExitReasonBeBlacklisted	5	被管理员加入黑名单

API 原型

static void RegExitCb(const ExitCallback& cb, const std::string& json_extension = "");

参数说明

参数	说明
cb	异步回调通知
json_extension	扩展字段，预留

示例

void OnExitHandler(long roomId, ResponseCode errorCode, NIMChatRoomExitReason reason)
{
    ...
}
//监听事件
nim_chatroom::ChatRoom::RegExitCb([&](::int64_t room_id, int error_code, NIMChatRoomExitReason reason)
{
    ...
});

//取消监听
nim_chatroom::ChatRoom::RegExitCb(nullptr);

聊天室连接状态更改通知

网络出现波动导致聊天室断开连接时，会通知开发者聊天室的连接状态。SDK 会监听网络状况，自动重连。

NIMChatRoomLinkCondition枚举参数说明

枚举	值	说明
kNIMChatRoomLinkConditionAlive	0	连接正常
kNIMChatRoomLinkConditionDeadAndRetry	1	连接失败，尝试重连
kNIMChatRoomLinkConditionDead	2	开发者需要重新申请聊天室登录信息

API 原型

static void RegLinkConditionCb(const LinkConditionCallback& cb, const std::string& json_extension = "");

参数说明

参数	说明
cb	异步回调通知
json_extension	扩展字段，预留

示例

//监听事件
nim_chatroom::ChatRoom::RegLinkConditionCb([&](::int64_t room_id, NIMChatRoomLinkCondition condition)
{
    ...
});

//取消监听
nim_chatroom::ChatRoom::RegLinkConditionCb(nullptr);

接收消息事件

收到一条聊天室消息,消息内容为ChatRoomMessage。多个聊天室的消息都是通过该事件通知，开发者通过区分roomId来区分各自的聊天室。所有的聊天室消息本地都不做存储。

NIMChatRoomMsgType枚举说明

枚举	值	说明
kNIMChatRoomMsgTypeText	0	文本类型消息
kNIMChatRoomMsgTypeImage	1	图片类型消息
kNIMChatRoomMsgTypeAudio	2	声音类型消息
kNIMChatRoomMsgTypeVideo	3	视频类型消息
kNIMChatRoomMsgTypeLocation	4	位置类型消息
kNIMChatRoomMsgTypeNotification	5	活动室通知
kNIMChatRoomMsgTypeFile	6	文件类型消息
kNIMChatRoomMsgTypeTips	10	提醒类型消息
kNIMChatRoomMsgTypeRobot	11	波特机器人消息
kNIMChatRoomMsgTypeCustom	100	自定义消息
kNIMChatRoomMsgTypeUnknown	1000	未知类型消息，作为默认值

ChatRoomMessage重要参数说明

类型	参数	说明
int64_t	room_id_	消息所属的聊天室id(服务器填充)
string	from_id_	消息发送者
int64_t	timetag_	消息发送的时间戳（毫秒）(服务器填充)
NIMChatRoomClientType	from_client_type_	消息发送方客户端类型,发送方不需要填写(服务器填充)
string	from_nick_	消息发送者昵称(服务器填充)
string	from_avatar_	消息发送者头像(服务器填充)
string	from_ext_	消息发送者身份扩展字段(服务器填充)
NIMChatRoomMsgType	msg_type_	消息类型，详见NIMChatRoomMsgType
string	msg_attach_	消息内容,长度限制2048,如果约定的是json字符串，必须为可以解析为json的非格式化的字符串，除文本消息外，其他图片、语音、视频、地理位置、自定义消息都需要是目前约定好的json串，此内容是透传内容，本质上是`IM`消息的附件内容。参考发送消息的相应类型消息
string	client_msg_id_	客户端消息id,发送方填写
ChatRoomMessageSetting	msg_setting_	消息设置，详见ChatRoomMessageSetting
string	local_res_path_	媒体文件本地绝对路径（客户端）（暂不支持）
string	local_res_id_	本地媒体文件ID（客户端）（暂不支持）

ChatRoomMessageSetting消息设置重要参数说明

类型	参数	说明
bool	resend_flag	消息是否需要重发，true:需要，false:不需要，默认是false（暂不支持）
string	ext_	第三方扩展字段, 长度限制4096, 必须为可以解析为Json的非格式化的字符串
bool	anti_spam_enable_	是否需要过易盾反垃圾，true:需要，false:不需要,默认false,参考IM消息的反垃圾设置
string	anti_spam_content_	(可选)开发者自定义的反垃圾字段,长度限制：5000字符
bool	history_save_	是否存云端消息历史，默认存（暂不支持）

API 原型

static void RegReceiveMsgCb(const ReceiveMsgCallback& cb, const std::string& json_extension = "");

参数说明

参数	说明
cb	异步回调通知
json_extension	扩展字段，预留

示例

//监听事件
nim_chatroom::ChatRoom::RegReceiveMsgCb([&](::int64_t room_id, const ChatRoomMessage& result)
{
	...
});

//取消监听
nim_chatroom::ChatRoom::RegReceiveMsgCb(nullptr);

发送消息结果通知

通过该事件，用户可以知道消息发送成功与否。

API 原型

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

参数说明

参数	说明
cb	异步回调通知
json_extension	扩展字段，预留

示例

//监听事件
nim_chatroom::ChatRoom::RegSendMsgAckCb([&](::int64_t room_id, int error_code,const ChatRoomMessage& result)
{
    ...
});

//取消监听
nim_chatroom::ChatRoom::RegSendMsgAckCb(nullptr);

收到聊天室通知消息事件

聊天室的所有通知消息都通过该事件接收。包括成员进入/离开聊天室，禁言/解除禁言，加黑/取消加黑等等，详见ChatRoomNotification说明。

NIMChatRoomNotificationId枚举说明

枚举值	说明
kNIMChatRoomNotificationIdMemberIn	成员进入聊天室
kNIMChatRoomNotificationIdMemberExit	成员离开聊天室
kNIMChatRoomNotificationIdAddBlack	成员被加入黑名单
kNIMChatRoomNotificationIdRemoveBlack	成员被取消黑名单
kNIMChatRoomNotificationIdAddMute	成员被禁言
kNIMChatRoomNotificationIdRemoveMute	成员被取消禁言
kNIMChatRoomNotificationIdAddManager	设置为管理员
kNIMChatRoomNotificationIdRemoveManager	被取消管理员
kNIMChatRoomNotificationIdAddFixed	设置为聊天室固定成员
kNIMChatRoomNotificationIdRemoveFixed	被取消聊天室固定成员
kNIMChatRoomNotificationIdClosed	聊天室被关闭了
kNIMChatRoomNotificationIdInfoUpdated	聊天室信息更新
kNIMChatRoomNotificationIdMemberKicked	成员被踢出聊天室
kNIMChatRoomNotificationIdMemberTempMute	临时禁言
kNIMChatRoomNotificationIdMemberTempUnMute	解除临时禁言
kNIMChatRoomNotificationIdMyRoleUpdated	成员主动更新了聊天室内的角色信息(仅指nick/avator/ext)
kNIMChatRoomNotificationIdRoomMuted	聊天室被禁言了,只有管理员可以发言,其他人都处于禁言状态
kNIMChatRoomNotificationIdRoomDeMuted	聊天室解除全体禁言状态

再来看下ChatRoomNotification参数说明

类型	参数	说明
NIMChatRoomNotificationId	id_	通知类型
string	ext_	上层开发自定义的事件通知扩展字段, 必须为可以解析为Json的非格式化的字符串
string	operator_id_	操作者的账号id
string	operator_nick_	操作者昵称
std::list< std::string >	target_nick_	被操作者的nick列表
std::list< std::string >	target_ids_	操作者的账号id列表
bool	muted_	当通知类型为成员进入时有该值，代表是否禁言状态，1:是缺省或0:不是
bool	temp_muted_	当通知类型为成员进入言时有该值，代表临时禁言状态
int64_t	temp_mute_duration_	当通知为临时禁言相关时有该值，禁言时代表本次禁言的时长(秒)，取消禁言时代表本次剩余禁言时长（秒）;当通知类型为成员进入时，代表临时禁言时长（秒），其他通知不带此数据
string	queue_change_	当通知为聊天室队列变更事件才有，代表变更的内容（暂不支持）

API 原型

 static void RegNotificationCb(const NotificationCallback& cb, const std::string& json_extension = "");

示例

//监听事件
nim_chatroom::ChatRoom::RegNotificationCb([&](::int64_t room_id, const ChatRoomNotification& notification)
{
	...
});

//取消监听
nim_chatroom::ChatRoom::RegNotificationCb(nullptr);

进入聊天室

获取token

聊天室依赖IM，进入聊天室前，需要通过调用IM模块接口获取进入聊天室的授权信息，在开发者调用登录聊天室接口时将此授权信息传入接口。聊天室可以同时登录多个，每个聊天室都要各自根据roomId请求授权信息.

注意：这里调用的是 IM SDK 模块的接口

API 原型

static void ChatRoomRequestEnterAsync(const int64_t room_id, const ChatRoomRequestEnterCallback &callback, const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
callback	结果通知回调
json_ext	扩展信息，预留

API 示例

//以测试房间号3001为例
int64_t roomId = 3001;
string _token = "";

nim::PluginIn::ChatRoomRequestEnterAsync(roomId, [&](int error_code, const std::string& result)
{
	if (error_code == kNIMResSuccess)
    {
    	_token = result; //此token即为所需要的授权信息
        //nim_chatroom::ChatRoom::Enter，尽量请抛一个异步任务去操作,如下；
        scheduleOnce([&](float dt)
        {
        	ChatRoomEnterInfo loginData;
            loginData.SetNick("nickName");
            loginData.SetIcon("https://xxxx.png");//图片url
            loginData.SetExt("{\"myExt\:\"111\"}");
            loginData.SetNotifyExt("{\"myNotifyExt\:\"2222\"}") ;
			nim_chatroom::ChatRoom::Enter(roomId,_token,loginData);
		});
    }
});

登录聊天室

进入聊天室时，可以通过ChatRoomEnterInfo设置本人在聊天室的昵称，头像，以及传递通知信息和扩展信息等。登录过程通过登录聊天室事件通知开发者。

ChatRoomEnterInfo参数说明

类型	参数	说明
string	SetNick	进入聊天室后展示的昵称,选填
string	SetIcon	进入聊天室的头像，填头像的url,选填
string	SetExt	扩展字段信息，必须是json字符串,选填
string	SetNotifyExt	进入聊天室通知扩展字段,必须是json字符串，选填

API 原型

static bool Enter(const int64_t room_id, const std::string& request_login_data, const ChatRoomEnterInfo& info = ChatRoomEnterInfo(), const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
requestrequest_login_data	通过接口获取token获取的授权信息，必填
info	进入聊天室时附带的个人信息，选填
json_extension	扩展信息，预留

示例

查阅示例代码

离开聊天室

离开聊天室，会断开聊天室对应的链接，并不再收到该聊天室的任何消息。如果用户要离开聊天室，可以手动调用离开聊天室接口。

API 原型

static void Exit(const int64_t room_id, const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
json_extension	扩展信息，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::Exit(roomId);

发送聊天室消息

先创建消息内容Message，然后通过nim_chatroom::ChatRoom::SendMsg接口，发送结果通过发送消息结果通知给用户。可发送多种类型消息，包括文本，图片，语音，视频，地理位置等等各种自定义消息，具体消息内容可参见IM的消息收发。本地没有保存消息历史记录，可以查询云端历史消息记录。

为保证用户体验（如避免服务器过载），目前针对消息接收，有两套流控机制。第一套针对普通消息，聊天室用户每秒至多可接收20条，超过部分会因为流控随机丢弃。第二套针对高优先级消息，每秒至多接收10条，超过部分无法保证不丢失。
为避免丢失重要消息（通常为服务端消息），可将发送聊天室消息的 HighPriority 参数设置为 true 实现高优先级接收服务端消息，进而保证高优先级消息流控上限内（每秒10条）的重要消息不丢失。详情请参见发送聊天室消息中的 HighPriority 参数说明。

创建聊天室消息

API 原型

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);

参数说明

参数	说明
msg_type	消息类型）
client_msg_id	消息id）
attach	消息内容详见ChatRoomMessage的`attach`说明
msg_body	文本消息内容（暂不支持）
msg_setting	消息设置，详见ChatRoomMessageSetting
timetag	当前UNIX时间戳，毫秒

发送消息

1秒内默认最多可调用该接口100次。如需上调上限，请在官网首页通过微信、在线消息或电话等方式咨询商务人员。

API 原型

static void SendMsg(const int64_t room_id, const std::string& json_msg, const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
json_msg	消息内容详见ChatRoomMessage,可以使用创建聊天室消息接口创建
json_extension	扩展信息，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
//消息设置
ChatRoomMessageSetting setting;
setting.ext_ = "{\"ext\":\"自定义扩展内容\"}";
...

std::string msg = nim_chatroom::ChatRoom::CreateRoomMessage(kNIMChatRoomMsgTypeText,"消息唯一uuid","这是一条文本消息","",setting);
nim_chatroom::ChatRoom::SendMsg(roomId,msg);

查询云端历史消息记录

SDK支持查询在云端的聊天室历史消息记录。

ChatRoomGetMsgHistoryParameters参数说明

类型	参数	说明
int64_t	start_timetag_	开始时间,单位毫秒
int	limit_	查询最大条数上限，必须为大于0的值
bool	reverse_	是否反向查询

API 原型

static void GetMessageHistoryOnlineAsync(const int64_t room_id,	const ChatRoomGetMsgHistoryParameters &parameters,	const GetMsgHistoryCallback &callback,const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
parameters	获取聊天室消息历史参数
callback	结果回调通知
json_extension	扩展信息，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
ChatRoomGetMembersParameters params;
params.limit_ = 20;
params.startTimetag = 1520391909233;//13位时间戳(毫秒)
params.reverse_ = false;
nim_chatroom::ChatRoom::GetMessageHistoryOnlineAsync(roomId, params, [&](::int64_t room_id, int error_code, const std::list<ChatRoomMessage>& messages)
{
   ...
});

聊天室管理

获取聊天室信息

进入聊天室的事件中会有聊天室的信息，此外还能通过单独的接口获取聊天室信息。SDK 本地不缓存聊天室信息，只提供向服务器查询的接口，因此接口调用遵循服务器接口使用频率限制。

ChatRoomInfo重要参数说明

类型	参数	说明
int64_t	id_	聊天室id,即房间号
string	name_	聊天室名称，管理员可以更新此信息
string	announcement_	聊天室公告
string	broadcast_url_	视频直播流地址
string	creator_id_	聊天室创建者账号id
int	valid_flag_	聊天室有效标记，1：有效，0: 无效
string	ext_	第三方扩展字段, 必须为可以解析为Json的非格式化的字符串, 长度4k
int	online_count_	在线人数
bool	mute_all_	聊天室禁言标志，1:禁言 0：不禁言

API 原型

static void GetInfoAsync(const int64_t room_id,const GetChatRoomInfoCallback& callback,const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
callback	结果回调通知
json_extension	扩展信息，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::GetInfoAsync(roomId, [&](int64_t room_id, int error_code, const ChatRoomInfo& info)
{
	...
});

更新聊天室信息

SDK支持更新聊天室信息，仅管理员拥有此权限。目前只支持更新ChatRoomInfo 的name_，announcement_，broadcast_url_，ext_ 四个属性。同时，在更新时可以设置是否在聊天室内广播通知。

API 原型

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 = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填
info	聊天室更新信息
need_notify	是否聊天室内广播通知,true:通知，此时`notify_ext`不为空 false:不通知
notify_ext	通知中的自定义字段，长度限制2048
callback	结果回调通知
json_extension	扩展信息，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
ChatRoomInfo info;
info.id_ = roomId,
info.announcement_ ="聊天室公告",
info.name_ = "newName",
info.broadcast_url_ = "http://xxxxx",
info.ext_ = "{\"test"\:\"1111\"}", //自定义扩展字串
nim_chatroom::ChatRoom::UpdateRoomInfoAsync(roomId, info,false,null,[&](::int64_t room_id, int error_code)
{
    ...
});

获取聊天室成员列表

该接口可以获取固定成员信息、仅在线的固定成员信息及游客信息 ChatRoomMemberInfo，其中的扩展字段由该用户进入聊天室时填写。固定成员有四种类型，分别是创建者,管理员,普通用户,受限用户。禁言用户和黑名单用户都属于受限用户。本地不缓存成员列表信息，均直接从云端获取。

ChatRoomMemberInfo重要参数说明

类型	参数	说明
int64_t	room_id_	聊天室id,即房间号
string	account_id_	成员账号
ChatRoomMemberType	type_	成员类型，-1:受限用户; 0:普通;1:创建者;2:管理员，详见ChatRoomMemberType
int	level_	成员级别: >=0,表示用户开发者可以自定义的级别
string	nick_	聊天室内的昵称字段,可以由用户进聊天室时提交
string	avatar_	聊天室内的头像,可以由用户进聊天室时提交
string	ext_	第三方扩展字段, 必须为可以解析为Json的非格式化的字符串, 长度4k
NIMChatRoomOnlineState	state_	成员是否处于在线状态, 仅特殊成员才可能离线, 对游客/匿名用户而言只能是在线，0：离线 1: 在线
NIMChatRoomGuestFlag	guest_flag_	是否是普通游客类型,0:不是游客,1:是游客; 游客身份在聊天室中没有持久化, 只有在线时才会有内存状态
int64_t	enter_timetag_	进入聊天室的时间戳（毫秒）,对于离线成员该字段为空
bool	is_blacklist_	是否在黑名单 1:是 0：否
bool	is_muted_	是否被禁言 1:是 0：否
bool	is_valid_	是否有效 1:是 0：否
bool	temp_muted_	是否被临时禁言 1:是 0：否
int64_t	temp_muted_duration_	临时禁言剩余时长,单位秒
int64_t	update_timetag_	固定成员的记录更新时间戳,用于固定成员列表的排列查询

NIMChatRoomGetMemberType枚举说明

枚举	值	说明
kNIMChatRoomGetMemberTypeSolid	0	固定成员，包括创建者,管理员,普通等级用户,受限用户(禁言+黑名单),即使非在线也可以在列表中看到,有数量限制
kNIMChatRoomGetMemberTypeTemp	1	非固定成员，又称临时成员，只有在线时才能在列表中看到,数量无上限

ChatRoomMemberType枚举说明

枚举	值	说明
Restricted	-1	受限制成员
Normal	0	普通成员
Creator	1	创建者

ChatRoomGetMembersParameters参数说明

类型	参数	说明
NIMChatRoomGetMemberType	type_	成员类型，详见NIMChatRoomGetMemberType
int64_t	timestamp_offset_	距离当前时间的时间戳
int	limit_	查询最大条数上限，必须为大于0的值

API 原型

static void GetMembersOnlineAsync(const int64_t room_id,const ChatRoomGetMembersParameters &parameters,const GetMembersCallback& callback,const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
parameters	查询参数设置，详见ChatRoomGetMembersParameters
callback	结果回调通知
json_extension	扩展信息，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
ChatRoomGetMembersParameters params;
params.limit_ = 20;
params.timestamp_offset_ = 0;//距离当前时间的时间戳
params.type_ = kNIMChatRoomGetMemberTypeSolid;
nim_chatroom::ChatRoom::GetMembersOnlineAsync(roomId, params, [&](::int64_t room_id, int error_code, const std::list<ChatRoomMemberInfo>& infos)
{
    ...
});

获取指定聊天室成员信息

该接口可以获取指定多个账号的成员信息ChatRoomMemberInfo，从云端获取。

API 原型

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

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
ids	成员id集合
callback	结果回调通知
json_extension	扩展信息，预留

示例

//以测试房间号3001,聊天室成员test1,test2为例
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)
{
	...
});

更新自己的聊天室信息

目前支持更新本人聊天室成员信息。目前只支持昵称，头像和扩展字段的更新。可以设置更新是否通知，如果设置通知，则通过收到聊天室通知消息事件通知给用户。

API 原型

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 = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
info	成员信息，将需要修改的字段修改为新的字段,目前只支持更新 `ChatRoomMemberInfo` 的 `Nick`, `MemberIcon`,`Extension` 三个属性。详见ChatRoomMemberInfo
callback	结果回调通知
notify	是否聊天室内广播通知,true:通知，此时`notify_ext`不为空 false:不通知
notify_ext	通知中的自定义字段，长度限制2048
json_extension	预留字段

示例

//以测试房间号3001
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)
{
	...
});

聊天室权限管理

设置成员身份标识

设置/取消管理员时, 服务器会通过收到聊天室通知消息事件通知给用户。通知类型查看说明。如果游客被设为管理员，再被取消管理员，该成员不再变为游客，而成为普通成员。

NIMChatRoomMemberAttribute枚举说明

枚举	值	说明
kNIMChatRoomMemberAttributeAdminister	1	管理员(固定成员),仅创建者拥有操作提升权限
kNIMChatRoomMemberAttributeNomalSold	2	普通成员,操作者必须是创建者或管理员
kNIMChatRoomMemberAttributeBlackList	-1	黑名单成员,操作者必须是创建者或管理员
kNIMChatRoomMemberAttributeMuteList	-2	被永久禁言成员,操作者必须是创建者或管理员

ChatRoomSetMemberAttributeParameters参数说明

类型	参数	说明
string	account_id_	成员账号id
NIMChatRoomMemberAttribute	attribute_	成员身份标识，详见NIMChatRoomMemberAttribute
bool	opt_	对应设置成员身份标识，1：设置 0：取消设置
int	level_	用户等级,opt_= 1 or 2时才有效
string	notify_ext_	操作产生的通知事件中开发者自定义的扩展字段，需要是json字符串

API 原型

static void SetMemberAttributeOnlineAsync(const int64_t room_id,const ChatRoomSetMemberAttributeParameters& parameters,const SetMemberAttributeCallback& callback,const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
parameters	成员属性信息，详见ChatRoomSetMemberAttributeParameters
callback	操作结果回调
json_extension	预留字段

示例

//以测试房间号3001,聊天室成员test1为例
int64_t roomId = 3001;

//设置/取消管理员
ChatRoomSetMemberAttributeParameters ri;
ri.account_id_ = "test1",
ri.attribute_ = kNIMChatRoomMemberAttributeAdminister,
ri.opt_ = true,//如果设置为false,则为取消管理员

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

//设置/取消永久禁言
ChatRoomSetMemberAttributeParameters prop;
prop.account_id_ = "test1",
prop.attribute_ = kNIMChatRoomMemberAttributeMuteList,
prop.opt_ = true,//如果设置为false,则为取消禁言

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

临时禁言成员

此接口提供临时禁言/解除临时禁言成员的功能。如果需要永久禁言，请通过设置成员身份标识接口将用户设置为禁言用户。如果禁言时长时间到了，自动取消禁言。设置临时禁言成功后的通知消息中，包含的时长是禁言剩余时长。若设置禁言时长为0，表示取消临时禁言。若第一次设置的禁言时长还没结束，又设置第二次临时禁言，以第二次设置的时间开始计时。

API 原型

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 = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
accid	成员账号，必填）
duration	临时禁言时长（秒），解禁填0
callback	操作结果回调
notify	是否聊天室内广播通知
notify_ext	通知中的自定义字段，长度限制2048,json字符串
json_extension	预留字段

示例

//以测试房间号3001,聊天室成员test1为例,禁言60秒
int64_t roomId = 3001;
nim_chatroom::ChatRoom::TempMuteMemberAsync(roomId,"test1", 60,false,null,[&](::int64_t room_id, int error_code, const ChatRoomMemberInfo& info)
{
	...
});

踢出在线成员

踢出成员。仅管理员可以踢；如目标是管理员仅创建者可以踢。可以添加被踢通知扩展字段，这个字段会放到被踢通知的扩展字段中。被踢出聊天室的通知通过聊天室通知事件下发给开发者。

API 原型

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 = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
id	成员账号）
notify_ext	放到事件通知中的扩展字段
callback	操作结果回调
json_extension	预留字段

示例

//以测试房间号3001,聊天室成员test1为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::KickMemberAsync(roomId,"test1","notify" ,[&](::int64_t room_id, int error_code)
{
	...
});

聊天室队列服务

聊天室提供队列服务，针对直播连麦场景使用。

新加(更新)麦序队列元素

聊天室队列服务：加入或者更新队列元素(聊天室管理员权限).当 key 不存在时候，调用该接口，表示加入新元素。当 key 已存在的时候，调用该接口，表示修改对应 key 的 value。

ChatRoomQueueElement麦序队列元素说明

类型	参数	说明
string	key_	元素的唯一key,长度限制128字节
string	value_	元素的内容，长度限制4096字节

API 原型

static void QueueOfferAsync(const int64_t room_id, const ChatRoomQueueElement& element, const QueueOfferCallback& callback, const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填
element	麦序队列元素数据
callback	操作结果回调
json_extension	扩展参数，预留

示例

//以测试房间号3001为例
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);

取出麦序队列元素

element_key是唯一键,element_key 若为空，则表示取出头元素。若不为空，则表示取出指定元素。操作成功后，在回调通知中result获得该元素的key和value。

API 原型

 static void QueuePollAsync(const int64_t room_id, const std::string& element_key, const QueuePollCallback& callback, const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
element_key	元素的唯一key,长度限制128字节
callback	操作结果回调
json_extension	扩展参数，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueuePollAsync(roomId,"key1", [&](::int64_t room_id, int error_code, const ChatRoomQueueElement& element)
{
    //result:获取的队列元素的json字符串，如{"key":"key1","value":"value1"}
	...
});

获取所有队列元素

排序列出所有队列元素,在result返回队列元素的json数组。

API 原型

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

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
callback	操作结果回调
json_extension	扩展参数，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueueListAsync(roomId,[&](::int64_t room_id, int error_code, const ChatRoomQueue& queue)
{
    //result:获取的队列元素的json数组，如[{"key":"key1","value":"value1"},{"key":"key2","value":"value2"}]
	...
});

删除麦序队列

将整个麦序队列删除，需要管理员权限。

API 原型

static void QueueDropAsync(const int64_t room_id, const QueueDropCallback& callback, const std::string& json_extension = "");

参数说明

参数	说明
room_id	聊天室id，即房间号，必填）
callback	操作结果回调
json_extension	扩展参数，预留

示例

//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueueDropAsync(roomId,[&](::int64_t room_id, int error_code)
{
	...
});

在线咨询

微信咨询

电话咨询

此文档是否对你有帮助？

有帮助

去反馈

聊天室
聊天室功能概述
初始化与清理
聊天室事件通知
登录聊天室事件
退出聊天室事件
聊天室连接状态更改通知
接收消息事件
发送消息结果通知
收到聊天室通知消息事件
进入聊天室
获取token
登录聊天室
离开聊天室
发送聊天室消息
创建聊天室消息
发送消息
查询云端历史消息记录
聊天室管理
获取聊天室信息
更新聊天室信息
获取聊天室成员列表
获取指定聊天室成员信息
更新自己的聊天室信息
聊天室权限管理
设置成员身份标识
临时禁言成员
踢出在线成员
聊天室队列服务
新加(更新)麦序队列元素
取出麦序队列元素
获取所有队列元素
删除麦序队列