聊天室 - IM 即时通讯

IM 即时通讯

含 UI 集成

不含 UI 集成

圈组功能

更新时间： 2023/02/06 15:51:47

功能概述

云信提供聊天室功能，人数无上限，用户可自由进出聊天室。聊天室的创建与关闭需要通过服务端API来完成。

聊天室原型：

返回值	ChatRoomInfo 接口	说明
String	getAnnouncement()	获取聊天室公告
String	getBroadcastUrl()	获取聊天室直播地址
String	getCreator()	获取聊天室创建者帐号
Map	getExtension()	获取聊天室扩展字段
String	getName()	获取聊天室名称
int	getOnlineUserCount()	获取当前在线用户数量
int	getQueueLevel()	获取队列权限配置
String	getRoomId()	获取聊天室id
boolean	isMute()	获取当前聊天室禁言状态
boolean	isValid()	获取聊天室有效标记
void	setAnnouncement(String announcement)	设置聊天室公告
void	setBroadcastUrl(String broadcastUrl)	设置聊天室直播地址
void	setCreator(String creator)	设置聊天室创建者
void	setExtension(Map extension)	设置扩展字段
void	setMute(int mute)	设置当前聊天室禁言状态
void	setName(String name)	设置聊天室名称
void	setOnlineUserCount(int onlineUserCount)	设置当前在线用户数量
void	setRoomId(String roomId)	设置聊天室id
void	setValidFlag(int validFlag)	设置聊天室有效标记
void	setQueueLevel(int queueLevel)	设置队列权限，0 表示所有人都有权限，1 表示只有主播/管理员有权限

进入聊天室

用户要在聊天室收发消息之前，必须先调用接口进入聊天室。聊天室只允许用户手动进入，无法进行邀请。支持同时进入10个聊天室。

进入聊天室可以有两种方式：以独立模式进入聊天室和非独立模式进入聊天室。
独立模式是指在IM处于未登录的情况下，进入聊天室的方式，针对只需要聊天室功能的业务场景。
非独立模式是指先完成IM登录，再进入聊天室的方式，针对需要IM和聊天室功能的业务场景。

/**
 * 进入聊天室
 *
 * @param roomData   聊天室基本数据（聊天室ID必填）
 * @param retryCount 如果进入失败，重试次数
 * @return InvocationFuture 可以设置回调函数。回调中返回聊天室基本信息
 */
AbortableFuture<EnterChatRoomResultData> enterChatRoomEx(EnterChatRoomData roomData, int retryCount);

EnterChatRoomData部分参数说明：

返回值	EnterChatRoomData参数	说明
String	getAccount()	获取独立登录模式的用户账号
String	getAppKey()	获取聊天室appKey
String	getAvatar()	获取聊天室展示的头像
Map	getExtension()	获取进入聊天室后展示的扩展字段
ChatRoomIndependentCallback	getIndependentModeCallback()	获取独立模式的回调
String	getNick()	获取聊天室展示的昵称
Map	getNotifyExtension()	获取聊天室通知开发者扩展字段
String	getRoomId()	获取聊天室 ID
String	getToken()	获取独立登录模式的用户密码
boolean	isIndependentMode()	是否是独立登录聊天室
boolean	isAnonymousMode()	是否是匿名模式
String	getChatRoomAuthProvider()	获取动态token回调
String	getTags()	获取登录标签
String	getNotifyTargetTags()	获取登录登出通知的目标标签，目标标签说明请参见标签表达式
AntiSpamConfig	getAntiSpamConfig()	获取反垃圾配置项
Integer	getLoginAuthType()	获取获取鉴权方式，0表示最初的loginToken的校验方式，1表示基于appSecret计算的token鉴权方式，2表示基于第三方回调的token鉴权方式，默认0
ChatRoomSpatialLocation	getChatRoomSpatialLocation()	获取空间位置信息
void	setAppKey(String appKey)	设置聊天室appKey，独立登录模式下，才启用，不传则使用IM对应的appKey，需要保证roomId与appKey的对应关系
void	setAvatar(String avatar)	设置聊天室展示的头像
void	setExtension(Map extension)	设置进入聊天室后展示用户信息的扩展字段，长度限制 4k。设置后在获取聊天室成员信息 ChatRoomMember 时可以查询到此扩展字段；此外，在收到聊天室消息时，可以从 ChatRoomMessage#ChatRoomMessageExtension#getSenderExtension 中获取消息发送者的用户信息扩展字段。若没有设置，则这个字段为 null。
void	setIndependentMode(ChatRoomIndependentCallback cb, String account, String token)	设置聊天室独立模式
void	setNick(String nick)	设置聊天室展示的昵称(可选字段), 如果不填则直接使用 NimUserInfo 中的昵称
void	setNotifyExtension (Map notifyExtension)	设置聊天室通知消息扩展字段，长度限制 2k。设置后，在收到聊天室通知消息的 ChatRoomNotificationAttachment 中可以获取到此扩展字段。
void	setRoomId(String roomId)	设置聊天室 ID
void	setTags(String tags)	设置登录标签
void	setChatRoomAuthProvider(ChatRoomAuthProvider chatRoomAuthProvider)	设置动态Token回调
void	setNotifyTargetTags(String notifyTargetTags)	设置登录登出通知的目标标签
void	setAntiSpamConfig(AntiSpamConfig antiSpamConfig)	设置反垃圾配置项
void	setLoginAuthType(Integer loginAuthType))	设置鉴权方式
void	setLoginExt(String loginExt)	设置登录自定义字段
void	setChatRoomSpatialLocation(ChatRoomSpatialLocation chatRoomSpatialLocation)	设置空间位置信息

鉴权方式

聊天室通过setLoginAuthType方法支持三种鉴权方式。0表示最初的loginToken的校验方式，1表示动态token鉴权方式，2表示基于第三方回调的token鉴权方式，默认0。如果配置为动态token鉴权方式，则需要通过setChatRoomAuthProvider方法设置动态Token回调。进入聊天室时，SDK通过此回调实时获取token。

示例

// roomId 表示聊天室ID
EnterChatRoomData data = new EnterChatRoomData(roomId);
data.setLoginAuthType(1);
data.setChatRoomAuthProvider(new ChatRoomAuthProvider() {
                @Override
                public String getToken(String roomId,String account) {
                    return DemoAuthProvider.getTokenFromServer(account);
                }
            })
// 以登录一次不重试为例
NIMClient.getService(ChatRoomService.class).enterChatRoomEx(data, 1).setCallback(new RequestCallback<EnterChatRoomResultData>() {
    @Override
    public void onSuccess(EnterChatRoomResultData result) {
        // 登录成功
    }

    @Override
    public void onFailed(int code) {
        // 登录失败
    }

    @Override
    public void onException(Throwable exception) {
        // 错误
    }
});

非独立模式

非独立模式较为简单，在IM处于登录状态时，直接调用进入聊天室方法即可。

示例

// roomId 表示聊天室ID
EnterChatRoomData data = new EnterChatRoomData(roomId);
// 以登录一次不重试为例
NIMClient.getService(ChatRoomService.class).enterChatRoomEx(data, 1).setCallback(new RequestCallback<EnterChatRoomResultData>() {
    @Override
    public void onSuccess(EnterChatRoomResultData result) {
        // 登录成功
    }

    @Override
    public void onFailed(int code) {
        // 登录失败
    }

    @Override
    public void onException(Throwable exception) {
        // 错误
    }
});

独立模式

当选择以独立模式进入聊天室时，必须通过EnterChatRoomData.setIndependentMode(...)方法设置聊天室独立模式。

API 原型

/**
 * 设置聊天室独立模式
 *
 * @param cb      如果是独立模式，必须提供回调函数，用于SDK向APP获取聊天室地址信息的数据。
 * @param account 独立登录的账号，可以不填。不填即为匿名登录
 * @param token   独立登录的密码。
 */
public void setIndependentMode(ChatRoomIndependentCallback cb, String account, String token);

参数说明

参数	说明
cb	如果是独立模式，必须提供回调函数，用于SDK向APP获取聊天室地址信息的数据
account	独立登录的账号，可以不填。不填即为匿名登录
token	独立登录的密码

