聊天室

聊天室功能概述

聊天室分类:

聊天室分为独立模式和非独立模式。独立模式不依赖 IM 登录,非独立模式必须依赖 IM 登录。其中,独立模式又可以分为匿名模式登录和非匿名模式登录。

聊天室分类 细分 说明
独立模式 匿名模式/非匿名模式 不依赖 IM 登录
非独立模式 依赖 IM 登录

聊天室模型特点:

进入聊天室

非独立模式进入聊天室

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

EnterChatRoomData部分参数说明:

返回值 EnterChatRoomData参数 说明
String getRoomId() 获取聊天室 ID
void setRoomId(String roomId) 设置聊天室 ID
void setNick(String nick) 设置聊天室展示的昵称(可选字段),
如果不填则直接使用 NimUserInfo 的数据
void setAvatar(String avatar) 设置聊天室展示的头像
void setExtension(Map
extension)
设置进入聊天室后展示用户信息的扩展字段,长度限制 4k。
设置后在获取聊天室成员信息 ChatRoomMember 时可以查询到此扩展字段;
此外,在收到聊天室消息时,可以从 ChatRoomMessage#ChatRoomMessageExtension#getSenderExtension
中获取消息发送者的用户信息扩展字段。
若没有设置,则这个字段为 null。
void setNotifyExtension
(Map
notifyExtension)
设置聊天室通知消息扩展字段,长度限制 1k。
设置后,在收到聊天室通知消息时的
ChatRoomNotificationAttachment 中可以查询到此扩展字段。
// 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) {
        // 错误
    }
});

注意:当进入聊天室后,再发生掉线问题时,SDK会自动进行重连,无需开发者再次调用进入聊天室接口。 注意:进入聊天室前,必须先成功登录 IM,否则会登录失败,并上报错误码1000。

独立模式进入聊天室

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

/**
 * 进入聊天室
 *
 * @param roomData   聊天室基本数据(聊天室ID必填)
 * @param retryCount 如果进入失败,重试次数
 * @return InvocationFuture 可以设置回调函数。回调中返回聊天室基本信息
 */
AbortableFuture<EnterChatRoomResultData> enterChatRoomEx(EnterChatRoomData roomData, int retryCount);
参数 说明
cb 如果是独立模式,必须提供回调函数,用于SDK向APP获取聊天室地址信息的数据
account 独立登录的账号,可以不填。不填即为匿名登录
token 独立登录的密码

EnterChatRoomData部分参数说明:

返回值 EnterChatRoomData参数 说明
boolean isIndependentMode() 是否是独立登录聊天室
String getAccount() 获取独立登录模式的用户账号,null表示匿名登录
String getToken() 获取独立登录模式的用户密码
ChatRoomIndependentCallback getIndependentModeCallback() 获取独立模式的回调
void setIndependentMode
(ChatRoomIndependentCallback cb,
String account, String token)
设置聊天室独立模式。
如果是独立模式,必须提供回调函数,用于SDK向APP获取聊天室地址信息的数据。
如果SDK无法通过此回调函数获取聊天室地址(null或者有异常),会返回错误码1001
独立登录的账号,可以不填。不填即为匿名登录。

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

