聊天室管理

概述

JMessage iOS SDK 从 3.4.0 版本开始提供聊天室功能，包括查询基本信息，加入聊天室，退出聊天室等。

  • 主要特点

    • 聊天室的消息没有推送通知和离线保存
    • 没有常驻成员的概念，只要进入聊天室即可接收消息，开始聊天
    • 一旦退出聊天室，不再会接收到任何消息、通知和提醒

  • 发送消息

    • 聊天室消息的发送与单聊、群聊是一样的，通用的发送接口

  • 接收消息

注意：进入聊天室会自动获取最近50条消息。客户端目前不支持创建聊天室

聊天室对象

属性/方法 类型/返回值 说明
roomID NSString 聊天室 id
name NSString 名称
appkey NSString 聊天室所属应用 AppKey
desc NSString 描述信息
totalMemberCount NSInteger 聊天室人数
maxMemberCount NSString 聊天室最大人数限制
ctime NSNumber 聊天室的创建时间

获取应用下聊天室列表

可以获取对应 AppKey 应用下的聊天室列表，不传 AppKey 则默认是当前应用。

  1. /*!
  2.  * @abstract 分页获取聊天室详情
  3.  *
  4.  * @param appKey  选填，为 nil 则获取当前应用下的聊天室
  5.  * @param start   分页获取的下标，第一页从  index = 0 开始
  6.  * @param count   一页的数量，每页最大值是 50
  7.  * @param handler 结果回调. 正常返回时 resultObject 类型是 NSArray<JMSGChatRoom>
  8.  *
  9.  * @discussion 该接口总是向服务器端发起请求.
  10.  */
  11. + (void)getChatRoomListWithAppKey:(NSString *JMSG_NULLABLE)appKey
  12.                             start:(NSInteger)start
  13.                             count:(NSInteger)count
  14.                 completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

获取当前用户加入的聊天室列表

  1. /*!
  2.  * @abstract 获取当前用户已加入的聊天室列表
  3.  *
  4.  * @param handler 结果回调. 正常返回时 resultObject 类型是 NSArray<JMSGChatRoom>
  5.  *
  6.  * @discussion 该接口总是向服务器端发起请求.
  7.  */
  8. + (void)getMyChatRoomListCompletionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

查询指定roomID的聊天室信息

  1. /*!
  2.  * @abstract 获取聊天室详情
  3.  *
  4.  * @param roomIds   待获取详情的聊天室 ID 数组
  5.  * @param handler   结果回调. 正常返回时 resultObject 类型是 NSArray<JMSGChatRoom>
  6.  *
  7.  * @discussion 该接口总是向服务器端发起请求.
  8.  */
  9. + (void)getChatRoomInfosWithRoomIds:(NSArray *JMSG_NONNULL)roomIds
  10.                   completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

进入聊天室

成功进入聊天室之后，会将聊天室中最近 50 条聊天记录同步下来，并上抛通知上层，上层可以通过 onReceiveChatRoomConversation:messages: 监听并获取返回的消息列表。

  1. /*!
  2.  * @abstract 加入聊天室
  3.  *
  4.  * @param roomId    聊天室 id
  5.  * @param handler   结果回调. error = nil 表示加入成功，resultObject 为 JMSGConversation 类型
  6.  *
  7.  * @discussion 成功进入聊天室之后，会将聊天室中最近若干条聊天记录同步下来并以 onReceiveChatRoomConversation: 事件的形式通知到上层，进入聊天室会自动获取最近50条消息。
  8.  */
  9. + (void)enterChatRoomWithRoomId:(NSString *JMSG_NONNULL)roomId
  10.               completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

离开聊天室

注意：退出聊天室后获取不到任何消息和通知

  1. /*!
  2.  * @abstract 退出聊天室
  3.  *
  4.  * @param roomId    聊天室 id
  5.  * @param handler   结果回调. error = nil 表示加入成功.
  6.  *
  7.  * @discussion 退出聊天室后获取不到任何消息和通知.
  8.  */
  9. + (void)leaveChatRoomWithRoomId:(NSString *JMSG_NONNULL)roomId
  10.               completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