API 原型

/**
     * 设置聊天室独立模式
     *
     * @param cb              如果是独立模式，必须提供回调函数，用于SDK向APP获取聊天室地址信息的数据。
     * @param account         独立登录的账号，
     * @param token           独立登录的密码。
     * @param isAnonymousMode 是否匿名模式，如果为false，account参数不可为空
     */
public void setIndependentMode(ChatRoomIndependentCallback cb, String account, String token,boolean isAnonymousMode);

匿名模式与非匿名模式

独立模式下又可分为匿名模式与非匿名模式。匿名模式只能收消息，不能发消息。

当第一个setIndependentMode方法传参account 不填时，则为匿名模式。SDK 将使用自动生成的匿名账号进行登录。在匿名模式下，必须通过EnterChatRoomData的setNick和setAvatar 设置昵称和头像信息。

第二个setIndependentMode方法则可以明确指定是否为匿名模式，同时如果isAnonymousMode为true，情况下如果account不为空，则表示匿名模式下自定义账号名。在匿名模式下，必须通过EnterChatRoomData的setNick和setAvatar 设置昵称和头像信息。

获取聊天室地址

独立模式由于不依赖IM连接，SDK无法自动获取聊天室服务器的地址，需要客户端向开发者应用服务器请求该地址，而应用服务器需要向网易云信服务器请求，然后将请求结果原路返回给客户端，即请求路径为：客户端 <-> 开发者应用服务器 <-> 网易云信服务器(API：请求聊天室地址)。

需要通过ChatRoomIndependentCallback - getChatRoomLinkAddresses设置SDK通过开发者应用服务器获取聊天室地址的回调方法：

/**
 *  聊天室独立登录模式的回调函数，用于上层 APP 向 SDK 提供数据
 */ 
java.util.List<java.lang.String> getChatRoomLinkAddresses(java.lang.String roomId,
                                                          java.lang.String account);

示例

示例一：独立模式的匿名登录

// roomId 为聊天室id
EnterChatRoomData data = new EnterChatRoomData(roomId);

// 独立模式的匿名模式登录聊天室
data.setNick("testNick"); // 此模式，昵称必填。以testNick为例
data.setAvatar("avatar"); // 此模式，头像必填。以avatar为例
data.setIndependentMode(new ChatRoomIndependentCallback() {
    @Override
    public List<String> getChatRoomLinkAddresses(String roomId, String account) {
        // 向应用服务器请求聊天室地址，非SDK接口
        return ChatRoomHttpClient.getInstance().fetchChatRoomAddress(roomId, null);
    }
}, null, null);

NIMClient.getService(ChatRoomService.class).enterChatRoomEx(data, 1).setCallback(new RequestCallback<EnterChatRoomResultData>() {
    @Override
    public void onSuccess(EnterChatRoomResultData result) {

    }

    @Override
    public void onFailed(int code) {

    }

    @Override
    public void onException(Throwable exception) {

    }
});

示例二：独立模式的非匿名登录

// roomId 为聊天室id
EnterChatRoomData data = new EnterChatRoomData(roomId);

// 独立模式的非匿名登录，帐号和密码必填，以account和token为例
data.setIndependentMode(new ChatRoomIndependentCallback() {
    @Override
    public List<String> getChatRoomLinkAddresses(String roomId, String account) {
        // 向应用服务器请求聊天室地址，非SDK接口
        return ChatRoomHttpClient.getInstance().fetchChatRoomAddress(roomId, "account");
    }
}, "account", "token");

NIMClient.getService(ChatRoomService.class).enterChatRoomEx(data, 1).setCallback(new RequestCallback<EnterChatRoomResultData>() {
    @Override
    public void onSuccess(EnterChatRoomResultData result) {

    }

    @Override
    public void onFailed(int code) {

    }

    @Override
    public void onException(Throwable exception) {

    }
});

支持聊天室空间消息

SDK 在 8.11.0 中新增了空间消息能力，用于在部分基于空间坐标的场景下给指定范围内的用户发送消息，如某游戏地图内指定范围的区域。要使用空间消息能力，您首先需要开启空间消息开关SDKOptions#enableChatRoomLocation，在加入聊天室时，可以预设一个坐标位置来加入房间，并且可以订阅接收多少距离内的消息。

示例

// roomId 表示聊天室ID
EnterChatRoomData data = new EnterChatRoomData(roomId);
//设置空间位置信息以及需要接受消息的距离
ChatRoomSpatialLocation location = new ChatRoomSpatialLocation(100.0, 100.0, 100.0,200.0);
data.setChatRoomSpatialLocation(location);
// 以登录一次不重试为例
NIMClient.getService(ChatRoomService.class).enterChatRoomEx(data, 1).setCallback(new RequestCallback<EnterChatRoomResultData>() {
    @Override
    public void onSuccess(EnterChatRoomResultData result) {
        // 登录成功
    }

    @Override
    public void onFailed(int code) {
        // 登录失败
    }

    @Override
    public void onException(Throwable exception) {
        // 错误
    }
});

更新位置信息

/**
 * 更新位置信息
 * 注意：每300ms只能上报一次位置信息给服务器，300ms 内多次调用返回 416
 * @param roomId 当前聊天室id
 * @param location 空间位置信息
 * @return
 */
InvocationFuture<Void> updateLocation(String roomId, ChatRoomSpatialLocation location);

ChatRoomSpatialLocation 参数说明：

参数	说明
x	坐标x
y	坐标y
z	坐标z
distance	订阅的消息的距离

聊天室多端登录

支持设置聊天室多端登录策略，即当同账号在不同客户端登录时，是否可以同时进入同一个聊天室。可以进入云信控制台选择应用 > IM专业版 > 功能配置 > 聊天室配置 > 聊天室多端登录配置进行设置。

只允许一端登录，Windows、Web、Android、iOS 彼此互踢。同一账号仅允许在一台设备上登录。当该账号在另一台设备上成功登录时，新设备会将旧设备踢下线。
各端均可以同时登录在线。最多可支持10个设备同时在线，在设备数上限内，所有的新设备再次登录，均不会将在线的旧设备踢下线。

控制台修改多端互踢的逻辑之后，下次新的设备登录时才会基于新的多端互踢策略进行校验，已经建立连接的设备不会因为策略的修改被强制踢出。

如果某台设备重复登录同一个聊天室，后登录的会将前面的长连接断开，此时会再触发一次进入聊天室的抄送，但是不会触发退出聊天室的抄送。关于进出聊天室（eventType=9）的抄送请参见聊天室事件抄送。

监听聊天室连接变化

进入聊天室成功后，SDK 会负责维护与服务器的长连接以及断线重连等工作。当用户在线状态发生改变时，会发出通知。登录过程也有状态回调。此外，网络连接上之后，SDK 会负责聊天室的自动登录。

API 原型

/**
 * 注册/注销聊天室在线状态/登录状态观察者
 *
 * @param observer 观察者, 参数为聊天室ID和聊天室状态（未进入、连接中、进入中、已进入）
 * @param register true为注册，false为注销
 */
public void observeOnlineStatus(Observer<ChatRoomStatusChangeData> observer, boolean register);

参数说明

ChatRoomStatusChangeData 属性	说明
roomId	聊天室 ID
status	状态码，参考 StatusCode

此外，在状态变更观察者回调中可以调用 SDK 接口获取服务器返回的失败原因，并在界面上做相应的处理。

API 原型

/**
 * 获取进入聊天室失败的错误码
 * 如果是手动登录，在enterChatRoom的回调函数中已有错误码。
 * 如果是断网重连，在自动登录失败时，即监听到在线状态变更为UNLOGIN时，可以采用此接口查看具体自动登录失败的原因。
 *
 * @param roomId 聊天室ID
 * @return 聊天室断网重连、自动登录失败的错误码
 */
int getEnterErrorCode(String roomId);

参数说明

错误码	说明
414	参数错误
404	聊天室不存在
403	无权限
500	服务器内部错误
13001	IM主连接状态异常
13002	聊天室状态异常
13003	黑名单用户禁止进入聊天室

示例