// 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) {
        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) {
        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 有聊天室断线重连机制,会在网络恢复后做重连并自动登录,如果自动登录失败,则会有在线状态变更通知,见监听聊天室在线状态。 如果为在线状态变更为 UNLOGIN 则表示自动登录失败(例如账号被群主拉黑,聊天室状态异常等),那么在状态变更观察者回调中可以调用 SDK 接口获取服务器返回的失败原因,并在界面上做相应的处理(比如退出聊天室)。

/**
 * 获取进入聊天室失败的错误码
 * 如果是手动登录,在enterChatRoom的回调函数中已有错误码。
 * 如果是断网重连,在自动登录失败时,即监听到在线状态变更为UNLOGIN时,可以采用此接口查看具体自动登录失败的原因。
 *
 * @param roomId 聊天室ID
 * @return 聊天室断网重连、自动登录失败的错误码
 */
int getEnterErrorCode(String roomId);
错误码 说明
414 参数错误
404 聊天室不存在
403 无权限
500 服务器内部错误
13001 IM主连接状态异常
13002 聊天室状态异常
13003 黑名单用户禁止进入聊天室
// code表示进入聊天室失败的错误码
int code = NIMClient.getService(ChatRoomService.class).getEnterErrorCode(roomId);

离开聊天室

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

/**
 * 离开聊天室
 *
 * @param roomId 聊天室ID
 */
void exitChatRoom(String roomId);
NIMClient.getService(ChatRoomService.class).exitChatRoom(roomId);

聊天室消息收发

发送消息

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

返回值 ChatRoomMessageBuilder 接口 说明
static ChatRoomMessage createChatRoomAudioMessage(String roomId, File file, long duration) 创建一条音频消息
static ChatRoomMessage createChatRoomCustomMessage(String roomId, MsgAttachment attachment) 创建自定义消息
static ChatRoomMessage createChatRoomFileMessage(String roomId, File file, String displayName) 创建一条文件消息
static ChatRoomMessage createChatRoomImageMessage(String roomId, File file, String displayName) 创建一条图片消息
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 createEmptyChatRoomMessage(String roomId, long time) 创建一条空消息,仅设置了房间ID以及时间点,用于记录查询
static ChatRoomMessage createTipMessage(String roomId) 创建一条提醒消息

聊天室消息 ChatRoomMessage 继承自 IMMessage。新增了两个方法:分别是设置和获取聊天室消息扩展属性。

返回值 ChatRoomMessage 接口 说明
CustomChatRoomMessageConfig getChatRoomConfig() 获取聊天室消息配置
ChatRoomMessageExtension getChatRoomMessageExtension() 获取聊天室消息扩展属性
void setChatRoomConfig
(CustomChatRoomMessageConfig config)
设置聊天室消息配置

1. 文本消息发送

以文本消息发送为例,其它类型的消息发送方式与会话消息类似。

/**
 * 创建普通文本消息
 *
 * @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);

接收消息

通过添加消息接收观察者,在有新消息到达时,第三方 APP 就可以接收到通知。

/**
 * 注册/注销消息接收观察者。
 *
 * @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);

聊天室管理

获取聊天室信息

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

/**
 * 获取当前聊天室信息
 *
 * @param roomId 聊天室id
 * @return InvocationFuture 可以设置回调函数。回调中返回聊天室的信息
 */
InvocationFuture<ChatRoomInfo> fetchRoomInfo(String roomId);
返回值 ChatRoomInfo 接口 说明
String getAnnouncement() 获取聊天室公告
String getBroadcastUrl() 获取聊天室拉流地址
String getCreator() 获取聊天室创建者帐号
Map getExtension() 获取聊天室扩展字段
String getName() 获取聊天室名称
int getOnlineUserCount() 获取当前在线用户数量
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 表示只有主播/管理员有权限
// 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的消息。

/**
 * 更新聊天室信息
 *
 * @param roomId             聊天室id
 * @param chatRoomUpdateInfo 可更新的聊天室信息
 * @param needNotify         是否通知
 * @param notifyExtension    更新聊天室信息扩展字段,这个字段会放到更新聊天室信息通知的扩展字段中
 * @return InvocationFuture 可以设置回调函数。更新聊天室信息完成之后才会调用,如果出错,会有具体的错误代码。
 */
InvocationFuture<Void> updateRoomInfo(String roomId, ChatRoomUpdateInfo chatRoomUpdateInfo, boolean needNotify, Map<String, Object> notifyExtension);
参数 说明
roomId 聊天室id
chatRoomUpdateInfo 可更新的聊天室信息
needNotify 是否通知
notifyExtension 更新聊天室信息扩展字段,这个字段会放到更新聊天室信息通知的扩展字段中
queueLevel 队列管理权限,0表示所有人有权限,1表示只有主播管理员有权限

ChatRoomUpdateInfo 接口说明

返回值 ChatRoomUpdateInfo 接口 说明
String getAnnouncement() 获取聊天室公告
String getBroadcastUrl() 获取视频直播拉流地址
Map getExtension() 获取第三方扩展字段
String getName() 获取聊天室名称
void setAnnouncement(String announcement) 设置聊天室公告
void setBroadcastUrl(String broadcastUrl) 设置视频直播拉流地址
void setExtension(Map extension) 设置第三方扩展字段,长度 4k
void setName(String name) 设置聊天室名称
void setQueueLevel(int queueLevel) 设置队列管理权限
// 以更新聊天室信息为例
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) {
                // 错误
            }
        });

获取聊天室成员

