消息管理–获取消息的已读回执和送达回执

更新时间:2022-02-28

本文介绍环信即时通讯 IM SDK 如何从服务器获取消息的已读回执和送达回执。

环信即时通讯 IM 投递消息成功会返回送达回执,提供消息已读功能,接收方查看消息后,会返回已读回执。

功能 描述
消息送达回执 消息下发成功后,会返回消息送达回执。
消息已读回执 接收方查看消息后,会返回消息已读回执。
单个消息已读回执 提供单聊消息已读回执能力。
群组消息已读回执 提供群组消息已读回执能力。

使用环信即时通讯 IM Web SDK可以实现消息的送达回执与已读回执,主要方法如下:

  • 已送达回执:在 webim.config.js 中配置 deliverytrue,收到消息时会自动发送已送达回执,对方收到已送达回执的回调函数是 onDeliveredMessage。具体见 快速开始。(//todo:加跳转链接)

  • 已读回执存在以下两种情况:

    1、当认为用户已读某条(些)消息会生成已读回执,发送给对方,对方会通过 onReadMessage 回调收到已读回执。

    2、针对整个会话回复 channel ack 消息,表示整个会话的消息均已读。此回执消息旨在清空通过 getSessionList 获取的会话列表的未读数,比如调用 getSessionList 获取到会话列表,其中一个会话的未读消息数是 5,可在点击这个会话的时候回复一条 channel 消息,该会话的未读数会清零。

开始前,请确保满足以下条件:

  • 完成 SDK 初始化,并连接到服务器,详见 快速开始
  • 了解环信即时通讯 IM 的使用限制,详见 使用限制

消息送达回执

若在消息送达时收到通知,可打开消息送达开关,这样消息到达对方设备时,你便会收到通知。

  • 送达回执:创建 connection 对象时,设置 options 参数的 deliverytrue 即可开启送达回执功能。收到消息时 SDK 会自动发送送达回执,消息发送端会收到 onDeliveredMessage 回调。
  • onDeliveredMessage 回调是对方收到消息时的通知,你可以在收到该通知时会显示消息的送达状态。

示例代码如下:

// customEvent 用户可以自定义。
WebIM.conn.addEventHandler('customEvent', {
    onReceivedMessage: function(message){},    // 收到消息送达服务器回执。
    onDeliveredMessage: function(message){},   // 收到消息送达客户端回执。
});

消息已读回执

消息阅读后,可以发出已读回执。该回执需要你调用 API 实现,这样消息发送方可以知道消息已被阅读。下文分别介绍会话已读回执、单聊和群聊的消息已读回执。

发送会话已读回执

会话已读回执用于获知接收方是否阅读消息的场景,目前单聊可以直接集成,群聊需要联系客户经理单独开通。

注意

群消息已读回执功能为增值服务,仅旗舰版及以上支持,具体使用参考 群消息已读回执。

示例代码如下:

// 单聊。
let option = {
    chatType: 'singleChat', // 会话类型,设置为单聊。
    type: 'channel',        // 消息类型。
    to: 'userID'            // 接收消息对象(用户 ID)。
}
let msg = WebIM.message.create(option); 
WebIM.conn.send(msg);

// 群聊。
let option = {
    chatType: 'groupChat', // 会话类型,设置为群聊。
    type: 'channel',       // 消息类型。
    to: 'groupID'          // 消息接收方(群组 ID)。
}
let msg = WebIM.message.create(option); 
WebIM.conn.send(msg);
监听会话已读回执
// customEvent 用户可以自定义。
WebIM.conn.addEventHandler('customEvent', {
    onChannelMessage: (message) => {}
})

单聊发送已读回执

let option = {
    type: 'read',           // 消息是否已读。
    chatType: 'singleChat', // 会话类型,这里为单聊。
    to: 'userID',           // 消息接收方(用户 ID)。
    id: 'id'                // 需要发送已读回执的消息 ID。
}   
let msg = WebIM.message.create(option); 
WebIM.conn.send(msg);

监听单个消息的已读回执

可以在接收消息的的回调中监听某个消息是否已读,示例代码如下:

// customEvent 用户可以自定义。
WebIM.conn.addEventHandler('customEvent', {
    onReadMessage: (message) => {}
})

群聊消息已读回执

发送群组已读回执的消息 (需要群主或管理员权限)
sendGroupReadMsg = () => {
    let option = {
        type: 'txt',            // 消息类型。
        chatType: 'groupChat',  // 会话类型,这里为群聊。
        to: "groupId",          // 消息接收方(群组ID)。
        msg: 'message content'  // 消息内容。
        msgConfig: { allowGroupAck: true } // 设置此消息需要已读回执。
    }

    let msg = WebIM.message.create(option); 
    WebIM.conn.send(msg).then((res) => {
        console.log('send private text success');
    }).catch((e) => {
        console.log("send private text error");
    })

}
监听收到群组消息回执

分两种情况:

1、正常在线时可以在 onReadMessage 函数里监听到回执;

2、离线时收到群组消息回执,登录后会在 onStatisticMessage 函数里监听到回执。

// 在线时可以在 onReadMessage 里监听。
onReadMessage: (message) => {
    let { mid } = message;
    let msg = {
        id: mid
    };
    if(message.groupReadCount){
        // 消息已读数。
        msg.groupReadCount = message.groupReadCount[message.mid];
    }
}
      
// 离线时收到回执,登录后会在这里监听到。
onStatisticMessage: (message) => {
    let statisticMsg = message.location && JSON.parse(message.location);
    let groupAck = statisticMsg.group_ack || [];
}
收到回执消息后发送回执
sendReadMsg = () => {
    let option = {
        type: 'read',           // 消息是否已读。
        chatType: 'groupChat',  // 会话类型,这里为群聊。
        id: 'msgId',            // 需要发送已读回执的消息 ID。
        to: "groupId",          // 群组 ID。
        ackContent: JSON.stringify({}) // 回执内容。
    }  
    let msg = WebIM.message.create(option); 
    WebIM.conn.send(msg)
}
查看已读消息的用户
WebIM.conn.getGroupMsgReadUser({
    msgId,  // 消息 ID。
    groupId // 群组 ID。
}).then((res)=>{
    console.log(res)
})