logo
当前页

消息回执


功能简介

消息已读回执,是指用户在会话中发送一条消息后,得知其他用户已读或未读此消息。本功能可用于在企业办公等需要实时知晓消息是否已经被阅读的场景。

本文档介绍了如何使用 ZIM SDK 的接口,实现发送一条附带回执的消息,以及查看和应答回执详情等功能。

注意

ZIM SDK 目前支持发送“单聊”会话和“群组”会话的消息回执(仅支持普通消息和富媒体消息),暂不支持发送“房间”会话的消息回执。

实现流程

消息发送端通过 ZIM SDK 发送一条消息,并通过设置 ZIMMessageSendConfighasReceipt 字段标记该消息是否需要带回执,接收端可根据消息的回执状态 receiptStatus 判断该消息当前是否带回执,或者回执处于正在进行中还是已完成,从而渲染不同的 UI 效果,而接收端可根据不同的场景进行不同的已读方式。

发送一条附带回执的消息

如果客户端 A 想要向客户端 B 发送一条附带回执的消息:

  1. 客户端 A 和 客户端 B 登录 ZIM SDK;
  2. 客户端 A 调用 sendMessagesendMediaMessage 接口,向客户端 B 发送一条消息(仅支持“单聊”会话和“群组”会话的普通消息和富媒体消息),并设置 ZIMMessageSendConfighasReceipt 字段为 true;
  3. 客户端 B 通过监听相关回调( onPeerMessageReceivedonGroupMessageReceived )会收到一条 receiptStatusPROCESSING 的消息。

接收端对消息回执进行已读操作

已读操作分为消息已读会话已读

消息已读

消息已读,是指接收端收到对方发送的附带回执的消息,可对该消息设置已读,已读成功,发送方将会收到该消息已被读的通知。

注意
  • 消息可为单条消息或批量消息,但是消息发送端与接收端必须在同一会话内,不允许跨会话。
  • 如需对会话的历史消息进行相关操作,需先完成查询历史消息,对历史消息的回执状态进行判断,详情请参考 查询历史消息
  1. 客户端 B 通过相关回调( onPeerMessageReceivedonGroupMessageReceived )收到客户端 A 发送的一条附带回执的消息;
  2. 客户端 B 根据回调的 receiptStatus 字段判断该消息的回执状态。如果是该字段为 PROCESSING,表示该消息处于“回执中”,开发者可根据自己的业务逻辑,调用 sendMessageReceiptsRead 接口将该消息设置为已读。
  3. 客户端 B 通过 ZIMMessageReceiptsReadSentCallback 得知设置是否成功。
  4. 客户端 A 通过 ZIMEventHandleronMessageReceiptChanged 收到该消息被设置为消息已读的回调通知。开发者可根据这个回调,在客户端 A 实现将此消息设置为已读的业务逻辑。

会话已读

会话已读,是指接收端将指定会话内所有已接收的对方消息都设置为已读。

注意
  • 目前 ZIM SDK 只允许在单聊会话实现此功能;
  • 此功能只作用于设置已读之前获取的消息,不对设置之后的消息生效。
  • 此功能建议在用户从会话列表页进入到会话时使用,不推荐在同一会话中与 sendMessageReceiptsRead 接口混用。
  • 如需对会话的历史消息进行相关操作,需先完成查询历史消息,对历史消息的回执状态进行判断,详情请参考 查询历史消息
  1. 客户端 B 根据回调 onPeerMessageReceivedreceiptStatus 字段判断该消息的回执状态。如果是该字段为 PROCESSING,则表示该消息处于回执中,开发者可根据自己的业务逻辑,调用 sendConversationMessageReceiptRead 接口将会话内客户端 A 已发送的所有消息都设置为已读。
  2. 客户端 B 通过 ZIMConversationMessageReceiptReadSentCallback 得知设置是否成功。
  3. 客户端 A 通过 ZIMEventHandleronConversationMessageReceiptChanged 收到该消息被设置为会话已读的回调通知,开发者可根据这个回调,实现该会话所有对方发的消息都设置为已读的逻辑。开发者可根据这个回调,在客户端 A 实现自己发的所有消息都被客户端 B 设置为已读的业务逻辑。

更多功能

批量查询消息的回执状态、已读用户数和未读用户数

当需要查询一条或一批消息的回执状态、已读用户数和未读未读用户数时,可以调用 queryMessageReceiptsInfo 接口查询,通过 ZIMMessageReceiptsInfoQueriedCallback 获取相关信息。

注意
  • 如果是查询其他用户发送的信息,得到的已读用户数和未读用户数都是 0。
  • 如需对会话的历史消息进行相关操作,需先完成查询历史消息,对历史消息的回执状态进行判断,详情请参考 查询历史消息

查询群组里自己发送的消息的已读和未读成员列表

ZIM SDK 支持查询群组里自己发送的消息的已读成员列表和未读成员列表。

查询已读成员列表

当需要查询有哪些成员读了自己发送的消息,可调用 queryGroupMessageReceiptReadMemberList 接口查询具体成员列表。

注意

