当发送方需要知道接收方是否已经阅读了自己发送的消息时，需要使用已读回执的功能。

单聊消息已读回执

本节以发送方和接收方的消息交互场景为例，介绍单聊消息已读回执的实现流程。

API 调用时序

sequenceDiagram



note over NIM SDK: 初始化与登录
发送方 ->> NIM SDK: 初始化
note left of 发送方: 初始化时注册消息已读通知回调<br>(onMsgReceipts)
接收方 ->> NIM SDK: 初始化
发送方 ->> NIM SDK: 登录
接收方 ->> NIM SDK: 登录
note over NIM SDK: 消息收发
发送方 ->> NIM SDK: 发送消息
NIM SDK ->> 接收方: NIMMessage
note over NIM SDK: 发送已读回执
接收方 ->> NIM SDK: 发送消息已读回执<br>(sendMsgReceipt)
NIM SDK ->> 发送方: 消息已读通知<br>(MsgReceipts)

前提条件

• 已集成 SDK。
• 已注册云信 IM 账号，获取 accid 和 token。

实现流程

1. 消息发送方在初始化时注册 onMsgReceipts 接收消息已读回执回调函数（注：仅在发送方在线时可触发回调）。

2. 消息接收方在收到消息并阅读后，调用sendMsgReceipt方法发送已读回执，调用时传入接收到的消息。

   如在会话界面中调用该方法并传入当前会话的最后一条消息，即表示这之前的消息本方都已读。

   
   

   示例代码如下：

   nim.sendMsgReceipt({
       msg: session.lastMsg,
       done: sendMsgReceiptDone
   });
   function sendMsgReceiptDone(error, obj) {
       console.log('发送消息已读回执' + (!error?'成功':'失败'), error, obj);
   }
   
   

3. 如果发送方在线，那么发送方将收到消息已读通知。

通知消息格式如下：