NIMClient.getService(ChatRoomServiceObserver.class).observeOnlineStatus(onlineStatus, register);

Observer<ChatRoomStatusChangeData> onlineStatus= new Observer<ChatRoomStatusChangeData>() {
        @Override
        public void onEvent(ChatRoomStatusChangeData data) {
            if (data.status == StatusCode.UNLOGIN) {
                int errorCode = NIMClient.getService(ChatRoomService.class).getEnterErrorCode(roomId));
                // 如果遇到错误码13001，13002，13003，403，404，414，表示无法进入聊天室，此时应该调用离开聊天室接口。
            }
            ...
        }
};

监听被踢出

当用户被踢出聊天室或者聊天室关闭时，会触发被踢回调。

注意：收到被踢出通知后，不需要再调用退出聊天室接口，SDK 会负责聊天室的退出工作。可以在踢出通知中做相关缓存的清理工作和界面操作。

API 原型

/**
 * 注册/注销被踢出聊天室观察者。
 *
 * @param observer 观察者, 参数为被踢出的事件（可以获取被踢出的聊天室ID和被踢出的原因）
 * @param register true为注册，false为注销
 */
public void observeKickOutEvent(Observer<ChatRoomKickOutEvent> observer, boolean register);

参数说明

ChatRoomKickOutEvent.ChatRoomKickOutReason 属性说明

ChatRoomKickOutEvent.ChatRoomKickOutReason 属性	说明
BE_BLACKLISTED	被拉黑了
CHAT_ROOM_INVALID	聊天室已经被关闭
ILLEGAL_STAT	当前连接状态异常
KICK_OUT_BY_CONFLICT_LOGIN	被其他端踢出
KICK_OUT_BY_MANAGER	被管理员踢出
UNKNOWN	未知（出错情况）

示例

NIMClient.getService(ChatRoomServiceObserver.class).observeKickOutEvent(kickOutObserver, register);

Observer<ChatRoomKickOutEvent> kickOutObserver = new Observer<ChatRoomKickOutEvent>() {
        @Override
        public void onEvent(ChatRoomKickOutEvent chatRoomKickOutEvent) {
            // 提示被踢出的原因（聊天室已解散、被管理员踢出、被其他端踢出等）
            // 清空缓存数据
        }
    };

离开聊天室

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

###离开单个聊天室

API 原型

/**
 * 离开聊天室
 *
 * @param roomId 聊天室ID
 */
void exitChatRoom(String roomId);

示例

NIMClient.getService(ChatRoomService.class).exitChatRoom(roomId);

离开某个类型的聊天室

API原型

/**
 * 离开聊天室
 *
 * @param mode 聊天室类型
 */
void exitChatRooms(ChatRoomModeEnum mode);

示例

NIMClient.getService(ChatRoomService.class).exitChatRoom(ChatRoomModeEnum.DEPENDENT);

聊天室消息收发

聊天室消息 ChatRoomMessage 继承自 IMMessage。新增了以下方法：

返回值	ChatRoomMessage 接口	说明
java.lang.String	getNotifyTargetTags	获取消息目标的标签表达式
CustomChatRoomMessageConfig	getChatRoomConfig()	获取聊天室消息配置
ChatRoomMessageExtension	getChatRoomMessageExtension()	获取聊天室消息扩展属性
boolean	isHighPriorityMessage()	是否是高优先级消息
void	setLocX(Double locX)	设置坐标X
void	setLocY(Double locY)	设置坐标Y
void	setLocZ(Double locZ)	设置坐标Z
void	setToAccounts(List accounts)	设置消息接收者账户列表

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

发送聊天室消息

先通过 ChatRoomMessageBuilder 提供的接口创建消息对象，然后调用 ChatRoomService 的 sendMessage 接口发送出去即可。

在聊天室发送自定义消息时，强烈建议将消息内容传入attach字段

ChatRoomMessageBuilder 接口说明

返回值	ChatRoomMessageBuilder 接口	说明
static ChatRoomMessage	createChatRoomAudioMessage(String roomId, File file, long duration)	创建一条音频消息
static ChatRoomMessage	createChatRoomAudioMessage(String roomId, File file, long duration, String nosTokenSceneKey)	创建一条音频消息并指定文件资源场景
static ChatRoomMessage	createChatRoomCustomMessage(String roomId, MsgAttachment attachment)	创建自定义消息
static ChatRoomMessage	createChatRoomCustomMessage(String roomId, MsgAttachment attachment, String nosTokenSceneKey)	创建自定义消息并指定文件资源场景
static ChatRoomMessage	createChatRoomFileMessage(String roomId, File file, String displayName)	创建一条文件消息
static ChatRoomMessage	createChatRoomFileMessage(String roomId, File file, String displayName, String nosTokenSceneKey)	创建一条文件消息并指定文件资源场景
static ChatRoomMessage	createChatRoomImageMessage(String roomId, File file, String displayName)	创建一条图片消息
static ChatRoomMessage	createChatRoomImageMessage(String roomId, File file, String displayName, String nosTokenSceneKey)	创建一条图片消息并指定文件资源场景
static ChatRoomMessage	createChatRoomLocationMessage(String roomId, double lat, double lng, String addr)	创建一条地理位置信息
static ChatRoomMessage	createChatRoomTextMessage(String roomId, String text)	创建普通文本消息
static ChatRoomMessage	createChatRoomVideoMessage(String roomId, File file, long duration, int width, int height, String displayName)	创建一条视频消息
static ChatRoomMessage	createChatRoomVideoMessage(String roomId, File file, long duration, int width, int height, String displayName, String nosTokenSceneKey)	创建一条视频消息并指定文件资源场景
static ChatRoomMessage	createEmptyChatRoomMessage(String roomId, long time)	创建一条空消息，仅设置了房间ID以及时间点，用于记录查询
static ChatRoomMessage	createTipMessage(String roomId)	创建一条提醒消息
static ChatRoomMessage	createChatRoomSpatialLocationTextMessage(String roomId, String text,Double x,Double y,Double z)	创建带位置信息的消息

nosTokenSceneKey 详见文件资源场景。

下面以文本消息发送为例，其它类型的消息发送方式与IM单聊群聊类似。

API 原型

/**
 * 创建普通文本消息
 *
 * @param roomId 聊天室ID
 * @param text   文本消息内容
 * @return ChatRoomMessage 生成的聊天室消息对象
 */
public static ChatRoomMessage createChatRoomTextMessage(String roomId, String text);

