当前页

消息表态

2026-04-02

功能简介

消息表态,是指用户对消息的反应。一般可用于对单聊或群聊的消息添加或删除表情,也可用于发起群组投票、确认群组结果等操作。

4_ 消息表态_中文.png
说明

以上仅为表态消息的 UI 示意图,ZIM SDK 不提供相关表态的美术资源,需要由您自行实现。

实现流程

ZIM SDK 支持对单聊或群聊会话中的指定消息进行表态。以客户端 B 对来自客户端 A 的消息增删表态为例:

  1. 客户端 A 和 客户端 B 分别创建自己的 ZIM 实例,并注册 on 监听的 messageReactionsChanged 回调接口,监听消息表态的相关通知。
  1. 客户端 A 和 客户端 B 分别登录 ZIM SDK。
  2. 客户端 A 向 客户端 B 发送单聊消息后,客户端 B 对该消息进行表态时:
    1. 客户端 B 调用 addMessageReaction 接口,传入参数 reactionType 和 message ,表态指定的消息。
    2. 客户端 B 通过 ZIMMessageReactionAddedResult 回调接口得知表态操作的结果。
    3. 客户端 A 通过 messageReactionsChanged 回调得知消息表态的相关通知。
  3. 客户端 B 删除上述表态时:
    1. 客户端 B 调用 deleteMessageReaction 接口,传入参数 reactionType 和 message ,表态指定的消息。
    2. 客户端 B 通过 ZIMMessageReactionDeletedResult 回调接口得知表态操作的结果。
    3. 客户端 A 通过 messageReactionsChanged 回调得知消息表态的相关通知。

1 监听消息表态

用户创建 ZIM 示例后,需要注册 on 监听的 messageReactionsChanged 回调接口,监听消息表态的相关通知。

当其他用户增加或删除对某条消息的表态后,可以直接获取表态的相关信息,包括表态的类型和人数等。通过此回调可获取的用户信息有限,一般为 5 名用户,如需了解表态相关的更多用户信息,请参考 更多功能

// 收到消息表态回调
zim.on('messageReactionsChanged', (zim: ZIM, data: ZIMEventOfMessageReactionsChangedResult) => {
});

2 新增消息表态 & 重复表态计数

在单聊或群聊会话发送消息后,您可以调用 addMessageReaction 对任意消息进行表态。增加表态操作的结果将通过 ZIMMessageReactionAddedResult 返回。通过此 callback 可获取的用户信息有限,一般为 5 名用户,如需了解表态相关的更多用户信息,请参考 更多功能

注意
  • 在 2.28.0 之前的版本,重复调用本接口对同一条消息进行相同类型的表态会抛出错误信息。
  • 在 2.28.0 以及之后的版本,通过配置 config 参数对同一条消息进行相同类型的表态,可实现重复表态和计数功能。
  • 一条消息默认表态类型上限为 100,如需调整,请联系 ZEGO 技术支持。
const reactionType = "key";
const messageObj: ZIMMessage = {};

// 添加消息表态
zim.addMessageReaction(reactionType, messageObj)
    .then((res: ZIMMessageReactionAddedResult) => {
        // 操作成功,在 UI 上更新该消息的表态列表
    })
    .catch((err: ZIMError) => {
        // 操作失败
    });


// 2.28.0 开始支持:重复表态-计数
const config: ZIMMessageReactionAddConfig = {
    // 表态计数增量值,要求正整数。
    // 当高频表态时,开发者可聚合增量值,只调用一次该接口:比如短时间表态 10 次,可设置为 10,然后只调用一次(避免高频调用影响服务端性能)
    increaseCount: 1
};
zim.addMessageReaction(reactionType, messageObj, config)
    .then((res: ZIMMessageReactionAddedResult) => {
        // 操作成功,在 UI 上更新该消息的表态列表
    })
    .catch((err: ZIMError) => {
        // 操作失败
    });    

3 删除消息某个表态 & 删除消息全部表态

对消息表态后,您可以调用 deleteMessageReaction 删除该表态。删除操作的结果将通过 ZIMMessageReactionDeletedResult 返回。通过此 callback 可获取的用户信息有限,一般为 5 名用户,如需了解表态相关的更多用户信息,请参考 更多功能

在 2.28.0 以及之后的版本,支持调用 deleteMessageAllReactions 删除消息的全部表态。

注意

调用本接口只能删除自己所作的表态。如果是重复表态,调用本接口会将自己的重复表态数量清零,且不会影响其他用户的重复表态数量。

// 删除某个表态
const reactionType = "key";
const messageObj: ZIMMessage = {};

zim.deleteMessageReaction(reactionType, messageObj)
    .then((res: ZIMMessageReactionDeletedResult) => {
        // 操作成功,在 UI 上更新该消息的表态列表
    })
    .catch((err: ZIMError) => {
        // 操作失败
    });

// 2.28.0 开始支持:删除全部表态
zim.deleteMessageAllReactions(messageObj)
    .then(() => {
        // 操作成功,在 UI 上更新该消息的表态列表
    })
    .catch((err: ZIMError) => {
        // 操作失败
    });    

更多功能

查询某个表态的用户列表 & 按用户维度查询所有表态计数

表态操作(监听、增加以及删除表态)只会返回概要用户信息,默认是 5 个,如需调整,请联系 ZEGO 技术支持。因此,当需要查询有哪些用户对某条消息作出了指定类型表态时,可以通过调用 queryMessageReactionUserList 进行查询。操作的结果将通过 ZIMMessageReactionUserListQueriedResult 返回,可知有哪些用户对这条消息增加了这种类型的表态。

如果实现了重复表态计数功能,也可通过该接口查询用户的所有表态计数,返回的列表按用户的总表态数量倒序排序。

// 查询某个表态的用户列表
const config: ZIMMessageReactionUserQueryConfig = {
    reactionType: "key",
    // count 超过 100 条会返回报错
    count: 20,
    nextFlag: 0,
};
const messageObj: ZIMMessage = {};

zim.queryMessageReactionUserList(messageObj, config)
    .then((res: ZIMMessageReactionUserListQueriedResult) => {
        // 操作成功
        // 遍历 res.userInfoList,从中获取 userID
    })
    .catch((err: ZIMError) => {
        // 操作失败
    });


// 2.28.0 开始支持:按用户维度查询所有表态计数
const config: ZIMMessageReactionUserQueryConfig = {
    reactionType: "", // 表态类型需要为空
    // count 超过 100 条会返回报错
    count: 20,
    nextFlag: 0,
};
const messageObj: ZIMMessage = {};

zim.queryMessageReactionUserList(messageObj, config)
    .then((res: ZIMMessageReactionUserListQueriedResult) => {
        // 操作成功
        // 遍历 res.userInfoList,从中获取 userID 和 reactions(表态类型和计数)
    })
    .catch((err: ZIMError) => {
        // 操作失败
    });    

上一篇

消息回执

下一篇

消息置顶

当前页

返回到顶部