消息已读回执

更新时间: 2024/04/17 15:00:36

当消息接收方收到消息并阅读后,可以将该消息标记为已读(发送已读回执),消息发送方会通过已读回执的回调知晓接收方是否已读。

本端发送已读回执成功后,其他登录客户端和消息发送方均会收到已读回执回调。

目前 NIM SDK 支持单聊消息已读回执和高级群消息已读回执功能。

单聊消息已读回执

前提条件

在实现单聊消息已读回执之前,请确保已初始化 SDK

API 调用时序

uml diagram

实现步骤

以下仅介绍主要步骤,登录等常见步骤省略,具体请参考登录 IM章节。

  1. 消息发送方需要注册消息监听器,监听单聊已读回执回调事件。消息接收方需要注册消息监听器,监听消息接收回调事件。

    Android/iOS/macOS/Windows

    调用 addMessageListener 方法注册消息监听器,监听单聊已读回执回调事件 onReceiveP2PMessageReadReceipts和消息接收回调事件 onReceiveMessages

    Android
    javaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
    
    V2NIMMessageListener messageListener = new V2NIMMessageListener() {
        @Override
        public void onReceiveP2PMessageReadReceipts(List<V2NIMP2PMessageReadReceipt> readReceipts) {
    
        }
    
        @Override
        public void onReceiveMessages(List<V2NIMMessage> messages) {
    
        }
    };
    
    v2MessageService.addMessageListener(messageListener);
    
    iOS
    objective-c[[[NIMSDK sharedSDK] v2MessageService] addMessageListener:listener];
    
    macOS/Windows
    cppV2NIMMessageListener listener;
    listener.onReceiveP2PMessageReadReceipts = [](std::vector<V2NIMP2PMessageReadReceipt> readReceipts) {
        // receive p2p message read receipts
    };
    listener.onReceiveMessages = [](std::vector<V2NIMMessage> messages) {
        // receive messages
    };
    messageService.addMessageListener(listener);
    

    Web/uni-app/小程序/Harmony

    调用 on("EventName") 方法注册消息相关监听器,监听单聊已读回执事件onReceiveP2PMessageReadReceipts和消息接收回调事件onReceiveMessages

    Web/uni-app/小程序
    typescriptnim.V2NIMMessageService.on("onReceiveP2PMessageReadReceipts", function (readReceipts: V2NIMP2PMessageReadReceipt[]) {})
    nim.V2NIMMessageService.on("onReceiveMessages", function (messages: V2NIMMessage[]) {})
    
    Harmony
    typescriptnim.messageService.on("onReceiveP2PMessageReadReceipts", function (readReceipts: V2NIMP2PMessageReadReceipt[]) {})
    nim.messageService.on("onReceiveMessages", function (messages: V2NIMMessage[]) {})
    
  2. 消息发送方调用 createTextMessage 方法构造一条文本消息,然后调用 sendMessage 方法发送给接收方。

    接收方会通过回调接收消息 V2NIMMessage

    参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId String - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。在单聊场景中,不判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),即默认都需要已读回执。但是当该消息转发至群聊,群聊场景下需要判断是否需要已读回执,会读取消息对象的 readReceiptEnabled 字段,true 才发送群聊已读回执。因此在单聊场景下也建议用户按需设置该参数。
    success V2NIMSuccessCallback - 消息发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback - 消息发送失败回调,返回错误码。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。
    iOS
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId NSString * - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。在单聊场景中,不判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),即默认都需要已读回执。但是当该消息转发至群聊,群聊场景下需要判断是否需要已读回执,会读取消息对象的 readReceiptEnabled 字段,true 才发送群聊已读回执。因此在单聊场景下也建议用户按需设置该参数。
    success V2NIMSuccessCallback - 消息发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback - 消息发送失败回调,返回错误码。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId nstd::string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。在单聊场景中,不判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),即默认都需要已读回执。但是当该消息转发至群聊,群聊场景下需要判断是否需要已读回执,会读取消息对象的 readReceiptEnabled 字段,true 才发送群聊已读回执。因此在单聊场景下也建议用户按需设置该参数。
    success V2NIMSuccessCallback - 消息发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback - 消息发送失败回调,返回错误码。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。在单聊场景中,不判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),即默认都需要已读回执。但是当该消息转发至群聊,群聊场景下需要判断是否需要已读回执,会读取消息对象的 readReceiptEnabled 字段,true 才发送群聊已读回执。因此在单聊场景下也建议用户按需设置该参数。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。在单聊场景中,不判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),即默认都需要已读回执。但是当该消息转发至群聊,群聊场景下需要判断是否需要已读回执,会读取消息对象的 readReceiptEnabled 字段,true 才发送群聊已读回执。因此在单聊场景下也建议用户按需设置该参数。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。

    示例代码:

    Android
    V2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
    // 创建一条文本消息
    V2NIMMessage v2Message = V2NIMMessageCreator.createTextMessage("xxx");
    // 以单聊类型为例
    String conversationId = V2NIMConversationIdUtil.conversationId("xxx", V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P);
    // 发送消息
    v2MessageService.sendMessage(v2Message, conversationId, sendMessageParams,
            new V2NIMSuccessCallback<V2NIMSendMessageResult>() {
                @Override
                public void onSuccess(V2NIMSendMessageResult v2NIMSendMessageResult) {
                    // TODO: 发送成功
                }
            },
            new V2NIMFailureCallback() {
                @Override
                public void onFailure(V2NIMError error) {
                    // TODO: 发送失败
                }
            }
    );
    
    iOS
    // 创建一条文本消息
    V2NIMMessage *message = [V2NIMMessageCreator createTextMessage:@"v2 message"];
    V2NIMSendMessageParams *params = [[V2NIMSendMessageParams alloc] init];
    // 发送消息
    [[[NIMSDK sharedSDK] v2MessageService] sendMessage:message 
                                        conversationId:@"conversationId"
                                                params:params
                                            success:^(V2NIMSendMessageResult * _Nonull result) {
                                                // 发送成功回调
                                                }
                                            failure:^(V2NIMError * _Nonnull error) {
                                                // 发送失败回调, error 包含错误原因
                                                }
    }];          
    
    macOS/Windows
    // 以单聊类型为例
    auto conversationId = V2NIMConversationIdUtil::p2pConversationId("target_account_id");
    // 创建一条文本消息
    auto message = V2NIMMessageCreator::createTextMessage("hello world");
    auto params = V2NIMSendMessageParams();
    // 发送消息
    messageService.sendMessage(
        message,
        conversationId,
        params,
        [](V2NIMSendMessageResult result) {
            // send message succeeded
        },
        [](V2NIMError error) {
            // send message failed, handle error
        });
    
    Web/uni-app/小程序
    try {
    // 创建一条文本消息
    const message: V2NIMMessage = nim.V2NIMMessageCreator.createTextMessage("hello");
    // 发送消息
    const res: V2NIMSendMessageResult = await nim.V2NIMMessageService.sendMessage(message, 'test1|1|test2');
    // todo success
    } catch (err) {
    // todo error
    }
    
    Harmony
    try {
    // 创建一条文本消息
    const message: V2NIMMessage = nim.messageCreator.createTextMessage("hello")
    // 发送消息
    const res: V2NIMSendMessageResult = await nim.messageService.sendMessage(message, 'test1|1|test2')
    // todo Success
    } catch (err) {
    // todo error
    }
    
  3. (可选)消息发送方在发送消息后,可调用isPeerRead 方法主动查询接收方是否已读。

    示例代码:

    Android
    V2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
    boolean isPeerRead = v2MessageService.isPeerRead(v2Message);
    
    iOS
    [[[NIMSDK sharedSDK] v2MessageService] isPeerRead:message];
    
    macOS/Windows
    V2NIMMessage message;
    // ...
    bool peerRead = messageService.isPeerRead(message);
    
    Web/uni-app/小程序
    try {
    const res: boolean = nim.V2NIMMessageService.isPeerRead(message)
    // todo Success
    } catch (err) {
    // todo error
    }
    
    Harmony
    try {
    const res: boolean = nim.messageService.isPeerRead(message)
    // todo Success
    } catch (err) {
    // todo error
    }
    
  4. 消息接收方阅读消息后,调用 sendP2PMessageReceipt,给消息发送方发送单聊消息已读回执。调用时,传入接收方通过回调接收到的消息 V2NIMMessage

    参数说明:

    Android
    参数名称 类型 是否必填 描述
    message V2NIMMessage 消息对象,需要标记为已读的消息对象(即接收到的消息)。如在会话界面中调用该方法并传入当前会话的最后一条消息,即表示这之前的消息本方都已读。
    success V2NIMSuccessCallback 已读回执发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback 已读回执发送失败回调,返回错误码。
    iOS
    参数名称 类型 是否必填 描述
    message V2NIMMessage 消息对象,需要标记为已读的消息对象(即接收到的消息)。如在会话界面中调用该方法并传入当前会话的最后一条消息,即表示这之前的消息本方都已读。
    success V2NIMSuccessCallback 已读回执发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback 已读回执发送失败回调,返回错误码。
    macOS/Windows
    参数名称 类型 是否必填 描述
    message V2NIMMessage 消息对象,需要标记为已读的消息对象(即接收到的消息)。如在会话界面中调用该方法并传入当前会话的最后一条消息,即表示这之前的消息本方都已读。
    success V2NIMSuccessCallback 已读回执发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback 已读回执发送失败回调,返回错误码。
    Web/uni-app/小程序
    参数名称 类型 是否必填 描述
    message V2NIMMessage 消息对象,需要标记为已读的消息对象(即接收到的消息)。如在会话界面中调用该方法并传入当前会话的最后一条消息,即表示这之前的消息本方都已读。
    Harmony
    参数名称 类型 是否必填 描述
    message V2NIMMessage 消息对象,需要标记为已读的消息对象(即接收到的消息)。如在会话界面中调用该方法并传入当前会话的最后一条消息,即表示这之前的消息本方都已读。

    示例代码:

    Android
    javaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
    
    // V2NIMMessage v2Message
    v2MessageService.sendP2PMessageReceipt(v2Message,
        new V2NIMSuccessCallback<Void>() {
            @Override
            public void onSuccess(Void unused) {
    
            }
        },
        new V2NIMFailureCallback() {
            @Override
            public void onFailure(V2NIMError error) {
    
            }
        }
    );
    
    iOS
    [[[NIMSDK sharedSDK] v2MessageService] sendP2PMessageReceipt:message 
                                                         success:^{
        //发送成功
        }
                                                         failure:^(V2NIMError * _Nonnull error) {
        //error 包含错误原因
    }];
    
    macOS/Windows
    cppV2NIMMessage message;
    // ...
    messageService.sendP2PMessageReceipt(
        message,
        []() {
            // send p2p message receipt succeeded
        },
        [](V2NIMError error) {
            // send p2p message receipt failed, handle error
        });  
    
    Web/uni-app/小程序
    try {
    await nim.V2NIMMessageService.sendP2PMessageReceipt(message)
    // todo Success
    } catch (err) {
    // todo error
    }
    
    Harmony
    try {
    await nim.messageService.sendP2PMessageReceipt(message)
    // todo Success
    } catch (err) {
    // todo error
    }
    
  5. 消息发送方会通过回调接收到消息已读回执(V2NIMP2PMessageReadReceipt)。