/**
 * 发送消息
 *
 * @param msg    带发送的消息体，由{@link ChatRoomMessageBuilder}构造。
 * @param resend 如果是发送失败后重发，标记为true，否则填false。
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> sendMessage(ChatRoomMessage msg, boolean resend);

示例

// 示例用roomId
String roomId = "50";
// 文本消息内容
String text = "这是聊天室文本消息";
// 创建聊天室文本消息
ChatRoomMessage message = ChatRoomMessageBuilder.createChatRoomTextMessage(roomId, text);
// 将文本消息发送出去
NIMClient.getService(ChatRoomService.class).sendMessage(message, false)
        .setCallback(new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void param) {
	            // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败
            }

            @Override
            public void onException(Throwable exception) {
               // 错误
            }
        });

特殊错误码

错误码	说明
13004	在禁言列表中，不允许发言
13006	聊天室处于整体禁言状态,只有管理员能发言

发送消息配置选项

发送聊天室消息时，可以设置配置选项 CustomChatRoomMessageConfig ，主要用于设置是否存入云端历史记录。

CustomChatRoomMessageConfig 属性	说明
skipHistory	该消息是否要保存到服务器，如果为true，通过ChatRoomService#pullMessageHistory 拉取的结果将不包含该条消息。默认为false。

示例

// 示例用roomId
String roomId = "50";
// 文本消息内容
String text = "这是聊天室文本消息";
// 创建聊天室文本消息
ChatRoomMessage message = ChatRoomMessageBuilder.createChatRoomTextMessage(roomId, text);
// 配置不存历史记录
CustomChatRoomMessageConfig config = new CustomChatRoomMessageConfig();
config.skipHistory = true;
message.setChatRoomConfig(config);
// 发送聊天室消息
NIMClient.getService(ChatRoomService.class).sendMessage(message, false);

发送带位置信息的消息

发送聊天室消息时，给消息设置坐标位置：

示例

// 示例用roomId
String roomId = "50";
// 文本消息内容
String text = "这是聊天室文本消息";
Double locationX = 100.0;
Double locationY = 100.0;
Double locationZ = 100.0;
ChatRoomMessage message = ChatRoomMessageBuilder.createChatRoomSpatialLocationTextMessage(roomId,text,locationX,locationY,locationZ);
// 发送聊天室消息
NIMClient.getService(ChatRoomService.class).sendMessage(message, false);

发送定向消息

传统聊天室场景一个人发送的消息将广播给所有人或设定的某个标签下所有人（聊天室 SDK 8.4.0 新增的聊天室标签功能）。但在某些场景下，我希望该消息仅发送给聊天室的指定人而不是所有，您可以使用聊天室定向消息能力。

定向消息不存离线，无法查询历史消息，即当发送定向消息时，接收者离线，后续重新连接后也获取不到该消息。

要发送一个定向消息，您可以在发送消息时指定接收消息的用户列表，最多指定 100 个用户：

示例

// 示例用roomId
String roomId = "50";
// 文本消息内容
String text = "这是聊天室文本消息";
// 创建聊天室文本消息
ChatRoomMessage message = ChatRoomMessageBuilder.createChatRoomTextMessage(roomId, text);
//设置定向发送的账户列表
List<String> accountList = new ArrayList<>();
accountList.add("test1");
accountList.add("test2");
message.setToAccounts(accountList);
// 发送聊天室消息
NIMClient.getService(ChatRoomService.class).sendMessage(message, false);

接收聊天室消息

通过添加消息接收观察者，在有新消息到达时，就可以接收到通知。

API 原型

/**
 * 注册/注销消息接收观察者。
 *
 * @param observer 观察者，参数为收到的消息集合
 * @param register true为注册，false为注销
 */
public void observeReceiveMessage(Observer<List<ChatRoomMessage>> observer, boolean register);

示例

Observer<List<ChatRoomMessage>> incomingChatRoomMsg = new Observer<List<ChatRoomMessage>>() {
        @Override
        public void onEvent(List<ChatRoomMessage> messages) {
            // 处理新收到的消息
        }
    };
NIMClient.getService(ChatRoomServiceObserver.class).observeReceiveMessage(incomingChatRoomMsg, register);

附件的下载，请使用ChatRoomService的downloadAttachment方法进行下载。
注册/注销消息状态变化观察者，请使用ChatRoomServiceObserver的observeMsgStatus(Observer<ChatRoomMessage> observer, boolean register)。
注册/注销消息附件上传/下载进度观察者，请使用ChatRoomServiceObserver的observeAttachmentProgress(Observer<AttachmentProgress> observer, boolean register)。

聊天室通知消息

在聊天室中进行部分操作会产生聊天室通知消息。目前当出现以下事件，会产生通知消息：

NotificationType	说明
ChatRoomClose	聊天室被关闭了
ChatRoomCommonAdd	成员设定为固定成员
ChatRoomCommonRemove	成员取消固定成员
ChatRoomInfoUpdated	聊天室信息被更新了
ChatRoomManagerAdd	设置为管理员
ChatRoomManagerRemove	取消管理员
ChatRoomMemberBlackAdd	成员被加黑
ChatRoomMemberBlackRemove	成员被取消黑名单
ChatRoomMemberExit	成员离开聊天室
ChatRoomMemberIn	成员进入聊天室
ChatRoomMemberKicked	成员被踢了
ChatRoomMemberMuteAdd	成员被设置禁言
ChatRoomMemberTempMuteAdd	新增临时禁言
ChatRoomMemberTempMuteRemove	主动解除临时禁言
ChatRoomMyRoomRoleUpdated	成员主动更新了聊天室内的角色信息(仅指nick/avator/ext)
ChatRoomQueueBatchChange	队列批量变更
ChatRoomQueueChange	队列中有变更
ChatRoomRoomDeMuted	聊天室解除全体禁言状态
ChatRoomRoomMuted	聊天室被禁言了,只有管理员可以发言,其他人都处于禁言状态
ChatRoomRecall	聊天室消息撤回
ChatRoomQueueBatchAdd	批量添加聊天室队列元素
ChatRoomTagsUpdate	更新标签

特别地，支持设置成员进出聊天室通知是否下发：

应用级别：网易云信控制台 > 选择应用 > 聊天室用户进出消息系统下发 > 开启/关闭。
单个聊天室：调用服务端API「关闭指定聊天室进出通知」。
如果希望查询聊天室消息历史时，也不要包含聊天室用户进出消息，请联系商务顾问申请关闭「聊天室用户进出消息历史存储」。

所有的聊天室通知都以消息 ChatRoomMessage 的形式封装。聊天室通知的解析如下：

聊天室通知解析步骤：

通过 ChatRoomMessage.getMsgType() 获取消息类型，若为 MsgTypeEnum.notification ，则为聊天室通知消息。
将 ChatRoomMessage.getAttachment() 获取的附件对象强类型转换为 NotificationAttachment。
通过 NotificationAttachment.getType() 获取具体的 NotificationType 。
根据对应的 NotificationType 将 ChatRoomMessage.getAttachment() 得到的附件对象强转为对应的附件类（ChatRoomNotificationAttachment或其子类）。
如果是NotificationType是ChatRoomRecall，可以将附件强转为ChatRoomRecallAttachment，通过其getMsgUuid()方法得到被撤回消息的id，从而找到对应消息并进行相应处理。

ChatRoomNotificationAttachment 参数说明：

方法	说明
getExtension()	获取聊天室通知扩展字段
getOperator()	获取该操作的发起者的账号
getOperatorNick()	获取该操作的发起者的昵称
getTargets()	获取该操作的承受者的账号列表
getTargetNicks()	获取该操作的承受者的昵称列表

ChatRoomRecallAttachment 参数说明：

方法	说明
getMsgTime()	获取被撤回消息的时间
getMsgUuid()	获取被撤回消息的uuid,可根据此id找到需要撤回的消息

示例：

public static String getNotificationText(ChatRoomNotificationAttachment attachment) {
        if (attachment == null) {
            return "";
        }
        String targets = getTargetNicks(attachment);
        String text;
        switch (attachment.getType()) {
            case ChatRoomMemberIn:
                text = buildText("欢迎", targets, "进入直播间");
                break;
            case ChatRoomMemberExit:
                text = buildText(targets, "离开了直播间");
                break;
            case ChatRoomMemberBlackAdd:
                text = buildText(targets, "被管理员拉入黑名单");
                break;
            case ChatRoomMemberBlackRemove:
                text = buildText(targets, "被管理员解除拉黑");
                break;
            case ChatRoomMemberMuteAdd:
                text = buildText(targets, "被管理员禁言");
                break;
            case ChatRoomMemberMuteRemove:
                text = buildText(targets, "被管理员解除禁言");
                break;
            case ChatRoomManagerAdd:
                text = buildText(targets, "被任命管理员身份");
                break;
            case ChatRoomManagerRemove:
                text = buildText(targets, "被解除管理员身份");
                break;
            case ChatRoomCommonAdd:
                text = buildText(targets, "被设为普通成员");
                break;
            case ChatRoomCommonRemove:
                text = buildText(targets, "被取消普通成员");
                break;
            case ChatRoomClose:
                text = buildText("直播间被关闭");
                break;
            case ChatRoomInfoUpdated:
                text = buildText("直播间信息已更新");
                break;
            case ChatRoomMemberKicked:
                text = buildText(targets, "被踢出直播间");
                break;
            case ChatRoomMemberTempMuteAdd:
                text = buildText(targets, "被临时禁言");
                break;
            case ChatRoomMemberTempMuteRemove:
                text = buildText(targets, "被解除临时禁言");
                break;
            case ChatRoomMyRoomRoleUpdated:
                text = buildText(targets, "更新了自己的角色信息");
                break;
            case ChatRoomQueueChange:
                text = buildText(targets, "麦序队列中有变更");
                break;
            case ChatRoomRoomMuted:
                text = buildText("全体禁言，管理员可发言");
                break;
            case ChatRoomRoomDeMuted:
                text = buildText("解除全体禁言");
                break;
            case ChatRoomQueueBatchChange:
                text = buildText("批量变更");
                break;
            default:
                text = attachment.toString();
                break;
        }
        return text;
    }