1. 根据成员类型获取聊天室成员

该接口可以获取固定成员信息、仅在线的固定成员信息及游客信息 ChatRoomMember,其中的扩展字段由该用户进入聊天室时填写。

固定成员有四种类型,分别是创建者,管理员,普通用户,受限用户。禁言用户和黑名单用户都属于受限用户。

拉取固定成员时,无论成员在线不在线,都会返回。拉取游客时,只返回在线的成员。

/**
 * 获取聊天室成员信息
 *
 * @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 条数限制

ChatRoomMember 接口说明

返回值 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 仅在线的固定成员
UNKNOWN 未知
// 以游客为例,从最新时间开始,查询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) {
       ...
    }
});

2. 根据用户 id 获取聊天室成员信息

通过用户 id 批量获取指定成员在聊天室中的信息。

/**
 * 根据用户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>>() { ... });

监听聊天室在线状态

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

/**
 * 注册/注销聊天室在线状态/登录状态观察者
 *
 * @param observer 观察者, 参数为聊天室ID和聊天室状态(未进入、连接中、进入中、已进入)
 * @param register true为注册,false为注销
 */
public void observeOnlineStatus(Observer<ChatRoomStatusChangeData> observer, boolean register);
ChatRoomStatusChangeData 属性 说明
roomId 聊天室 ID
status 状态码,参考 StatusCode
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,表示无法进入聊天室,此时应该调用离开聊天室接口。
            }
            ...
        }
    };

修改自己的聊天室成员信息

支持更新本人聊天室成员信息。目前只支持昵称,头像和扩展字段的更新。可以设置更新是否通知,若设置通知,聊天室内会收到类型为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);
参数 说明
roomId 聊天室 id
chatRoomMemberUpdate 可更新的本人角色信息
needNotify 是否通知
notifyExtension 更新聊天室信息扩展字段,这个字段会放到更新聊天室信息通知的扩展字段中

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) {
        // 错误
    }
});

聊天室权限管理

设置为管理员

设为管理员时, 会收到类型为 ChatRoomManagerAdd 的聊天室通知消息。

取消管理员时, 会收到类型为 ChatRoomManagerRemove 的聊天室通知消息。

如果游客被设为管理员,再被取消管理员,该成员不在变为游客,而成为普通成员。


/**
 * 设为/取消聊天室管理员
 *
 * @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) {
                // 错误
            }
        });

设置为普通成员

即将游客变为固定成员中的普通成员身份。

设为普通成员时, 会收到类型为 ChatRoomCommonAdd 的聊天室通知消息。

移除普通成员时, 会收到类型为 ChatRoomCommonRemove 的聊天室通知消息。

/**
 * 设为/取消聊天室普通成员
 *
 * @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) {
                // 错误
            }
        });

设置为拉黑用户

加入黑名单时,会收到类型为 ChatRoomMemberBlackAdd 聊天室通知消息。

移出黑名单时,会收到类型为 ChatRoomMemberBlackRemove 的聊天室通知消息。

/**
 * 添加/移出聊天室黑名单
 *
 * @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) {
                        // 错误
                    }
                });

设置为禁言用户

1. 永久禁言

添加到禁言名单时, 会收到类型为 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) {
                // 错误
            }
        });

2. 临时禁言

设置临时禁言时, 会收到类型为 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) {
                // 错误
            }
        });

踢出成员

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

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

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

/**
 * 踢掉特定成员
 *
 * @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>() { ... });

监听被踢出聊天室

当用户被主播或者管理员踢出聊天室、聊天室被关闭(被解散),会收到通知。注意:收到被踢出通知后,不需要再调用退出聊天室接口,SDK 会负责聊天室的退出工作。可以在踢出通知中做相关缓存的清理工作和界面操作。

/**
 * 注册/注销被踢出聊天室观察者。
 *
 * @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) {
            // 提示被踢出的原因(聊天室已解散、被管理员踢出、被其他端踢出等)
            // 清空缓存数据
        }
    };

查询聊天室消息历史

聊天室支持获取云端消息记录的功能,进入聊天室时,不会下发该聊天室的历史消息,开发者应主动查询历史消息。

1. 获取历史消息

以 startTime(单位毫秒) 为时间戳,往前拉取 limit 条消息。拉取到的消息中也包含成员操作的通知消息。

/**
 * 获取历史消息,默认从给定时间点往前查询,排序为时间逆序
 *
 * @return InvocationFuture 可以设置回调函数。回调中返回历史消息列表
 */
