聊天室管理

概述

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

  • 主要特点

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

  • 发送消息

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

  • 接收消息

    • 聊天室消息的接收与单聊、群聊做了区分，聊天室消息的接收将通过 JMSGConversationDelegate 类里的 ">onReceiveChatRoomConversation:messages: 方法通知到上层注意：进入聊天室会自动获取最近50条消息。客户端目前不支持创建聊天室

聊天室对象

属性/方法类型/返回值说明
roomIDNSString聊天室 id
nameNSString名称
appkeyNSString聊天室所属应用 AppKey
descNSString描述信息
totalMemberCountNSInteger聊天室人数
maxMemberCountNSString聊天室最大人数限制
ctimeNSNumber聊天室的创建时间

获取应用下聊天室列表

可以获取对应 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;

聊天室通知事件

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