设置聊天室消息扩展字段

聊天室消息ChatRoomMessage继承自IMMessage，通过setRemoteExtension方法设置聊天室消息的服务端扩展字段。服务端扩展字段只能在消息发送前设置，会同步到其他端。

聊天室消息没有客户端扩展字段。
扩展字段，请使用JSON格式封装，并传入非格式化的JSON字符串，最大长度1024字节。

查询云端历史消息

聊天室没有离线消息和漫游消息。可以通过下面的接口查询聊天室消息历史。服务器只保存最近10天的聊天室消息记录。但是10天之前发送的文件(例如：图片、音频、视频等)，其url链接地址仍然是有效的(不过开发者需要自行保存这些url，因为无法通过已过期的消息来查询这些文件url)。如需延长「聊天室历史消息天数」，请联系商务顾问。

查询云端历史消息

以 startTime（单位毫秒）为查询起点，选择查询方向往前或者往后拉取 limit 条消息。拉取到的消息中也包含聊天室通知消息。

查询结果排序与查询方向有关，若方向往前，则结果排序按时间逆序，反之则结果排序按时间顺序。

/**
 * 获取历史消息,可选择给定时间往前或者往后查询，若方向往前，则结果排序按时间逆序，反之则结果排序按时间顺序。
 *
 * @return InvocationFuture 可以设置回调函数。回调中返回历史消息列表
 */
InvocationFuture<List<ChatRoomMessage>> pullMessageHistoryEx(String roomId, long startTime, int limit, QueryDirectionEnum direction);

参数说明

参数	说明
roomId	聊天室 id
startTime	时间戳，单位毫秒
limit	可拉取的消息数量，最多100条
direction	查询方向

QueryDirectionEnum 属性说明

QueryDirectionEnum 属性	说明
QUERY_OLD	查询比锚点时间更早的消息
QUERY_NEW	查询比锚点时间更晚的消息

示例

long startTime = System.currentTimeMillis();
// 从现在开始，往 QueryDirectionEnum.QUERY_OLD 查询100条
NIMClient.getService(ChatRoomService.class).pullMessageHistoryEx(roomId, startTime, 100, QueryDirectionEnum.QUERY_OLD);

按消息类型查询

以 startTime（单位毫秒）为时间戳，选择查询方向，指定一种或多种类型的消息，往前或者往后拉取 limit 条消息。

API 原型

/**
 * 获取历史消息,可选择给定时间往前或者往后查询，以及查询指定一种或多种类型的消息。
 *
 * 若方向往前，则结果排序按时间逆序，反之则结果排序按时间顺序
 *
 * 消息类型仅支持 0:文本，1:图片，2:语音，3:视频，4:地理位置，5:通知，6:文件，10:提示，11:Robot，100:自定义，其它为非法参数
 *
 * @param roomId    聊天室id
 * @param startTime 时间戳，单位毫秒
 * @param limit     可拉取的消息数量
 * @param direction 查询方向
 * @param typeEnums 消息类型，数组
 * @return InvocationFuture 可以设置回调函数。回调中返回历史消息列表
 */
InvocationFuture<List<ChatRoomMessage>> pullMessageHistoryExType(String roomId, long startTime, int limit, QueryDirectionEnum direction, MsgTypeEnum[] typeEnums);

参数说明

参数	说明
roomId	聊天室 id
startTime	时间戳，单位毫秒
limit	可拉取的消息数量
direction	查询方向
typeEnums	查询消息类型，数组

示例

MsgTypeEnum[] typeEnums = new MsgTypeEnum[]{MsgTypeEnum.text, MsgTypeEnum.image};
int[] types = new int[]{MsgTypeEnum.text.getValue(), MsgTypeEnum.image.getValue()};
long anchorTime = System.currentTimeMillis();

checkResponse(NIMClient.getService(ChatRoomService.class).pullMessageHistoryExType(Constants.CHATROOM_ID, anchorTime, 50, QueryDirectionEnum.QUERY_OLD, typeEnums), new TestRequestResult.Callback<List<ChatRoomMessage>>() {
    @Override
    public boolean onResponseData(int code, List<ChatRoomMessage> data) {
        ...
    }
});

根据标签查询历史消息

根据标签（Tags）在云端查询聊天室的历史消息。

以 fromTime 和 toTime（单位毫秒）为时间戳，选择查询方向，指定一种或多种标签和消息类型，往前或者往后拉取 limit 条消息。

API 原型

/**
 * 通过标签从云端拉取消息
 * @param param 参数
 * @return InvocationFuture 可以设置回调函数。回调中返回历史消息列表
 */
InvocationFuture<List<ChatRoomMessage>> getMessagesByTags(GetMessagesByTagsParam param);

参数说明

参数	类型	说明
roomId	long	聊天室 ID（必填）
tags	List<String>	标签列表，支持传入多个标签同时查询（必填）
types	List<`MsgTypeEnum`>	消息类型列表，查询指定消息类型的消息，默认查询全部消息类型
fromTime	Long	起始时间，单位毫秒
toTime	Long	结束时间，单位毫秒
limit	Integer	可查询的最大消息数量
reverse	Boolean	查询方向

示例代码

NIMClient.getService(ChatRoomService.class).getMessagesByTags(param).setCallback(new RequestCallback<List<ChatRoomMessage>>() {
    @Override
    public void onSuccess(List<ChatRoomMessage> result) {
        // 获取消息成功
    }

    @Override
    public void onFailed(int code) {
        // 获取消息失败
    }

    @Override
    public void onException(Throwable exception) {
        // 获取消息出现异常
    }
});

聊天室信息管理

获取聊天室信息

此接口可以向服务器获取聊天室信息。SDK 不提供聊天室信息的缓存，开发者可根据需要自己做缓存。聊天室基本信息的扩展字段需要在服务器端设置，客户端 SDK 只提供查询。

API 原型

/**
 * 获取当前聊天室信息
 *
 * @param roomId 聊天室id
 * @return InvocationFuture 可以设置回调函数。回调中返回聊天室的信息
 */
InvocationFuture<ChatRoomInfo> fetchRoomInfo(String roomId);

示例

// roomId为聊天室ID
NIMClient.getService(ChatRoomService.class).fetchRoomInfo(roomId).setCallback(new RequestCallback<ChatRoomInfo>() {
    @Override
    public void onSuccess(ChatRoomInfo param) {
        // 成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
        // 错误
    }
});

修改聊天室信息

支持修改聊天室信息，只有创建者和管理员拥有权限修改聊天室信息。可以设置修改是否通知，若设置通知，聊天室内会收到类型为NotificationType#ChatRoomInfoUpdated的消息。

API 原型