高级群消息已读回执

群消息已读回执功能仅支持 200 人以内的高级群。

前提条件

在实现高级群消息已读回执之前,请确保:

  • 初始化 SDK

  • 已在控制台开通群聊消息已读回执功能,具体请参见配置群组功能

  • 已创建群组且消息发送方和接收方已加入群组。

API 调用时序

uml diagram

实现步骤

以下仅介绍主要步骤,登录等常见步骤省略,具体请参考登录 IM章节。

  1. 消息发送方需要注册消息监听器,监听高级群已读回执回调事件。消息接收方需要注册消息监听器,监听消息接收回调事件。

    Android/iOS/macOS/Windows

    调用 addMessageListener 方法注册消息监听器,监听高级群已读回执回调事件onReceiveTeamMessageReadReceipts和消息接收回调事件onReceiveMessages

    Android
    javaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
    
    V2NIMMessageListener messageListener = new V2NIMMessageListener() {
        @Override
        public void onReceiveTeamMessageReadReceipts(List<V2NIMTeamMessageReadReceipt> readReceipts) {
            // TODO: 处理接收到的群消息已读回执
        }
    
        @Override
        public void onReceiveMessages(List<V2NIMMessage> messages) {
            // TODO: 处理接收到的消息
        }
    };
    
    v2MessageService.addMessageListener(messageListener);
    
    iOS
    objective-c[[[NIMSDK sharedSDK] v2MessageService] addMessageListener:listener];
    
    macOS/Windows
    cppV2NIMMessageListener listener;
    listener.onReceiveTeamMessageReadReceipts = [](std::vector<V2NIMTeamMessageReadReceipt> readReceipts) {
        // receive team message read receipts
    };
    listener.onReceiveMessages = [](std::vector<V2NIMMessage> messages) {
        // receive messages
    };
    messageService.addMessageListener(listener);
    

    Web/Harmony

    调用 on("EventName") 方法注册消息相关监听器,监听高级群已读回执事件onReceiveTeamMessageReadReceipts和消息接收回调事件onReceiveMessages

    Web/uni-app/小程序
    typescriptnim.V2NIMMessageService.on("onReceiveTeamMessageReadReceipts", function (readReceipts: V2NIMTeamMessageReadReceipt[]) {})
    nim.V2NIMMessageService.on("onReceiveMessages", function(messages: V2NIMMessage[]) {})
    
    Harmony
    typescriptnim.messageService.on("onReceiveTeamMessageReadReceipts", function (readReceipts: V2NIMTeamMessageReadReceipt[]) {})
    nim.messageService.on("onReceiveMessages", function(messages: V2NIMMessage[]) {})
    
  2. 消息发送方调用 createTextMessage 方法构造一条文本消息,然后调用 sendMessage 方法在群组中发送该消息。

    接收方会通过回调接收消息 V2NIMMessage

    参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId String - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    • 在群聊场景中,必须判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),只有设置为 true 才发送群聊已读回执。
    • 由于群组成员较多,不建议每条消息都设置为需要已读回执,可以只针对重要消息指定需要已读回执。
    success V2NIMSuccessCallback - 消息发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback - 消息发送失败回调,返回错误码。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。
    iOS
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId NSString * - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    • 在群聊场景中,必须判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),只有设置为 true 才发送群聊已读回执。
    • 由于群组成员较多,不建议每条消息都设置为需要已读回执,可以只针对重要消息指定需要已读回执。
    success V2NIMSuccessCallback - 消息发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback - 消息发送失败回调,返回错误码。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId nstd::string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    • 在群聊场景中,必须判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),只有设置为 true 才发送群聊已读回执。
    • 由于群组成员较多,不建议每条消息都设置为需要已读回执,可以只针对重要消息指定需要已读回执。
    success V2NIMSuccessCallback - 消息发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback - 消息发送失败回调,返回错误码。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    • 在群聊场景中,必须判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),只有设置为 true 才发送群聊已读回执。
    • 由于群组成员较多,不建议每条消息都设置为需要已读回执,可以只针对重要消息指定需要已读回执。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    message V2NIMMessage - 消息对象,通过调用 createTextMessage 接口创建。如果为空或不存在则返回 191004 参数错误。
    conversationId string - 会话 ID,通过调用 V2NIMConversationIdUtil 的对应函数创建。
    组成方式:发送者用户账号|会话类型(V2NIMConversationType)|接收者用户账号或群组 ID。此处的接收者需要设为用户 C。如果为空或不存在则返回 191004 参数错误。
    params V2NIMSendMessageParams null 消息发送配置参数,包括发送、推送、抄送、反垃圾等配置。
    • 在群聊场景中,必须判断消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),只有设置为 true 才发送群聊已读回执。
    • 由于群组成员较多,不建议每条消息都设置为需要已读回执,可以只针对重要消息指定需要已读回执。
    progress V2NIMProgressCallback null 附件上传进度回调,用于图片、语音、视频、文件类型消息。

    示例代码:

    Android
    V2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
    // 创建一条文本消息
    V2NIMMessage v2Message = V2NIMMessageCreator.createTextMessage("xxx");
    // 群聊类型
    String conversationId = V2NIMConversationIdUtil.conversationId("xxx", V2NIMConversationType.V2NIM_CONVERSATION_TYPE_TEAM);
    // 发送消息
    v2MessageService.sendMessage(v2Message, conversationId, sendMessageParams,
            new V2NIMSuccessCallback<V2NIMSendMessageResult>() {
                @Override
                public void onSuccess(V2NIMSendMessageResult v2NIMSendMessageResult) {
                    // TODO: 发送成功
                }
            },
            new V2NIMFailureCallback() {
                @Override
                public void onFailure(V2NIMError error) {
                    // TODO: 发送失败
                }
            }
    );
    
    iOS
    // 创建一条文本消息
    V2NIMMessage *message = [V2NIMMessageCreator createTextMessage:@"v2 message"];
    V2NIMSendMessageParams *params = [[V2NIMSendMessageParams alloc] init];
    // 发送消息
    [[[NIMSDK sharedSDK] v2MessageService] sendMessage:message 
                                        conversationId:@"conversationId"
                                                params:params
                                            success:^(V2NIMSendMessageResult * _Nonull result) {
                                                // 发送成功回调
                                                }
                                            failure:^(V2NIMError * _Nonnull error) {
                                                // 发送失败回调, error 包含错误原因
                                                }
    }];          
    
    macOS/Windows
    // 群聊类型
    auto conversationId = V2NIMConversationIdUtil::teamConversationId("target_team_id");
    // 创建一条文本消息
    auto message = V2NIMMessageCreator::createTextMessage("hello world");
    auto params = V2NIMSendMessageParams();
    // 发送消息
    messageService.sendMessage(
        message,
        conversationId,
        params,
        [](V2NIMSendMessageResult result) {
            // send message succeeded
        },
        [](V2NIMError error) {
            // send message failed, handle error
        });
    
    Web/uni-app/小程序
    try {
    // 创建一条文本消息
    const message: V2NIMMessage = nim.V2NIMMessageCreator.createTextMessage("hello");
    // 发送消息
    const res: V2NIMSendMessageResult = await nim.V2NIMMessageService.sendMessage(message, 'test1|1|test2');
    // todo success
    } catch (err) {
    // todo error
    }
    
    Harmony
    try {
    // 创建一条文本消息
    const message: V2NIMMessage = nim.messageCreator.createTextMessage("hello")
    // 发送消息
    const res: V2NIMSendMessageResult = await nim.messageService.sendMessage(message, 'test1|1|test2')
    // todo Success
    } catch (err) {
    // todo error
    }
    
  3. 消息接收方阅读消息后,通过判断该消息是否需要已读回执(V2NIMMessageConfig.readReceiptEnabled),若需要,则调用 sendTeamMessageReceipts,给消息发送方发送群聊消息已读回执。

    参数说明:

    Android
    参数名称 类型 是否必填 默认值 描述
    messages List<V2NIMMessage> 消息对象列表,需要发送已读回执的消息列表,一次最多传入 50 个消息对象。
    success V2NIMSuccessCallback 已读回执发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback 已读回执发送失败回调,返回错误码。
    iOS
    参数名称 类型 是否必填 默认值 描述
    messages List<V2NIMMessage> 消息对象列表,需要发送已读回执的消息列表,一次最多传入 50 个消息对象。
    success V2NIMSuccessCallback 已读回执发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback 已读回执发送失败回调,返回错误码。
    macOS/Windows
    参数名称 类型 是否必填 默认值 描述
    messages List<V2NIMMessage> 消息对象列表,需要发送已读回执的消息列表,一次最多传入 50 个消息对象。
    success V2NIMSuccessCallback 已读回执发送成功回调,返回 V2NIMSendMessageResult
    failure V2NIMFailureCallback 已读回执发送失败回调,返回错误码。
    Web/uni-app/小程序
    参数名称 类型 是否必填 默认值 描述
    messages List<V2NIMMessage> 消息对象列表,需要发送已读回执的消息列表,一次最多传入 50 个消息对象。
    Harmony
    参数名称 类型 是否必填 默认值 描述
    messages List<V2NIMMessage> 消息对象列表,需要发送已读回执的消息列表,一次最多传入 50 个消息对象。

    示例代码:

    Android
    javaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
    
    List<V2NIMMessage> v2Messages = ; // 需要发送已读回执的消息列表
    v2MessageService.sendTeamMessageReceipts(v2Messages,
            new V2NIMSuccessCallback<Void>() {
                @Override
                public void onSuccess(Void unused) {
    
                }
            },
            new V2NIMFailureCallback() {
                @Override
                public void onFailure(V2NIMError error) {
    
                }
            });
    
    iOS
    [[[NIMSDK sharedSDK] v2MessageService] sendTeamMessageReceipts:@[message]
                                                           success:^{
        //发送成功
        }
                                                           failure:^(V2NIMError * _Nonnull error) {
        //error 包含错误原因
    }];
    
    macOS/Windows
    cppnstd::vector<V2NIMMessage> messages;
    // ...
    messageService.sendTeamMessageReceipts(
        messages,
        []() {
            // send team message receipts succeeded
        },
        [](V2NIMError error) {
            // send team message receipts failed, handle error
        });
    
    Web/uni-app/小程序
    try {
    await nim.V2NIMMessageService.sendTeamMessageReceipts(messages)
    // todo Success
    } catch (err) {
    // todo error
    }
    
    Harmony
    try {
    await nim.messageService.sendTeamMessageReceipts(messages)
    // todo Success
    } catch (err) {
    // todo error
    }
    
  4. 消息发送方会通过回调接收到消息已读回执(V2NIMTeamMessageReadReceipt)。