如需对会话的历史消息进行相关操作,需先完成查询历史消息,对历史消息的回执状态进行判断,详情请参考 查询历史消息

查询未读成员列表

当需要查询还有哪些成员未读自己发送的消息,可调用 queryGroupMessageReceiptUnreadMemberList 接口查询具体成员列表。

注意
  • 若 SDK 版本低于 2.16.0,当群成员人数大于 100 时,此接口不会返回具体未读成员列表。如需使用此功能,可联系 ZEGO 技术支持。
  • 如需对会话的历史消息进行相关操作,需先完成查询历史消息,对历史消息的回执状态进行判断,详情请参考 查询历史消息

示例代码

Untitled
zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onMessageReceiptChanged(ZIM zim, ArrayList<ZIMMessageReceiptInfo> infos) {
        // 对方设置了消息的已读回执
    }

    @Override
    public void onConversationMessageReceiptChanged(ZIM zim, ArrayList<ZIMMessageReceiptInfo> infos) {
        // 对方设置会话的已读回执
    }
})

// 用户 A 发送一条消息,并带上回执,以单聊文本消息为例

String conversationID = "xxx" ; // 会话 ID

ZIMTextMessage message = new ZIMTextMessage("test");
ZIMMessageSendConfig sendConfig = new ZIMMessageSendConfig();
sendConfig.hasReceipt = true;    // 设置消息带回执
zim.sendMessage(message, conversationID, ZIMConversationType.PEER,sendConfig, new ZIMMessageSentCallback() {
            @Override
            public void onMessageAttached(ZIMMessage message) {}

            @Override
            public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
                if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                    // 这里表示发送消息成功,message 的 receiptStatus 会为 PROCESSING,业务层可根据这个标志实现展示回执中(消息未读)的逻辑。
                }
            }
        });


// 用户 B 接收到回执,并做已读操作,选择以下任一接口即可

// 消息已读
List<ZIMMessage> messages = new ArrayList<>();
messages.add(message);
zim.sendMessageReceiptsRead(messages, conversationID, ZIMConversationType.PEER, 
        new ZIMMessageReceiptsReadSentCallback() {
            @Override
            public void onMessageReceiptsReadSent(String conversationID, ZIMConversationType conversationType, 
ArrayList<Long> errorMessageIDs, ZIMError errorInfo) {
             if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 消息已读的回调
             }
            }
        });

// 会话已读
zim.sendConversationMessageReceiptRead(conversationID, ZIMConversationType.PEER, 
            new ZIMConversationMessageReceiptReadSentCallback() {
            @Override
            public void onConversationMessageReceiptReadSent(String conversationID, 
                ZIMConversationType conversationType, ZIMError errorInfo) {
                if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                    // 会话已读成功,开发者可通过监听这个回调,把这个会话内对方发的消息都设置为已读的标志。
                }
            }
        });


// (可选)查询一批消息的回执状态、未读用户数和已读用户数

List<ZIMMessage> messages = new ArrayList<>();
messages.add(message);
zim.queryMessageReceiptsInfo(messages, conversationID, ZIMConversationType.PEER, new ZIMMessageReceiptsInfoQueriedCallback() {
            @Override
            public void onMessageReceiptsInfoQueried(ArrayList<ZIMMessageReceiptInfo> infos, 
                ArrayList<Long> errorMessageIDs, ZIMError errorInfo) {
                if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                    // 查询到这一批消息的状态和数量,遍历 infos 获取对应的消息 ID 和 count
                }
            }
        });


// (可选)查询某一条群消息的已读群成员列表和未读群成员列表

// 已读用户列表
ZIMGroupMessageReceiptMemberQueryConfig config = new ZIMGroupMessageReceiptMemberQueryConfig();
config.nextFlag = 0;    // 查询的 flag ,初始时填 0,后续填从 callback 里返回的 flag。
config.count = 10;    // 需要查询的用户数量。

zim.queryGroupMessageReceiptReadMemberList(message, groupID, config, 
    new ZIMGroupMessageReceiptMemberListQueriedCallback() {
            @Override
            public void onGroupMessageReceiptMemberListQueried(String groupID, ArrayList<ZIMGroupMemberInfo> userList,
             int nextFlag, ZIMError errorInfo) {
                if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                   // 查询到对应的成员列表
                }
            }
        });

// 未读用户列表
ZIMGroupMessageReceiptMemberQueryConfig config = new ZIMGroupMessageReceiptMemberQueryConfig();
config.nextFlag = 0;    // 查询的 flag ,初始时填 0,后续填从 callback 里返回的 flag。
config.count = 10;    // 需要查询的用户数量。

zim.queryGroupMessageReceiptUnreadMemberList(message, groupID, config, 
    new ZIMGroupMessageReceiptMemberListQueriedCallback() {
            @Override
            public void onGroupMessageReceiptMemberListQueried(String groupID, ArrayList<ZIMGroupMemberInfo> userList,
             int nextFlag, ZIMError errorInfo) {
                if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                   // 查询到对应的成员列表
                }
            }
        });
1
Copied!

Previous

撤回消息

Next

设置消息拓展字段