/**
 * 更新聊天室信息
 *
 * @param roomId             聊天室id
 * @param chatRoomUpdateInfo 可更新的聊天室信息
 * @param needNotify         是否通知
 * @param notifyExtension    更新聊天室信息操作的扩展字段，这个字段会放到更新聊天室信息通知消息的扩展字段中
 * @return InvocationFuture 可以设置回调函数。更新聊天室信息完成之后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> updateRoomInfo(String roomId, ChatRoomUpdateInfo chatRoomUpdateInfo, boolean needNotify, Map<String, Object> notifyExtension);

/**
 * 更新聊天室信息
 *
 * @param roomId             聊天室id
 * @param chatRoomUpdateInfo 可更新的聊天室信息
 * @param needNotify         是否通知
 * @param notifyExtension    更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
 * @param antiSpamConfig     反垃圾配置参数
 * @return InvocationFuture 可以设置回调函数。更新聊天室信息完成之后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> updateRoomInfo(String roomId, ChatRoomUpdateInfo chatRoomUpdateInfo, boolean needNotify, Map<String, Object> notifyExtension,AntiSpamConfig antiSpamConfig);

参数说明

参数	说明
roomId	聊天室id
chatRoomUpdateInfo	可更新的聊天室信息
needNotify	是否通知
notifyExtension	更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
antiSpamConfig	反垃圾配置参数

示例

// 以更新聊天室信息为例
ChatRoomUpdateInfo updateInfo = new ChatRoomUpdateInfo();
updateInfo.setName("新聊天室名称");

NIMClient.getService(ChatRoomService.class).updateRoomInfo(roomId, updateInfo, false, "")
         .setCallback(new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
                // 成功
            }

            @Override
            public void onFailed(int i) {
                // 失败
            }

            @Override
            public void onException(Throwable throwable) {
				// 错误
            }
        });

聊天室成员管理

聊天室成员概述

关于聊天室成员：

聊天室成员包括固定成员和非固定成员(临时成员/游客)。固定成员上限是1000个。
固定成员包括四种类型：创建者、管理员、普通用户、受限用户。受限用户又包括：黑名单用户和永久禁言用户。
除了创建者，其他成员刚加入时，默认都是游客。
如果游客被设置为管理员，再被取消管理员，则变为普通用户(而不是游客)。
要将管理员变成普通用户，直接取消其管理员权限即可。不能直接将管理员设置为普通成员。
只有创建者可以对管理员进行操作，管理员不能对创建者和其他管理员进行操作。
普通用户被取消身份后变为游客。
游客被设置为黑名单用户后变为固定成员(同时会被服务器断开连接并且无法进入聊天室，除非被解除黑名单)。解除黑名单后变为游客。
永久禁言后，身份变为固定成员。解除永久禁言后，身份变为游客。解除永久禁言后，不影响临时禁言的到期时间。
临时禁言的设置和解除不会改变成员的身份。如果重复设置临时禁言，则后一次设置会覆盖前一次设置的到期时间(不会累积)。
游客只有在线时才属于聊天室的非固定成员；游客进入聊天室又退出后，不属于聊天室的任何成员(和聊天室没有任何关系)。

聊天室成员原型：

返回值	ChatRoomMember 接口	说明
String	getAccount()	获取成员帐号
String	getAvatar()	获取头像。可从 NimUserInfo 中取 avatar，可以由用户进聊天室时提交
long	getEnterTime()	获取进入聊天室时间。对于离线成员该字段为空
Map	getExtension()	获取扩展字段。长度限制 4k，可以由用户进聊天室时提交
int	getMemberLevel()	获取成员级别。大于等于 0 表示用户开发者可以自定义的级别
MemberType	getMemberType()	获取成员类型。成员类型：主要分为游客和非游客
String	getNick()	获取昵称。可从 NimUserInfo 中取，也可以由用户进聊天室时提交
String	getRoomId()	获取聊天室 id
long	getTempMuteDuration()	获取临时禁言解除时长，单位秒
long	getUpdateTime()	获取固定成员的记录更新时间，用于固定成员列表的排列查询
boolean	isInBlackList()	判断用户是否在黑名单中
boolean	isMuted()	判断用户是否被禁言
boolean	isOnline()	判断用户是否处于在线状态仅特殊成员才可能离线，对游客/匿名用户而言只能是在线
boolean	isTempMuted()	判断用户是否被临时禁言
boolean	isValid()	判断是否有效
void	setAccount(String account)	设置用户帐号
void	setAvatar(String avatar)	设置成员头像
void	setEnterTime(long enterTime)	设置进入聊天室时间
void	setExtension(Map extension)	设置扩展字段
void	setInBlackList(boolean inBlackList)	设置是否在黑名单中
void	setMemberLevel(int memberLevel)	设置成员等级
void	setMemberType(MemberType type)	设置成员类型
void	setMuted(boolean muted)	设置是否禁言
void	setNick(String nick)	设置成员昵称
void	setOnline(boolean online)	设置在线状态
void	setRoomId(String roomId)	设置聊天室id
void	setTempMuted(boolean tempMuted)	设置是否临时禁言
void	setTempMuteDuration(long tempMuteDuration)	设置临时禁言解除时长
void	setUpdateTime(long updateTime)	设置固定成员的更新时间
void	setValid(boolean valid)	设置是否有效

关于MemberQueryType 属性说明：

MemberQueryType 属性	说明
GUEST	非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限)
NORMAL	固定成员（包括创建者,管理员,普通等级用户,受限用户(禁言+黑名单), 即使非在线也可以在列表中看到,有数量限制）
ONLINE_NORMAL	仅在线的固定成员
GUEST_DESC	非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限) 按照进入聊天室时间倒序排序，进入时间越晚的越靠前
GUEST_ASC	非固定成员 (又称临时成员,只有在线时才能在列表中看到,数量无上限) 按照进入聊天室时间顺序排序，进入时间越早的越靠前
UNKNOWN	未知

获取聊天室成员

分页获取聊天室成员

此接口可以远程获取聊天室成员列表，SDK 不会缓存聊天室成员列表，开发者需要根据业务自己做好缓存。

API 原型

/**
 * 获取聊天室成员信息
 *
 * @param roomId          聊天室id
 * @param memberQueryType 成员查询类型。
 * @param time            固定成员列表用updateTime,
 *                        游客列表用进入enterTime，
 *                        填0会使用当前服务器最新时间开始查询，即第一页，单位毫秒
 * @param limit           人数限制
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息列表
 */
InvocationFuture<List<ChatRoomMember>> fetchRoomMembers(String roomId, MemberQueryType memberQueryType, long time, int limit);

参数说明

参数	说明
roomId	聊天室id
memberQueryType	成员查询类型。见 MemberQueryType
time	固定成员列表用 updateTime, 游客列表用进入 enterTime，填 0 会使用当前服务器最新时间开始查询，即第一页，单位毫秒
limit	人数限制

示例

// 以游客为例，从最新时间开始，查询10条
NIMClient.getService(ChatRoomService.class).fetchRoomMembers(roomId, MemberQueryType.GUEST, 0, 10).setCallback(new RequestCallbackWrapper<List<ChatRoomMember>>() {
    @Override
    public void onResult(int code, List<ChatRoomMember> result, Throwable exception) {
       ...
    }
});

获取指定聊天室成员

/**
 * 根据用户id获取聊天室成员信息
 *
 * @param roomId   聊天室id
 * @param accounts 成员帐号列表
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息列表
 */
InvocationFuture<List<ChatRoomMember>> fetchRoomMembersByIds(String roomId, List<String> accounts)

示例

List<String> accounts = new ArrayList<>();
accounts.add(account);

NIMClient.getService(ChatRoomService.class).fetchRoomMembersByIds(roomId, accounts)
	     .setCallback(new RequestCallbackWrapper<List<ChatRoomMember>>() { ... });

获取聊天室机器人列表

聊天室独立模式下，由于不存在 IM 连接，无法同步机器人列表，因此需要调用此接口拉取机器人列表。建议在进入聊天室之后调用此接口，并且做好频控措施，以防用户频繁切换聊天室时该接口频率过高。

API 原型

/**
 * 独立聊天室场景下，获取当前全部聊天室机器人
 *
 * @param roomId 当前聊天室id
 * @return InvocationFuture 可设置回调函数。回调中返回操作成功或者失败具体的错误码。
 */
InvocationFuture<List<NimRobotInfo>> pullAllRobots(String roomId);

示例


/**
 * 拉取机器人信息最短间隔 5min
 */
private static final long MIN_PULL_ROBOT_INTERNAL = 5 * 60 * 1000;

private long lastTime = 0L;

/**
 *  独立模式进入聊天室之后调用
 *
 *  最短时间间隔 MIN_PULL_ROBOT_INTERNAL
 * @param roomId
 */
public void pullRobotListIndependent(String roomId) {
    if (System.currentTimeMillis() - lastTime < MIN_PULL_ROBOT_INTERNAL) {
        return;
    }

    NIMClient.getService(ChatRoomService.class).pullAllRobots(roomId).setCallback(new RequestCallbackWrapper<List<NimRobotInfo>>() {
        @Override
        public void onResult(int code, List<NimRobotInfo> result, Throwable exception) {
            if (code == 200 && result != null) {
                lastTime = System.currentTimeMillis();
                // 更新缓存
            }
        }
    });
}

