消息已读回执,是指用户在会话中发送一条消息后,得知其他用户已读或未读此消息。本功能可用于在企业办公等需要实时知晓消息是否已经被阅读的场景。
本文档介绍了如何使用 ZIM SDK 的接口,实现发送一条附带回执的消息,以及查看和应答回执详情等功能。
ZIM SDK 目前支持发送“单聊”会话和“群组”会话的消息回执(仅支持普通消息和富媒体消息),暂不支持发送“房间”会话的消息回执。
在实现“消息回执”功能之前,请确保:
消息发送端通过 ZIM SDK 发送一条消息,并通过设置 ZIMMessageSendConfig 的 hasReceipt
字段标记该消息是否需要带回执,接收端可根据消息的回执状态 receiptStatus
判断该消息当前是否带回执,或者回执处于正在进行中还是已完成,从而渲染不同的 UI 效果,而接收端可根据不同的场景进行不同的已读方式。
如果客户端 A 想要向客户端 B 发送一条附带回执的消息:
hasReceipt
字段为 true;receiptStatus
为 PROCESSING
的消息。已读操作分为消息已读
和会话已读
。
消息已读,是指接收端收到对方发送的附带回执的消息,可对该消息设置已读,已读成功,发送方将会收到该消息已被读的通知。
receiptStatus
字段判断该消息的回执状态。如果是该字段为 PROCESSING
,表示该消息处于“回执中”,开发者可根据自己的业务逻辑,调用 sendMessageReceiptsRead 接口将该消息设置为已读。- (void)sendMessageReceiptsRead:(NSArray<ZIMMessage *> *)messageList
conversationID:(NSString *)conversationID
conversationType:(ZIMConversationType)conversationType
callback:(ZIMMessageReceiptsReadSentCallback)callback;
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
messageList | NSArray<ZIMMessage *> * | 是 | 消息已读的指定消息列表,所含消息不能超过 10 条。 |
conversationID | NSString * | 是 | 消息已读消息的指定会话 ID。
|
conversationType | ZIMConversationType | 是 | 会话类型。
|
callback | ZIMMessageReceiptsReadSentCallback | 是 | 消息已读操作的结果回调。 |
- (void)zim:(ZIM *)zim messageReceiptChanged:(NSArray<ZIMMessageReceiptInfo *> *)infos;
会话已读,是指接收端将指定会话内所有已接收的对方消息都设置为已读。
receiptStatus
字段判断该消息的回执状态。如果是该字段为 PROCESSING
,则表示该消息处于回执中,开发者可根据自己的业务逻辑,调用 sendConversationMessageReceiptRead 接口将会话内客户端 A 已发送的所有消息都设置为已读。- (void)sendConversationMessageReceiptRead:(NSString *)conversationID
conversationType:(ZIMConversationType)conversationType
callback:(ZIMConversationMessageReceiptReadSentCallback)callback
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
conversationID | NSString * | 是 | 会话已读消息的指定会话 ID。
|
conversationType | ZIMConversationType | 是 | 会话类型。
|
callback | ZIMConversationMessageReceiptReadSentCallback | 是 | 会话已读操作的结果回调。 |
- (void)zim:(ZIM *)zim conversationMessageReceiptChanged:(NSArray<ZIMMessageReceiptInfo *> *)infos;
当需要查询一条或一批消息的回执状态、已读用户数和未读未读用户数时,可以调用 queryMessageReceiptsInfoByMessageList 接口查询,通过 ZIMMessageReceiptsInfoQueriedCallback 获取相关信息。
- (void)queryMessageReceiptsInfoByMessageList:(NSArray<ZIMMessage *> *)messageList
conversationID:(NSString *)conversationID
conversationType:(ZIMConversationType)conversationType
callback:(ZIMMessageReceiptsInfoQueriedCallback)callback
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
messageList | NSArray<ZIMMessage *> * | 是 | 指定消息列表。 |
conversationID | NSString * | 是 | 指定会话 ID。
|
conversationType | ZIMConversationType | 是 | 会话类型。
|
callback | ZIMMessageReceiptsInfoQueriedCallback | 是 | 查询结果回调。 |
ZIM SDK 支持查询群组里自己发送的消息的已读成员列表和未读成员列表。
当需要查询有哪些成员读了自己发送的消息,可调用 queryGroupMessageReceiptReadMemberListByMessage 接口查询具体成员列表。
如需对会话的历史消息进行相关操作,需先完成查询历史消息,对历史消息的回执状态进行判断,详情请参考 查询历史消息。
- (void)queryGroupMessageReceiptReadMemberListByMessage:(ZIMMessage *)message
groupID:(NSString *)groupID
config:(ZIMGroupMessageReceiptMemberQueryConfig *)config
callback:(ZIMGroupMessageReceiptMemberListQueriedCallback)callback;
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
message | ZIMMessage * | 是 | 已发送的附带回执的消息。 |
groupID | NSString * | 是 | 消息对应的群 ID。 |
config | ZIMGroupMessageReceiptMemberQueryConfig | 是 | 查询所需的 config。 |
callback | ZIMGroupMessageReceiptMemberListQueriedCallback | 是 | 查询与消息已读情况的相关的具体成员信息列表的回调。 |
参数 config
对应的参数说明
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
count | int | 是 | 需要查询的用户数量。 |
nextFlag | int | 是 | 查询的 flag ,初始时填 0,后续填从 callback 里返回的 nextFlag。 |
当需要查询还有哪些成员未读自己发送的消息,可调用 queryGroupMessageReceiptUnreadMemberListByMessage 接口查询具体成员列表。
- (void)queryGroupMessageReceiptUnreadMemberListByMessage:(ZIMMessage *)message
groupID:(NSString *)groupID
config:(ZIMGroupMessageReceiptMemberQueryConfig *)config
callback:(ZIMGroupMessageReceiptMemberListQueriedCallback)callback;
queryGroupMessageReceiptUnreadMemberListByMessage 的参数说明与上文 queryGroupMessageReceiptReadMemberListByMessage 的参数说明相同。
// 1、创建 ZIM 对象,传入 appID、appSign
ZIMAppConfig *appConfig = [[ZIMAppConfig alloc] init];
appConfig.appID = (unsigned int)appID; // 替换为您从 ZEGO 控制台申请到的 AppID
appConfig.appSign = @"appSign"; // 替换为您从 ZEGO 控制台申请到的 AppSign
self.zim = [ZIM createWithAppConfig: appConfig];
// 2、登录
ZIMUserInfo *userInfo = [[ZIMUserInfo alloc]init];
userInfo.userID = @"zegoUser1"; // 填入 NSString 类型的值
userInfo.userName = @"zegotest"; // 填入 NSString 类型的值
[self.zim loginWithUserInfo:userInfo callback:^(ZIMError * _Nonnull errorInfo){
// 开发者可根据 ZIMError 来判断是否登录成功。
}];
- (void)zim:(ZIM *)zim messageReceiptChanged:(NSArray<ZIMMessageReceiptInfo *> *)infos{
// 对方设置了消息的已读回执
}
- (void)zim:(ZIM *)zim conversationMessageReceiptChanged:(NSArray<ZIMMessageReceiptInfo *> *)infos{
// 对方设置会话的已读回执
}
NSString *conversationID = @"xxx" ; // 会话 ID
// 3、用户 A 发送一条消息,并带上回执,以单聊文本消息为例
ZIMTextMessage *message = [[ZIMTextMessage alloc] init];
ZIMMessageSendConfig *sendConfig = [[ZIMMessageSendConfig alloc]init];
sendConfig.hasReceipt = true; // 设置消息带回执
[self.zim sendMessage:cmdMsg toUserID:toUserID conversationType:type config:config notification:notification callback:^((ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo)) {
// 开发者可以通过该回调监听消息是否发送成功。
if (errorInfo.code == 0) {
// 这里表示发送消息成功,message 的 receiptStatus 会为 PROCESSING,业务层可根据这个标志实现展示回执中(消息未读)的逻辑。
}
}];
// 4、用户 B 接收到回执,并做已读操作,选择以下任一接口即可
// 4.1 消息已读
NSMutableArray<ZIMMessage *> *messageList = [[NSMutableArray alloc] init];
[[ZIM getInstance] sendMessageReceiptsRead:messageList conversationID:@"conversationID" conversationType:conversationType callback:^(NSString * _Nonnull conversationID, ZIMConversationType conversationType, NSArray<NSNumber *> * _Nonnull errorMessageIDs, ZIMError * _Nonnull errorInfo) {
// 设置消息已读的回调
}];
// 4.2、会话已读
[[ZIM getInstance] sendConversationMessageReceiptRead:@"conversationID" conversationType:conversationType callback:^(NSString * _Nonnull conversationID, ZIMConversationType conversationType, ZIMError * _Nonnull errorInfo) {
// 设置会话已读的回调
}];
// 5、(可选)查询一批消息的回执状态、未读用户数和已读用户数
NSMutableArray<ZIMMessage *> *messageList = [[NSMutableArray alloc] init];
[[ZIM getInstance] queryMessageReceiptsInfoByMessageList:messageList conversationID:conversationID conversationType:conversationType callback:^(NSArray<ZIMMessageReceiptInfo *> * _Nonnull infos, NSArray<NSNumber *> * _Nonnull errorMessageIDs, ZIMError * _Nonnull errorInfo) {
// 查询到这一批消息的状态和数量,遍历 infos 获取对应 的消息 ID 和 count
}];
// 6、(可选)查询某一条群消息的已读群成员列表和未读群成员列表
// 6.1 已读用户列表
ZIMGroupMessageReceiptMemberQueryConfig *config = [[ZIMGroupMessageReceiptMemberQueryConfig alloc]init];
config.nextFlag = 0; // 查询的 flag ,初始时填 0,后续填从 callback 里返回的 flag。
config.count = 10; // 需要查询的用户数量。
[[ZIM getInstance] queryGroupMessageReceiptReadMemberListByMessage:message groupID:groupID config:config callback:^(NSString * _Nonnull groupID, NSArray<ZIMGroupMemberInfo *> * _Nonnull userList, unsigned int nextFlag, ZIMError * _Nonnull errorInfo) {
// 查询到对应的成员列表
}];
// 6.2 未读用户列表
ZIMGroupMessageReceiptMemberQueryConfig config = new ZIMGroupMessageReceiptMemberQueryConfig();
config.nextFlag = 0; // 查询的 flag ,初始时填 0,后续填从 callback 里返回的 flag。
config.count = 10; // 需要查询的用户数量。
[[ZIM getInstance] queryGroupMessageReceiptUnreadMemberListByMessage:message groupID:groupID config:config callback:^(NSString * _Nonnull groupID, NSArray<ZIMGroupMemberInfo *> * _Nonnull userList, unsigned int nextFlag, ZIMError * _Nonnull errorInfo) {
// 查询到对应的成员列表
}];
联系我们
文档反馈