已读回执其他操作

查询单聊消息的已读回执

在单聊会话中,消息发送方可以主动调用 getP2PMessageReceipt 接口查询指定消息的已读回执。

示例代码

Android
javaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);

v2MessageService.getP2PMessageReceipt("x|x|x",
        new V2NIMSuccessCallback<V2NIMP2PMessageReadReceipt>() {
            @Override
            public void onSuccess(V2NIMP2PMessageReadReceipt v2NIMP2PMessageReadReceipt) {

            }
        },
        new V2NIMFailureCallback() {
            @Override
            public void onFailure(V2NIMError error) {

            }
        });
iOS
objective-c[[[NIMSDK sharedSDK] v2MessageService] getP2PMessageReceipt:@"conversationId"
                                                     success:^(V2NIMP2PMessageReadReceipt * _Nonnull receipt) {
    //receipt 详见:V2NIMP2PMessageReadReceipt
}
                                                     failure:^(V2NIMError * _Nonnull error) {
    //error 包含错误原因
}];
macOS/Windows
cppauto conversationId = V2NIMConversationIdUtil::p2pConversationId("target_account_id");
messageService.getP2PMessageReceipt(
    conversationId,
    [](V2NIMP2PMessageReadReceipt receipt) {
        // get p2p message receipt succeeded
    },
    [](V2NIMError error) {
        // get p2p message receipt failed, handle error
    }
);
Web/uni-app/小程序
typescripttry {
  const res: V2NIMP2PMessageReadReceipt = await nim.V2NIMMessageService.getP2PMessageReceipt('me|1|another');
  // todo: Success
} catch (err) {
  // todo: error
}
Harmony
typescripttry {
  const res: V2NIMP2PMessageReadReceipt = await nim.messageService.getP2PMessageReceipt('me|1|another')
  // todo Success
} catch (err) {
  // todo error
}