修改自身信息

支持更新本人聊天室成员信息。目前只支持昵称，头像，扩展字段和反垃圾配置项的更新。可以设置更新是否通知，若设置通知，聊天室内会收到类型为NotificationType#ChatRoomMyRoomRoleUpdated的消息。

/**
 * 更新本人在聊天室内的信息
 *
 * @param roomId               聊天室id
 * @param chatRoomMemberUpdate 可更新的本人角色信息
 * @param needNotify           是否通知
 * @param notifyExtension      更新操作扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
 * @return InvocationFuture     可以设置回调函数。更新信息完成之后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> updateMyRoomRole(String roomId, ChatRoomMemberUpdate chatRoomMemberUpdate, boolean needNotify, Map<String, Object> notifyExtension);

/**
 * 更新本人在聊天室内的信息
 *
 * @param roomId               聊天室id
 * @param chatRoomMemberUpdate 可更新的本人角色信息
 * @param needNotify           是否通知
 * @param notifyExtension      更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中,最大长度2k
 * @param antiSpamConfig       反垃圾配置参数
 * @return InvocationFuture     可以设置回调函数。更新信息完成之后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> updateMyRoomRole(String roomId, ChatRoomMemberUpdate chatRoomMemberUpdate, boolean needNotify, Map<String, Object> notifyExtension,AntiSpamConfig antiSpamConfig);

参数说明

参数	说明
roomId	聊天室 id
chatRoomMemberUpdate	可更新的本人角色信息
needNotify	是否通知
notifyExtension	更新操作扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
antiSpamConfig	反垃圾配置参数

ChatRoomMemberUpdate 接口说明

返回值	ChatRoomMemberUpdate 接口	说明
String	getAvatar()	获取聊天室内的头像
Map	getExtension()	获取扩展字段
String	getNick()	获取聊天室内的昵称
boolean	isNeedSave()	更新的信息是否需要做持久化，只对固定成员生效，默认 false，v3.8.0增加
void	setAvatar(String avatar)	设置聊天室内的头像
void	setExtension(Map extension)	设置扩展字段，长度限制 2048
void	setNeedSave(boolean needSave)	设置是否需要持久化，只对固定成员生效，v3.8.0增加
void	setNick(String nick)	设置聊天室内的昵称

示例

// 以更新自己的昵称为例
ChatRoomMemberUpdate update = new ChatRoomMemberUpdate();
update.setNick("我的新昵称");

NIMClient.getService(ChatRoomService.class).updateMyRoomRole(roomId, update, false, "").setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        // 成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
		// 错误
    }
});

添加/移除管理员

/**
 * 设为/取消聊天室管理员
 *
 * @param isAdd        true:设为, false:取消
 * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
 */
InvocationFuture<ChatRoomMember> markChatRoomManager(boolean isAdd, MemberOption memberOption);

参数说明

返回值	MemberOption 接口	说明
String	getAccount()	获取成员帐号
Map	getNotifyExtension()	获取通知事件中开发者定义的扩展字段
String	getRoomId()	获取聊天室id
void	setAccount(String account)	设置成员帐号
void	setNotifyExtension(Map notifyExtension)	设置通知事件中的扩展字段
void	setRoomId(String roomId)	设置聊天室 id

示例