InvocationFuture<List<ChatRoomMessage>> pullMessageHistory(String roomId, long startTime, int limit);
参数 说明
roomId 聊天室 id
startTime 时间戳,单位毫秒
limit 可拉取的消息数量
long startTime = System.currentTimeMillis();
// 从现在开始,查询20条消息
NIMClient.getService(ChatRoomService.class).pullMessageHistory(roomId, startTime, 20);

2. 根据消息方向获取历史消息

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

3. 根据消息方向获取指定类型的历史消息

在 2 的基础上扩展,以 startTime(单位毫秒)为时间戳,选择查询方向,指定一种或多种类型的消息,往前或者往后拉取 limit 条消息。

/**
 * 获取历史消息,可选择给定时间往前或者往后查询,以及查询指定一种或多种类型的消息。
 *
 * 若方向往前,则结果排序按时间逆序,反之则结果排序按时间顺序
 *
 * 消息类型仅支持 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) {
        xxx
    }
});

聊天室通知消息

聊天室通知消息是聊天室消息的一种(消息类型为 Notification)。即聊天室消息为 ChatRoomMessage, 其中附件类型为 ChatRoomNotificationAttachment ,附件类型中的 type 字段来标识聊天室通知消息的类型。目前支持的类型见 NotificationType 。

参考 消息收发的通知消息 章节

队列服务

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

加入或更新队列元素

1. 默认加入或更新队列元素

注意:key是唯一键

当 key 不存在时候,调用该接口,表示加入新元素。 当 key 存在的时候,调用该接口,表示修改对应 key 的 value。


/**
 * 聊天室队列服务:加入或者更新队列元素
 *
 * @return InvocationFuture 可以设置回调函数。回调中返回操作成功或者失败具体的错误码。
 */
InvocationFuture<Void> updateQueue(String roomId, String key, String value);
参数 说明
roomId 聊天室 id
key 新元素(或待更新元素)的唯一键
value 新元素(待待更新元素)的内容
NIMClient.getService(ChatRoomService.class)
        .updateQueue(roomId, "this is key", "this is value")
        .setCallback(new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void param) {
                // 成功
            }

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

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

2. 支持配置当用户掉线或退出聊天室后,删除更新的元素。

当 key 不存在时候,调用该接口,表示加入新元素。 当 key 存在的时候,调用该接口,表示修改对应 key 的 value。

用户使用该接口加入或更新的元素,当 isTransient 参数为 true 时,表示当该用户掉线或退出聊天室时,服务器会自动删除该用户加入或更新的元素。同时,服务器将发出聊天室通知消息,通知消息的类型为 NotificationType#ChatRoomQueueBatchChange,通知消息的附件类型为 ChatRoomPartClearAttachment,该通知消息属于队列变更通知,所以附件类型中包含了队列变更类型 ChatRoomQueueChangeType#PARTCLEAR。

/**
 * 聊天室队列服务:加入或者更新队列元素,支持当用户掉线或退出聊天室后,是否删除这个元素
 * @param roomId 聊天室id
 * @param key    新元素(或待更新元素)的唯一键
 * @param value  新元素(待待更新元素)的内容
 * @param isTransient (可选参数,不传默认false)。true表示当提交这个新元素的用户从聊天室掉线或退出的时候,需要删除这个元素;默认false表示不删除
 * @return InvocationFuture 可以设置回调函数。回调中返回操作成功或者失败具体的错误码。
 */
InvocationFuture<Void> updateQueueEx(String roomId, String key, String value, boolean isTransient);
参数 说明
roomId 聊天室 id
key 新元素(或待更新元素)的唯一键
value 新元素(待待更新元素)的内容
isTransient (可选参数)
true 表示当提交这个新元素的用户从聊天室掉线或退出的时候,需要删除这个元素;默认false表示不删除

ChatRoomPartClearAttachment 说明

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

取出队列元素

注意: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<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) {
        // 错误
    }
});

删除队列

/**
 * 聊天室队列服务:删除队列
 *
 * @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) {
        // 错误
    }
});

独立模式下获取 bot 机器人列表

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

/**
 * 独立聊天室场景下,获取当前全部聊天室机器人
 *
 * @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();
                // 更新缓存
            }
        }
    });
}