获取聊天室会话

  1. /*!
  2.  * @abstract 返回聊天室 conversation 列表（异步,已排序）
  3.  *
  4.  * @param handler 结果回调。正常返回时 resultObject 的类型为 NSArray，数组里成员的类型为 JMSGConversation
  5.  *
  6.  * @discussion 当前是返回所有的chatroom conversation 列表，不包括单聊和群聊会话，默认是已经排序。
  7.  */
  8. + (void)allChatRoomConversation:(JMSGCompletionHandler)handler;
  1. /*!
  2.  * @abstract 获取聊天室会话
  3.  *
  4.  * @param roomId 聊天室 ID
  5.  *
  6.  * @discussion 如果会话还不存在，则返回 nil
  7.  */
  8. + (JMSGConversation * JMSG_NULLABLE)chatRoomConversationWithRoomId:(NSString *)roomId;

创建聊天室会话

  1. /*!
  2.  * @abstract 创建聊天室会话
  3.  *
  4.  * @param roomId  聊天室 ID。
  5.  * @param handler 结果回调。正常返回时 resultObject 类型为 JMSGConversation。
  6.  *
  7.  * @discussion 如果会话已经存在，则直接返回。如果不存在则创建。
  8.  * 创建会话时如果发现该 roomId 的信息本地还没有，则需要从服务器端上拉取。
  9.  * 如果从服务器上获取 roomId 的信息不存在或者失败，则创建会话失败。
  10.  */
  11. + (void)createChatRoomConversationWithRoomId:(NSString *)roomId
  12.                            completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

删除聊天室会话

  1. /*!
  2.  * @abstract 删除聊天室会话
  3.  *
  4.  * @param roomId  聊天室 ID
  5.  *
  6.  * @discussion 除了删除会话本身，还会删除该会话下所有的聊天消息。
  7.  */
  8. + (BOOL)deleteChatRoomConversationWithRoomId:(NSString *)roomId;

聊天室消息

聊天室消息发送

聊天室消息的发送接口与单聊、群里的发送接口是共用的，接口请查看会话与消息 - 发送消息

聊天室消息接收

  1. /*!
  2.  * @abstract 接收聊天室消息
  3.  *
  4.  * @param conversation 聊天室会话
  5.  * @param messages      接收到的消息数组，元素是 JMSGMessage
  6.  *
  7.  * @discussion 注意：
  8.  *
  9.  * 接收聊天室的消息与单聊、群聊消息不同，聊天室消息都是通过这个代理方法来接收的。
  10.  *
  11.  * @since 3.4.0
  12.  */
  13. - (void)onReceiveChatRoomConversation:(JMSGConversation *)conversation
  14.                              messages:(NSArray JMSG_GENERIC(__kindof JMSGMessage *)*)messages;

聊天室管理员

添加

  1. /*!
  2.  * @abstract 添加黑名单
  3.  *
  4.  * @param usernames 用户名列表
  5.  * @param appkey   用户 appKey，usernames 中的所有用户必须在同一个 AppKey 下，不填则默认为本应用 appKey
  6.  * @param handler 结果回调。error 为 nil 表示成功.
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. - (void)addBlacklistWithUsernames:(NSArray <__kindof NSString *>*)usernames
  11.                            appKey:(NSString *JMSG_NULLABLE)appKey
  12.                           handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

删除

  1. /*!
  2.  * @abstract 删除黑名单
  3.  *
  4.  * @param usernames 用户名列表
  5.  * @param appkey   用户 appKey，usernames 中的所有用户必须在同一个 AppKey 下，不填则默认为本应用 appKey
  6.  * @param handler 结果回调。error 为 nil 表示成功.
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. - (void)deleteBlacklistWithUsernames:(NSArray <__kindof NSString *>*)usernames
  11.                               appKey:(NSString *JMSG_NULLABLE)appKey
  12.                              handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

获取列表

  1. /*!
  2.  * @abstract 聊天室的黑名单列表
  3.  *
  4.  * @param handler 结果回调. resultObject 是 NSArray 类型，元素是 JMSGUser
  5.  *
  6.  * @since 3.8.0
  7.  */
  8. - (void)chatRoomBlacklist:(JMSGCompletionHandler JMSG_NULLABLE)handler;

聊天室黑名单

添加

  1. /*!
  2.  * @abstract 添加管理员
  3.  *
  4.  * @param usernames 用户名列表
  5.  * @param appkey    用户 AppKey，不填则默认为本应用 AppKey
  6.  * @param handler   结果回调。error 为 nil 表示成功.
  7.  *
  8.  * @discussion 注意：非 VIP 应用最多设置 15 个管理员，不包括群主本身
  9.  *
  10.  * @since 3.8.0
  11.  */
  12. - (void)addAdminWithUsernames:(NSArray <__kindof NSString *>*)usernames
  13.                        appKey:(NSString *JMSG_NULLABLE)appkey
  14.                       handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