查询群聊消息的已读回执

在高级群会话中,消息发送方可以主动调用 getTeamMessageReceipts 方法查询指定消息的多条已读回执。

  • 一次最多查询 50 条消息,且所有消息必须属于同一个会话,即一次只能查询一个会话中的 50 条消息,否则将报 191001 错误。
  • 调用成功后,只返回存在且有效的消息的已读回执。

示例代码

Android
javaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);

// List<V2NIMMessage> v2Messages = ; // 需要查询已读回执状态的消息
v2MessageService.getTeamMessageReceipts(v2Messages,
        new V2NIMSuccessCallback<List<V2NIMTeamMessageReadReceipt>>() {
            @Override
            public void onSuccess(List<V2NIMTeamMessageReadReceipt> v2NIMTeamMessageReadReceipts) {

            }
        },
        new V2NIMFailureCallback() {
            @Override
            public void onFailure(V2NIMError error) {

            }
        });
iOS
objective-c[[[NIMSDK sharedSDK] v2MessageService] getTeamMessageReceipts:@[message]
                                                       success:^(NSArray<V2NIMTeamMessageReadReceipt *> * _Nonnull readReceipts) {
    //readReceipts 详见:V2NIMTeamMessageReadReceipt
}
                                                       failure:^(V2NIMError * _Nonnull error) {
    //error 包含错误原因
}];
macOS/Windows
cppnstd::vector<V2NIMMessage> messages;
// ...
messageService.getTeamMessageReceipts(
    messages,
    [](nstd::vector<V2NIMTeamMessageReadReceipt> receipts) {
        for (auto&& receipt : receipts) {
            // do something
        }
    },
    [](V2NIMError error) {
        // get team message receipts failed, handle error
    });