// 以设置为管理员为例
NIMClient.getService(ChatRoomService.class)
        .markChatRoomManager(true, new MemberOption(roomId, account))
        .setCallback(new RequestCallback<ChatRoomMember>() {
            @Override
            public void onSuccess(ChatRoomMember param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

添加/移除普通成员

/**
 * 设为/取消聊天室普通成员
 *
 * @param isAdd        true:设为, false:取消
 * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
 */
InvocationFuture<ChatRoomMember> markNormalMember(boolean isAdd, MemberOption memberOption);

示例

// 以设为普通成员为例
NIMClient.getService(ChatRoomService.class).markNormalMember(true, new MemberOption(roomId, account)))
        .setCallback(new RequestCallback<ChatRoomMember>() {
            @Override
            public void onSuccess(ChatRoomMember param) {
               // 成功
            }

            @Override
            public void onFailed(int code) {
				// 失败
            }

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

添加/移除黑名单用户

/**
 * 添加/移出聊天室黑名单
 *
 * @param isAdd        true:添加, false:移出
 * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
 */
InvocationFuture<ChatRoomMember> markChatRoomBlackList(boolean isAdd, MemberOption memberOption);

示例

// 以添加到黑名单为例
MemberOption option = new MemberOption(roomId, account);
NIMClient.getService(ChatRoomService.class).markChatRoomBlackList(true, option).setCallback(new RequestCallback<ChatRoomMember>() {
        @Override
        public void onSuccess(ChatRoomMember param) {
        // 成功
        }

        @Override
        public void onFailed(int code) {
        // 失败
        }

        @Override
        public void onException(Throwable exception) {
		// 错误
        }
});

添加/移除禁言用户

添加到禁言名单时, 会收到类型为 ChatRoomMemberMuteAdd 的聊天室通知消息。

取消禁言时, 会收到类型为 ChatRoomMemberMuteRemove 的聊天室通知消息。

/**
 * 添加到禁言名单/取消禁言
 *
 * @param isAdd        true:添加, false:取消
 * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
 * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
 */
InvocationFuture<ChatRoomMember> markChatRoomMutedList(boolean isAdd, MemberOption memberOption);

示例

// 以添加到禁言名单为例
MemberOption option = new MemberOption(roomId, account);
NIMClient.getService(ChatRoomService.class).markChatRoomMutedList(true, option)
         .setCallback(new RequestCallback<ChatRoomMember>() {
            @Override
            public void onSuccess(ChatRoomMember param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败
            }

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

踢出成员

踢出成员。仅管理员可以踢；如目标是管理员，仅创建者可以踢。

当有人被踢出聊天室时，会收到类型为 ChatRoomMemberKicked 的聊天室通知消息。

可以添加被踢通知扩展字段，这个字段会放到被踢通知的扩展字段中。通知扩展字段最长 1K；扩展字段需要传入 Map<String,Object>， SDK 会负责转成 Json String。

/**
 * 踢掉特定成员
 *
 * @return InvocationFuture 可以设置回调函数。踢掉成员完成之后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> kickMember(String roomId, String account, Map<String, Object> notifyExtension);

参数说明

参数	说明
roomId	聊天室 id
account	踢出成员帐号。仅管理员可以踢；如目标是管理员仅创建者可以踢
notifyExtension	被踢通知扩展字段，这个字段会放到被踢通知的扩展字段中

示例

Map<String, Object> reason = new HashMap<>();
reason.put("reason", "kick");
NIMClient.getService(ChatRoomService.class).kickMember(roomId, account, reason).setCallback(new RequestCallback<Void>() { ... });

临时禁言成员

设置临时禁言时, 会收到类型为 ChatRoomMemberTempMuteAdd 的聊天室通知消息。

取消临时禁言时, 会收到类型为 ChatRoomMemberTempMuteRemove 的聊天室通知消息。

聊天室支持设置临时禁言，禁言时长时间到了，自动取消禁言。设置临时禁言成功后的通知消息中，包含的时长是禁言剩余时长。若设置禁言时长为0，表示取消临时禁言。若第一次设置的禁言时长还没结束，又设置第二次临时禁言，以第二次设置的时间开始计时。

/**
 * 设置聊天室成员临时禁言
 *
 * @return InvocationFuture 可以设置回调函数。如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> markChatRoomTempMute(boolean needNotify, long duration, MemberOption memberOption);

参数说明

参数	说明
needNotify	是否需要发送广播通知，true：通知，false：不通知
duration	禁言时长,单位秒
memberOption	请求参数，包含聊天室 id，帐号 id 以及可选的扩展字段

示例

// 以发送广播通知，并且临时禁言10秒为例
MemberOption option = new MemberOption(roomId, account);
NIMClient.getService(ChatRoomService.class).markChatRoomTempMute(true, 10, option)
        .setCallback(new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败
            }

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

聊天室队列

聊天室提供队列服务，可结合互动直播连麦场景中的麦位管理使用。权限由 ChatRoomInfo.getQueueLevel() 决定，可以通过updateChatroomInfo进行修改。默认情况下，所有用户都可以调用接口修改队列内容。

获取聊天室队列

/**
 * 聊天室队列服务：排序列出所有队列元素
 *
 * @param roomId 聊天室id
 * @return InvocationFuture 可设置回调函数。回调中返回所有排列的队列元素键值对。
 */
InvocationFuture<List<Entry<String, String>>> fetchQueue(String roomId);

示例

NIMClient.getService(ChatRoomService.class).fetchQueue(roomId).setCallback(new RequestCallback<List<Entry<String, String>>>() {
    @Override
    public void onSuccess(List<Entry<String, String>> param) {
        // 成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
		// 错误
    }
});

加入或者更新队列元素

用户使用该接口加入或更新的元素，当 isTransient 参数为 true 时，表示当该用户掉线或退出聊天室时，服务器会自动删除该用户加入或更新的元素。

同时，服务器将发出聊天室通知消息，通知消息的类型为 NotificationType#ChatRoomQueueBatchChange，通知消息的附件类型为 ChatRoomPartClearAttachment，该通知消息属于队列变更通知，所以附件类型中包含了队列变更类型 ChatRoomQueueChangeType#PARTCLEAR。

/**
 * 聊天室队列服务：加入或者更新队列元素，支持当用户掉线或退出聊天室后，是否删除这个元素
 *
 * @param roomId      聊天室id
 * @param key         新元素（或待更新元素）的唯一键
 * @param value       新元素（待待更新元素）的内容
 * @param isTransient true表示当提交这个新元素的用户从聊天室掉线或退出的时候，需要删除这个元素；默认false表示不删除
 * @param elementAccid 队列元素所属账号，默认不传表示队列元素属于当前操作人，管理员可以指定队列元素归属于其他合法账号
 * @return InvocationFuture 可以设置回调函数。回调中返回操作成功或者失败具体的错误码。
 */
InvocationFuture<Void> updateQueue(String roomId, String key, String value, boolean isTransient, String elementAccid);

参数说明

参数	说明
roomId	聊天室 id
key	新元素（或待更新元素）的唯一键
value	新元素（待待更新元素）的内容
isTransient	(可选参数) true 表示当提交这个新元素的用户从聊天室掉线或退出的时候，需要删除这个元素；默认false表示不删除
elementAccid	(可选参数) 队列元素所属账号，默认不传表示队列元素属于当前操作人，管理员可以指定队列元素归属于其他合法账号

ChatRoomPartClearAttachment 说明

返回值	ChatRoomPartClearAttachment 接口	说明
ChatRoomQueueChangeType	getChatRoomQueueChangeType()	返回队列变更类型，值为 ChatRoomQueueChangeType.PARTCLEAR
Map	getContentMap()	当用户掉线或退出聊天室时，返回用户使用 updateQueueEx 接口，并设置 isTransient 参数为true 时，加入或更新的元素

示例

NIMClient.getService(ChatRoomService.class)
         .updateQueueEx(roomId, "this is key", "this is value", true)
         .setCallback(new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败
            }

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

批量更新队列元素

只会更新已经存在的key，不会加入新元素。

/**
 * 聊天室队列服务 ： 批量更新元素
 *
 * @param roomId     聊天室id
 * @param queues     待更新的队列元素
 * @param needNotify 是否需要发送广播通知
 * @param notifyExt  通知中的自定义字段，最大长度2k
 * @return 不存在的元素elementKey列表
 */
InvocationFuture<List<String>> batchUpdateQueue(String roomId, List<Entry<String, String>> queues, boolean needNotify, Map<String, Object> notifyExt);

示例

List<Entry<String, String>> queues = new ArrayList<>();
        queues.add(new Entry<String, String>("key", "value1"));
        queues.add(new Entry<String, String>("key1", "value2"));
        queues.add(new Entry<String, String>("key2", "value3" ));

        Map<String, Object> notifyExt = new HashMap<>();
        notifyExt.put("notes", "notes_vaules");
        NIMClient.getService(ChatRoomService.class).batchUpdateQueue(roomId, queues, true, notifyExt).setCallback(new RequestCallback<List<String>>() {
            @Override
            public void onSuccess(List<String> result) {
               // 成功
               //result :不存在的元素的key list
            }

            @Override
            public void onFailed(int code) {
               //失败
            }

            @Override
            public void onException(Throwable exception) {
             //异常
               
            }
        });

移除指定队列元素

key是唯一键。key 若为 null，则表示取出头元素。若不为 null，则表示取出指定元素。

/**
 * 聊天室队列服务：取出队列头部或者指定元素
 *
 * @return InvocationFuture 可以设置回调函数。如果元素存在或者队列不为空，那么回调中返回元素的键值对，否则返回失败错误码。
 */
InvocationFuture<Entry<String, String>> pollQueue(String roomId, String key);

参数说明

参数	说明
roomId	聊天室 id
key	需要取出的元素的唯一键。若为 null，则表示取出队头元素

示例

NIMClient.getService(ChatRoomService.class).pollQueue(roomId, "this is key"
        .setCallback(new RequestCallback<Entry<String, String>>() {
            @Override
            public void onSuccess(Entry<String, String> param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 错误
            }

            @Override
            public void onException(Throwable exception) {
				// 失败
            }
        });

清空队列

/**
 * 聊天室队列服务：删除队列
 *
 * @param roomId 聊天室id
 * @return InvocationFuture 可设置回调函数。回调中返回操作成功或者失败具体的错误码。
 */
InvocationFuture<Void> dropQueue(String roomId);

示例

NIMClient.getService(ChatRoomService.class).dropQueue(roomId).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        // 成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
		// 错误
    }
});

聊天室标签

监听聊天室标签变更

监听聊天室标签变更事件后，当聊天室标签别修改后，会受到回调，包含变更标签的聊天室 ID 和变更后的标签信息。

原型

/**
 * 注册/注销标签更新观察者
 *
 * @param observer 观察者
 * @param register true为注册，false为注销
 */
public void observeTagsUpdate(Observer<ChatRoomTagsUpdateEvent> observer, boolean register);

更新聊天室标签

/**
 * 更新聊天室标签
 * @param roomId 当前聊天室id
 * @param tagsInfo 标签信息
 * @return
 */
InvocationFuture<Void> updateChatRoomTags(String roomId, ChatRoomTagsInfo tagsInfo);

ChatRoomTagsInfo 参数说明：

参数	说明
tags	可以设置多个，json_array格式，例子：["tag1", "tag2"]，如果要删除，则null即可，上传空数组代表启用标签功能但是不属于任何标签组
notifyTargetTags	更新标签的通知的目标标签，是一个标签表达式，同时也会改变该连接掉线时的通知对象，传null或空字符串表示允许通知聊天室所有成员，具体见标签表达式
needNotify	true表示，如果需要通知，则会产生一条通知
ext	通知扩展字段

此文档是否对你有帮助？

有帮助

我要吐槽

文档反馈

在线咨询

功能概述
进入聊天室
鉴权方式
非独立模式
独立模式
支持聊天室空间消息
更新位置信息
聊天室多端登录
监听聊天室连接变化
监听被踢出
离开聊天室
离开某个类型的聊天室
聊天室消息收发
发送聊天室消息
发送消息配置选项
发送带位置信息的消息
发送定向消息
接收聊天室消息
聊天室通知消息
设置聊天室消息扩展字段
查询云端历史消息
查询云端历史消息
按消息类型查询
根据标签查询历史消息
聊天室信息管理
获取聊天室信息
修改聊天室信息
聊天室成员管理
聊天室成员概述
获取聊天室成员
分页获取聊天室成员
获取指定聊天室成员
获取聊天室机器人列表
修改自身信息
添加/移除管理员
添加/移除普通成员
添加/移除黑名单用户
添加/移除禁言用户
踢出成员
临时禁言成员
聊天室队列
获取聊天室队列
加入或者更新队列元素
批量更新队列元素
移除指定队列元素
清空队列
聊天室标签
监听聊天室标签变更
更新聊天室标签