{
  MsgReceipts: [
    {
      idClient: "",
      msgReceiptTime: "",
      sessionId: ""
    }
  ]

群聊消息已读回执

本节以发送方与接收方的消息交互为例，介绍群聊消息已读回执的实现流程。

API 调用时序

sequenceDiagram



note over NIM SDK: 初始化与登录
消息发送方 ->> NIM SDK: 初始化
note left of 消息发送方: 初始化时注册群消息已读通知回调<br>(onTeamMsgReceipt)
消息接收方 ->> NIM SDK: 初始化
消息发送方 ->> NIM SDK: 登录
消息接收方 ->> NIM SDK: 登录
note over NIM SDK: 人员加入群组
消息发送方 ->> NIM SDK: 创建群组
消息接收方 ->> NIM SDK: 加入群组
note over NIM SDK: 消息收发
消息发送方 ->> NIM SDK: 发送消息
note left of 消息发送方: 发消息时设置需要已读回执<br>(needMsgReceipt=true)
NIM SDK ->> 消息接收方: NIMMessage
note over NIM SDK: 发送已读回执
消息接收方 ->> 消息接收方: 通过NIMMessage的<br>needMsgReceipt属性<br>判断是否需要发送已读回执
消息接收方 ->> NIM SDK: 发送已读回执<br>(sendTeamMsgReceipt)
NIM SDK ->> 消息发送方: 群消息已读通知<br>(teamMsgReceipts)

前提条件

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

• 已创建云信 IM 账号。

使用限制

使用群消息已读回执功能，需将群成员控制在 200 人以内。

实现流程

1. 发送方在初始化时，注册onTeamMsgReceipt接收群消息已读回执回调函数（注：仅在发送方在线时可触发回调）。

2. 发送方发送群消息时，将needMsgReceipt设置为 true，标记该消息需要已读回执。只有设置为需要已读回执，后续才会触发已读回执的通知。

   • 发送群消息只需要把消息发送接口的scene设置为team即可。更多消息收发相关说明参见消息收发。
   • 发送单聊消息（p2p 场景）时，无需设置 needMsgReceipt 属性。

3. 接收方接收到消息后，通过该消息的needMsgReceipt属性判断该消息是否需要发送已读回执。

4. 接收方调用 sendTeamMsgReceipt方法发送已读回执。

   该接口可以发送多个群组、多条消息的已读回执。需注意的是，传参中teamMsgReceipts可传入的群消息个数上限为50。

   请求参数	说明
   teamMsgReceipts	需要发送回执的消息配置列表
   teamMsgReceipt.teamId	群组 ID
   teamMsgReceipt.idServer	云信服务端生成的消息 ID
   done	回调函数

   done 的回调结果	说明
   error	第一个参数，如果为null表示成功
   obj	第二个参数，发送的参数(用于校验)
   content	第三个参数，content.teamMsgReceipts：失败的账号列表

   示例代码如下：

   nim.sendTeamMsgReceipt({
       teamMsgReceipts: [{
       teamId: '1027484',
       idServer: '68953284018302'
       }],
       done: sendTeamMsgReceiptDone
   })
   function sendTeamMsgReceiptDone (error, obj, content) {
       console.log('标记群组消息已读' + (!error?'成功':'失败'));
   }
   

5. 如果发送方在线，那么发送方将收到群消息已读通知。

   通知消息格式如下：

     {
       teamMsgReceipts: [
         {
           account: "cs3",
           idClient: "5b77d3ff7eb06af5567f56647518694b",
           idServer: "68953284018340",
           read: "1",
           teamId: "1027484",
           unread: "1"
         }
       ]
   

后续操作

消息发送方获取到群聊消息已读回执后，可调用如下方法查询已读/未读账号列表或查询单条消息的已读/未读数。

查询群消息已读/未读账号列表

调用getTeamMsgReadAccounts方法可查询单条群组消息的已读/未读账号列表。

请求参数	说明
teamMsgReceipt	待查询的群消息列表
teamMsgReceipt.teamId	群组 ID
teamMsgReceipt.idServer	云信服务端生成的消息 ID
done	回调函数

done 的回调结果	说明
error	第一个参数，如果为 null 表示成功
obj	第二个参数，发送的参数(用于校验)
content	第三个参数，账号列表 idClient：客户端生成的消息 ID readAccounts：已读帐号列表 unreadAccounts：未读帐号列表

示例代码

  nim.getTeamMsgReadAccounts({
    teamMsgReceipt: {
      teamId: '1027484',
      idServer: '68953284018302'
    },
    done: getTeamMsgReadAccountsDone
  })
  function getTeamMsgReadAccountsDone (error, obj, content) {
    console.log('获取群组消息已读' + (!error?'成功':'失败'));
    /* content.teamMsgReceipt 为
      idClient: "c7575fca32bf142787986e752fdeff6a",
      readAccounts: Array[],
      unreadAccounts: Array[]
    */

查询群消息已读/未读数量

调用getTeamMsgReads方法可从本地数据库查询单条或多条群组消息已读/未读账号列表。

传参中teamMsgReceipts可传入的群消息个数上限为50。

请求参数	说明
teamMsgReceipts	待查询的群消息列表
teamMsgReceipt.teamId	群组 ID
teamMsgReceipt.idServer	云信服务端生成的群消息 ID
done	回调函数

done 的回调结果	说明
error	第一个参数，如果为 null 表示成功
obj	第二个参数，发送的参数(用于校验)
content	第三个参数，查询结果。如果是多个群消息配置的结果，则该字段的teamMsgReceipts 数组顺序与查询配置一致

示例代码

  nim.getTeamMsgReads({
    teamMsgReceipts: [{
      teamId: '1027484',
      idServer: '68953284018302'
    }],
    done: getTeamMsgReadsDone
  })
  function getTeamMsgReadsDone (error, obj, content) {
    console.log('获取群组消息已读' + (!error?'成功':'失败'));
    /* content.teamMsgReceipts 为
      [ {
        idClient: "c7575fca32bf142787986e752fdeff6a"
        idServer: "68527276949899"
        read: "0"
        teamId: "1021136"
        unread: "187"
      } ]
    */

API参考

API	说明
sendMsgReceipt	发送单聊消息已读回执
sendTeamMsgReceipt	发送群聊消息已读回执
getTeamMsgReadAccounts	查询单条群组消息的已读/未读账号列表
getTeamMsgReads	查询群组消息的已读、未读数量