Web/uni-app/小程序
typescripttry {
  const res: V2NIMTeamMessageReadReceipt[] = await nim.V2NIMMessageService.getTeamMessageReceipts(messages);
  // todo: Success
} catch (err) {
  // todo: Error
}
Harmony
typescripttry {
  const res: V2NIMTeamMessageReadReceipt[] = await nim.messageService.getTeamMessageReceipts(messages)
  // todo Success
} catch (err) {
  // todo error
}

查询群聊消息的已读/未读状态

调用 getTeamMessageReceiptDetail 方法可查询群成员对指定群聊消息的已读/未读状态。

可以查询所有群成员对某消息的已读/未读状态,也可以查询部分群成员对某消息的已读/未读状态。

参数说明:

Android
参数名称 类型 是否必填 描述
messages V2NIMMessage 需要查询已读回执状态的群聊消息对象。
memberAccountIds Set<String> 需要查询的群成员列表。若为空,则查询所有群成员对目标消息的已读/未读状态。
success V2NIMSuccessCallback 查询已读回执成功回调。
failure V2NIMFailureCallback 查询已读回执失败回调,返回错误码。
iOS
参数名称 类型 是否必填 描述
messages V2NIMMessage 需要查询已读回执状态的群聊消息对象。
memberAccountIds NSSet * 需要查询的群成员列表。若为空,则查询所有群成员对目标消息的已读/未读状态。
success V2NIMSuccessCallback 查询已读回执成功回调。
failure V2NIMFailureCallback 查询已读回执失败回调,返回错误码。
macOS/Windows
参数名称 类型 是否必填 描述
messages V2NIMMessage 需要查询已读回执状态的群聊消息对象。
memberAccountIds nstd::setnstd::string 需要查询的群成员列表。若为空,则查询所有群成员对目标消息的已读/未读状态。
success V2NIMSuccessCallback 查询已读回执成功回调。
failure V2NIMFailureCallback 查询已读回执失败回调,返回错误码。
Web/uni-app/小程序
参数名称 类型 是否必填 描述
messages V2NIMMessage 需要查询已读回执状态的群聊消息对象。
memberAccountIds string[] 需要查询的群成员列表。若为空,则查询所有群成员对目标消息的已读/未读状态。
Harmony
参数名称 类型 是否必填 描述
messages V2NIMMessage 需要查询已读回执状态的群聊消息对象。
memberAccountIds string[] 需要查询的群成员列表。若为空,则查询所有群成员对目标消息的已读/未读状态。