删除

  1. /*!
  2.  * @abstract 删除管理员
  3.  *
  4.  * @param usernames 用户名列表
  5.  * @param appkey    用户 AppKey，不填则默认为本应用 AppKey
  6.  * @param handler   结果回调。error 为 nil 表示成功.
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. - (void)deleteAdminWithUsernames:(NSArray <__kindof NSString *>*)usernames
  11.                           appKey:(NSString *JMSG_NULLABLE)appkey
  12.                          handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

获取列表

  1. /*!
  2.  * @abstract 管理员列表
  3.  *
  4.  * @param handler 结果回调. resultObject 是 NSArray 类型，元素是 JMSGUser
  5.  *
  6.  * @discussion 注意：返回列表中不包含房主.
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. - (void)chatRoomAdminList:(JMSGCompletionHandler JMSG_NULLABLE)handler;

聊天室成员禁言

设置成员禁言

  1. /*!
  2.  * @abstract 设置成员禁言（可设置禁言时间）
  3.  *
  4.  * @param silenceTime 禁言时间戳，单位：毫秒，必须不小于5分钟，不大于1年
  5.  * @param usernames   用户的 username 数组，一次最多500人
  6.  * @param appKey      用户的 appKey，若传入空则默认使用本应用appKey，同一次设置的 usernames 必须在同一个 AppKey 下
  7.  * @param handler     结果回调，error = nil 时，表示成功
  8.  *
  9.  * @discussion 只有房主和管理员可设置；设置成功的话上层会收到相应下发事件。
  10.  *
  11.  * @since 3.8.1
  12.  */
  13. - (void)addChatRoomSilenceWithTime:(SInt64)silenceTime
  14.                          usernames:(NSArray *JMSG_NONNULL)usernames
  15.                             appKey:(NSString *JMSG_NULLABLE)appkey
  16.                            handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

删除成员禁言

  1. /*!
  2.  * @abstract 取消成员禁言
  3.  *
  4.  * @param usernames  用户的 username 数组，一次最多500人
  5.  * @param appKey     用户的 appKey，若传入空则默认使用本应用appKey，同一次设置的 usernames 必须在同一个 AppKey 下
  6.  * @param handler   结果回调，error = nil 时，表示成功
  7.  *
  8.  * @discussion 只有房主和管理员可设置；取消成功的话上层会收到相应下发事件。
  9.  *
  10.  * @since 3.8.1
  11.  */
  12. - (void)deleteChatRoomSilenceWithUsernames:(NSArray *JMSG_NONNULL)usernames
  13.                                     appKey:(NSString *JMSG_NULLABLE)appkey
  14.                                    handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

获取禁言状态

  1. /*!
  2.  * @abstract 获取禁言状态
  3.  *
  4.  * @param username 用户名
  5.  * @param appKey   用户所在应用 AppKey，不填这默认本应用
  6.  * @param handler  结果回调，resultObject 是 JMSGMemberSilenceInfo 类型
  7.  *                 若 error == nil && resultObject != nil,该成员已被禁言
  8.  *                 若 error == nil && resultObject == nil,该成员未被禁言
  9.  *                 若 error != nil ,请求失败，
  10.  *
  11.  * @discussion 详细信息可查看 JMSGMemberSilenceInfo 类
  12.  *
  13.  * @since 3.8.1
  14.  */
  15. - (void)getChatRoomMemberSilenceWithUsername:(NSString *JMSG_NONNULL)username
  16.                                       appKey:(NSString *JMSG_NULLABLE)appKey
  17.                                      handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

获取禁言列表

  1. /*!
  2.  * @abstract 禁言列表
  3.  *
  4.  * @param start 开始位置
  5.  * @param count 需要获取的个数，必须大于 0
  6.  * @param handler 结果回调
  7.  *
  8.  * @since 3.8.1
  9.  */
  10. - (void)getChatRoomSilencesWithStart:(SInt64)start
  11.                                count:(SInt64)count
  12.                              handler:(void(^)(NSArray <__kindof JMSGMemberSilenceInfo *>*JMSG_NULLABLE list,SInt64 total,NSError *JMSG_NULLABLE error))handler;

聊天室通知事件

聊天室事件目前有管理员变更事件、黑名单变更事件，具体事件详情和监听请查看事件与代理 - 聊天室事件