聊天室消息收发

聊天室消息收发接口与 IM 的消息收发接口统一，在发送消息时指定会话类型为聊天室即可。会话 id 即为聊天室 id。值得注意的是：针对聊天室消息，SDK不会持久化在本地。

部分重要参数如下：

参数	类型	说明
messageType	NIMMessageType	消息类型 如果设置为自定义消息类型，建议将自定义消息的文本内容传入messageObject字段
session	NIMSessionType	会话类型，包括单聊、群聊和聊天室等
notifyTargetTags	NSString *	聊天室消息的目标表达式。目标表达式相关说明参见目标表达式
locationX	NSNumber	X坐标，用于聊天室空间消息
locationY	NSNumber	Y坐标，用于聊天室空间消息
locationZ	NSNumber	Z坐标，用于聊天室空间消息
toAccIds	NSArray<NSString*>	消息接收者列表，用于聊天室定向消息，最多 100 个用户

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

更新坐标

objc/**
 * 更新坐标
 * @param location 当前地理位置和接收消息的有效距离
 * @param completion 请求完成回调
 */
-(void)updateLocation:(nonnull NIMChatroomLocation *)location
        completion:(nullable NIMChatroomHandler)completion;

• NIMChatroomLocation 参数列表

参数	类型	说明
roomId	NSString	聊天室ID
locationX	NSNumber	空间坐标 X
locationY	NSNumber	空间坐标 Y
locationZ	NSNumber	空间坐标 Z
distance	NSNumber	距离

空间坐标 X、Y、Z 主要用于确定当前用户的位置，距离（distance）是指在基于空间坐标（用户位置）给接收指定距离范围内的消息。

聊天室通知消息

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

NIMChatroomEventType	说明
NIMChatroomEventTypeEnter = 301	成员进入聊天室
NIMChatroomEventTypeExit = 302	成员离开聊天室
NIMChatroomEventTypeAddBlack = 303	成员被拉黑
NIMChatroomEventTypeRemoveBlack = 304	成员被取消拉黑
NIMChatroomEventTypeAddMute = 305	成员被设置禁言
NIMChatroomEventTypeRemoveMute = 306	成员被取消禁言
NIMChatroomEventTypeAddManager = 307	设置为管理员
NIMChatroomEventTypeRemoveManager = 308	移除管理员
NIMChatroomEventTypeAddCommon = 309	设置为固定成员
NIMChatroomEventTypeRemoveCommon = 310	取消固定成员
NIMChatroomEventTypeClosed = 311	聊天室被关闭
NIMChatroomEventTypeInfoUpdated = 312	聊天室信息更新
NIMChatroomEventTypeKicked = 313	聊天室成员被踢
NIMChatroomEventTypeAddMuteTemporarily = 314	聊天室成员被临时禁言
NIMChatroomEventTypeRemoveMuteTemporarily = 315	聊天室成员被解除临时禁言
NIMChatroomEventTypeMemberUpdateInfo = 316	聊天室成员主动更新了聊天室的角色信息
NIMChatroomEventTypeQueueChange = 317	聊天室通用队列变更的通知
NIMChatroomEventTypeRoomMuted = 318	聊天室被禁言了，只有管理员可以发言,其他人都处于禁言状态
NIMChatroomEventTypeRoomUnMuted = 319	聊天室解除禁言状态
NIMChatroomEventTypeQueueBatchChange = 320	聊天室通用队列批量变更的通知
NIMChatroomEventTypeRecall = 323	聊天室消息撤回
NIMChatroomEventTypeQueueBatchAdd = 324	批量添加聊天室队列元素

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

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

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

1. 判断消息是否为通知消息。

   • 判断 NIMMessage - messageType 字段是否为 NIMMessageTypeNotification。

2. 再判断是否为聊天室通知消息。

   • 将 NIMMessage - messageObject 强类型转换为 NIMNotificationObject。
   • 判断转换后的 NIMNotificationObject - notificationType 字段是否为 NIMNotificationTypeChatroom。

3. 解析具体内容。

   • 将 NIMNotificationObject - content 字段强类型转换为 NIMChatroomNotificationContent。

聊天室通知内容 NIMChatroomNotificationContent 的字段说明：

• eventType : 聊天室通知事件类型，表示具体属于哪一种聊天室通知，通知种类由 NIMChatroomEventType 枚举定义。
• source : 通知的操作者，表示谁触发了这个通知，被封装为NIMChatroomNotificationMember 类型。
• targets : 通知的被操作者，表示这个通知影响的用户，被封装为 NSArray 类型， NSArray 中每个元素被封装成 NIMChatroomNotificationMember 类型。
• notifyExt : 通知的扩展字段，这个扩展字段是由每个触发通知的操作接口定义的。如进入聊天室时设置的NIMChatroomEnterRequest - roomNotifyExt
• ext : 目前只有 临时禁言/队列操作 事件才有，记录禁言时长信息、队列操作具体信息等。
• revokedMessageId : 被撤回消息的ID
• revokedMessageTime : 被撤回消息的时间

下面针对聊天室队列元素变更通知消息的解析进行示例：