示例代码

Android
javaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);

// V2NIMMessage message = ; // 需要查询已读回执状态的消息
// Set<String> memberAccountIds = ; // 指定账号列表
v2MessageService.getTeamMessageReceiptDetail(message, memberAccountIds,
        new V2NIMSuccessCallback<V2NIMTeamMessageReadReceiptDetail>() {
            @Override
            public void onSuccess(V2NIMTeamMessageReadReceiptDetail v2NIMTeamMessageReadReceiptDetail) {

            }
        },
        new V2NIMFailureCallback() {
            @Override
            public void onFailure(V2NIMError error) {

            }
        }
);
iOS
objective-c[[[NIMSDK sharedSDK] v2MessageService] getTeamMessageReceiptDetail:message
                                                      memberAccountIds:@[@"user1"]
                                                               success:^(V2NIMTeamMessageReadReceiptDetail * _Nonnull detail) {
        //detail 详见:V2NIMTeamMessageReadReceiptDetail
    }
                                                               failure:^(V2NIMError * _Nonnull error) {
        //error 包含错误原因
}];
macOS/Windows
cppV2NIMMessage message;
// ...
messageService.getTeamMessageReceiptDetail(
    message,
    {},
    [](V2NIMTeamMessageReadReceiptDetail readReceiptDetial) {
        // get team message receipt detail succeeded
    },
    [](V2NIMError error) {
        // get team message receipt detail failed, handle error
    }
);
Web/uni-app/小程序
typescripttry {
  const res: V2NIMTeamMessageReadReceiptDetail = await nim.V2NIMMessageService.getTeamMessageReceiptDetail(message);
  // todo: Success
} catch (err) {
  // todo: error
}
Harmony
typescripttry {
  const res: V2NIMTeamMessageReadReceiptDetail = await nim.messageService.getTeamMessageReceiptDetail(message)
  // todo Success
} catch (err) {
  // todo error
}
此文档是否对你有帮助?
有帮助
去反馈
  • 单聊消息已读回执
  • 前提条件
  • API 调用时序
  • 实现步骤
  • 高级群消息已读回执
  • 前提条件
  • API 调用时序
  • 实现步骤
  • 已读回执其他操作
  • 查询单聊消息的已读回执
  • 查询群聊消息的已读回执
  • 查询群聊消息的已读/未读状态