在 NIMChatroomNotificationContent 的 eventType 事件中，有两种事件属于聊天室变更事件分别为NIMChatroomEventTypeQueueChange与NIMChatroomEventTypeQueueBatchChange。

消息解析示例:

objc- (void)onRecvMessages:(NSArray<NIMMessage *> *)messages
{
    for (NIMMessage *message in messages)
    {
        if (message.messageType == NIMMessageTypeNotification)
        {
            if (notification.notificationType == NIMNotificationTypeChatroom)
            {
                NIMChatroomNotificationContent *content = (NIMChatroomNotificationContent *)notification.content;
                NSDictionary *info = content.ext;
                if (content.eventType == NIMChatroomEventTypeQueueChange)
                {
                    //change type
                    //NIMChatroomQueueChangeTypeOffer, NIMChatroomQueueChangeTypePoll, NIMChatroomQueueChangeTypeDrop,NIMChatroomQueueChangeTypeUpdate
                    NIMChatroomQueueChangeType changeType = [[info objectForKey:NIMChatroomEventInfoQueueChangeTypeKey] integerValue];
                    //key
                    NSString *key = [info objectForKey:NIMChatroomEventInfoQueueChangeItemKey];
                    //value
                    NSString *value = [info objectForKey:NIMChatroomEventInfoQueueChangeItemValueKey];
                    //deal with key and value
                }
                if (content.eventType == NIMChatroomEventTypeQueueBatchChange)
                {
                    //change type
                    //NIMChatroomQueueBatchChangeTypePartClear
                    NIMChatroomQueueBatchChangeType changeType = [[info objectForKey:NIMChatroomEventInfoQueueChangeTypeKey] integerValue];
                    NSDictionary *batch = [info objectForKey:NIMChatroomEventInfoQueueChangeItemsKey];
                    for (NSString *key in batch)
                    {
                        NSString *value = [batch objectForKey:key];
                        //deal with key and value
                    }
                }
            }
        }
    }
}

• 关于例子中在ext中解析出来的changeType

若NIMChatroomNotificationContent 的 eventType 为 NIMChatroomEventTypeQueueChange， 则changeType为NIMChatroomQueueChangeType:

• 无效或未知变更类型 NIMChatroomQueueChangeTypeInvalid
• 新增元素 NIMChatroomQueueChangeTypeOffer
• 取出元素 NIMChatroomQueueChangeTypePoll
• 清空元素 NIMChatroomQueueChangeTypeDrop
• 更新元素 NIMChatroomQueueChangeTypeUpdate

若NIMChatroomNotificationContent 的 eventType 为 NIMChatroomEventTypeQueueBatchChange， 则changeType为NIMChatroomQueueBatchChangeType:

• 无效或未知变更类型 NIMChatroomQueueBatchChangeTypeInvalid
• 部分批量清理(发生在提交元素的用户掉线时，清理这个用户对应的key) NIMChatroomQueueBatchChangeTypePartClear

查询云端历史消息

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

objc@protocol NIMChatroomManager <NSObject>
/**
 *  查询服务器保存的聊天室消息记录
 * 
 *  @param roomId  聊天室ID
 *  @param option  查询选项
 *  @param result   完成回调
 */
- (void)fetchMessageHistory:(NSString *)roomId
                     option:(NIMHistoryMessageSearchOption *)option
                     result:(NIMFetchChatroomHistoryBlock)completion;
@end                     

NIMHistoryMessageSearchOption 参数列表 (部分字段对聊天室消息搜索选项无效，已过滤)

参数	类型	说明
startTime	NSTimeInterval	检索消息起始时间，需要检索的起始时间,没有则传入0。即以该时间为起点，往前或往后查询。
limit	NSUInteger	检索条数，最大限制 100 条
order	NIMMessageSearchOrder	检索顺序
messageTypes	NSArray<NSNumber *>	查询的消息类型，默认为 nil ，搜索全类型。

根据标签查询历史消息

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

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

objc/**
 * 通过标签查询消息
 * @param param 查询参数
 * @param completion 完成回调
 */
- (void)getMessagesByTags:(NIMGetMessagesByTagsParam *)param
              completion:(nullable NIMGetMessagesByTagsHandler)completion;

NIMGetMessagesByTagsParam 参数列表

参数	类型	说明
roomId	NSInteger	聊天室 ID（必填）
tags	NSArray<NSString *>	标签列表，支持传入多个标签同时查询（必填）
messageTypes	NSArray<NSNumber *>	消息类型列表，查询指定消息类型的消息，默认查询全部消息类型
fromTime	NSNumber *	起始时间，单位秒。被转换为NSTimeInterval类型使用
toTime	NSNumber *	结束时间，单位秒。被转换为NSTimeInterval类型使用
limit	NSNumber *	可查询的最大消息数量。被转换为NSInteger类型使用
reverse	NSNumber *	查询方向。被转换为BOOL类型使用

示例代码如下：

objc[[NIMSDK sharedSDK].chatroomManager getMessagesByTags:param completion:^(NSError * __nullable error,NSArray<NIMMessage *> * __nullable messages) {
    if (error) {
        // 获取消息失败
    } else {
        // 获取消息成功
    }
}];