Respond to messages with emoticons

2026-04-02

Overview

An emoticon response to a message indicates how a user responds to a message. The emoticon response feature is usually used to respond to a message in a private chat or group chat by adding an emoticon response to or removing an emoticon response from the message. Further, the emoticon response feature can be used in scenarios such as group voting and group voting result confirmation.

Note

The preceding figure shows merely a UI example of an emoticon response. ZEGO Instant Messaging (ZIM) SDK does not provide aesthetics resources for emoticon responses. You must add aesthetics resources as needed.

Procedure

ZIM SDK allows you to respond to a specific message in a private chat or group chat. The procedure is described in the following figure, in which a client B responds to a message from a client A by adding an emoticon response to or removing an emoticon response from the message.

The client A and the client B each create a ZIM instance and register the messageReactionsChanged callback of the ZIMEventHandler class to listen to emoticon response changes.
The client A and the client B log in to ZIM SDK.
The client A sends a private-chat message to the client B, and the client B adds an emoticon response to the message.
1. The client B calls the addMessageReaction operation and set the reactionType and message parameters to specify the message to which an emoticon response is added.
2. The client B obtains the addition result by invoking the ZIMMessageReactionAddedResult callback.
3. The client A receives a notification about an emoticon response change by invoking the messageReactionsChanged callback.
The client B removes the preceding emoticon response.
1. The client B calls the deleteMessageReaction operation and set the reactionType and message parameters to specify the message whose emoticon response is to be removed.
2. The client B obtains the removal result by invoking the ZIMMessageReactionDeletedResult callback.
3. The client A receives a notification about an emoticon response change by invoking the messageReactionsChanged callback.

1. Listen to an emoticon response change

After a user creates a ZIM instance, the user must register the messageReactionsChanged callback of the ZIMEventHandler class to listen to emoticon response changes. This way, when other users add emoticon responses to or remove emoticon responses from a specific message, the user that registers the onMessageReactionsChanged callback can obtain relevant emoticon response information, such as the types of the emoticon responses and the number of users who add emoticon responses or remove emoticon responses. In general, this callback can return information about a maximum of five users. For more user information details, see the "Query details of emoticon responses" section of the Respond to messages with emoticons topic.

//  Received message with emoticons callback.
zim.on('messageReactionsChanged', (zim: ZIM, data: ZIMEventOfMessageReactionsChangedResult) => {
});

//  Received message with emoticons callback.
zim.on('messageReactionsChanged', (zim: ZIM, data: ZIMEventOfMessageReactionsChangedResult) => {
});

2. Add an emoticon response & Repeated reaction counting

You can call the addMessageReaction operation to add an emoticon response to any message sent in a private chat or a group chat. You can obtain the addition result by invoking the ZIMMessageReactionAddedResult callback. In general, this Result can return information about a maximum of five users. For more user information details, see the "Query details of emoticon responses" section of the Respond to messages with emoticons topic.

Warning

If you repeatedly call this operation to add emoticon responses to the same message, an error may occur.
In version 2.28.0 and later, you can implement repeated reaction counting by configuring the config parameter to add the same type of reaction to the same message.
By default, a maximum of 100 types of emoticon responses can be given to a message. To expand the upper limit, contact ZEGOCLOUD Technical Support.

typescript

const reactionType = "key";
const messageObj: ZIMMessage = {};


// Add a message reaction
zim.addMessageReaction(reactionType, messageObj)
    .then((res: ZIMMessageReactionAddedResult) => {
        // The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) => {
        // The operation fails.
    });


// 2.28.0 and later support: repeated reaction counting
const config: ZIMMessageReactionAddConfig = {
    // The increment value of the reaction count, which must be a positive integer.
    // When frequent reactions occur, developers can aggregate the increment value and call this interface only once: for example, if 10 reactions occur within a short period of time, set the value to 10 and call it only once (to avoid affecting server performance due to frequent calls).
    increaseCount: 1
};
zim.addMessageReaction(reactionType, messageObj, config)
    .then((res: ZIMMessageReactionAddedResult) => {
        // The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) => {
        // The operation fails.
    });

const reactionType = "key";
const messageObj: ZIMMessage = {};


// Add a message reaction
zim.addMessageReaction(reactionType, messageObj)
    .then((res: ZIMMessageReactionAddedResult) => {
        // The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) => {
        // The operation fails.
    });


// 2.28.0 and later support: repeated reaction counting
const config: ZIMMessageReactionAddConfig = {
    // The increment value of the reaction count, which must be a positive integer.
    // When frequent reactions occur, developers can aggregate the increment value and call this interface only once: for example, if 10 reactions occur within a short period of time, set the value to 10 and call it only once (to avoid affecting server performance due to frequent calls).
    increaseCount: 1
};
zim.addMessageReaction(reactionType, messageObj, config)
    .then((res: ZIMMessageReactionAddedResult) => {
        // The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) => {
        // The operation fails.
    });

3. Remove an emoticon response

After you add an emoticon response to a message, you can call the deleteMessageReaction operation to remove the emoticon response. You can obtain the removal result by invoking the ZIMMessageReactionDeletedResult callback. In general, this Callback can return information about a maximum of five users. For more user information details, see the "Query details of emoticon responses" section of the Respond to messages with emoticons topic.

In version 2.28.0 and later, you can call the deleteMessageAllReactions operation to delete all emoticon responses of a message.

Warning

You can only delete the emoticon responses that you have added. If the emoticon response is repeated, calling this interface will reset the number of repeated emoticon responses to zero and will not affect the number of repeated emoticon responses of other users.

Sample code

const reactionType = "key";
const messageObj: ZIMMessage = {};

zim.deleteMessageReaction(reactionType, messageObj)
    .then((res: ZIMMessageReactionDeletedResult) => {
        //The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) =>  {
        //The operation fails.
    });

// 2.28.0 and later support: delete all emoticon responses
zim.deleteMessageAllReactions(messageObj)
    .then(() => {
        // The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) => {
        // The operation fails.
    });

const reactionType = "key";
const messageObj: ZIMMessage = {};

zim.deleteMessageReaction(reactionType, messageObj)
    .then((res: ZIMMessageReactionDeletedResult) => {
        //The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) =>  {
        //The operation fails.
    });

// 2.28.0 and later support: delete all emoticon responses
zim.deleteMessageAllReactions(messageObj)
    .then(() => {
        // The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) => {
        // The operation fails.
    });

What's more

Query details of emoticon responses & Query all emoticon responses count by user

Reaction operations (listening, adding, and removing reactions) only return brief user information by default, which is five. To expand the upper limit, contact ZEGO technical support. Therefore, when you need to query which users have made a specific type of reaction to a specific message, you can call the queryMessageReactionUserList operation. You can obtain the operation result by invoking the ZIMMessageReactionUserListQueriedResult callback.

If the repeated reaction counting feature is implemented, you can also query the total reaction count of users through this interface, and the list is sorted by the total reaction count of users in descending order.

Sample code

const config: ZIMMessageReactionUserQueryConfig = {
    nextFlag: 0,
    reactionType: "key",
    count: 20,
};
const messageObj: ZIMMessage = {};

zim.queryMessageReactionUserList(messageObj, config)
    .then((res: ZIMMessageReactionUserListQueriedResult) =>  {
        // The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) =>  {
        // The operation fails.

    });

// 2.28.0 and later support: query all reaction counts by user
const config: ZIMMessageReactionUserQueryConfig = {
    reactionType: "", // The reaction type needs to be empty
    // If count exceeds 100, an error will be returned
    count: 20,
    nextFlag: 0,
};
const messageObj: ZIMMessage = {};

zim.queryMessageReactionUserList(messageObj, config)
    .then((res: ZIMMessageReactionUserListQueriedResult) => {
        // The operation is successful.
        // Traverse res.userInfoList,从中获取 userID and reactions (reaction type and count)
    })
    .catch((err: ZIMError) => {
        // The operation fails.
    });

const config: ZIMMessageReactionUserQueryConfig = {
    nextFlag: 0,
    reactionType: "key",
    count: 20,
};
const messageObj: ZIMMessage = {};

zim.queryMessageReactionUserList(messageObj, config)
    .then((res: ZIMMessageReactionUserListQueriedResult) =>  {
        // The operation is successful, and the status list of the message is updated on the UI.
    })
    .catch((err: ZIMError) =>  {
        // The operation fails.

    });

// 2.28.0 and later support: query all reaction counts by user
const config: ZIMMessageReactionUserQueryConfig = {
    reactionType: "", // The reaction type needs to be empty
    // If count exceeds 100, an error will be returned
    count: 20,
    nextFlag: 0,
};
const messageObj: ZIMMessage = {};

zim.queryMessageReactionUserList(messageObj, config)
    .then((res: ZIMMessageReactionUserListQueriedResult) => {
        // The operation is successful.
        // Traverse res.userInfoList,从中获取 userID and reactions (reaction type and count)
    })
    .catch((err: ZIMError) => {
        // The operation fails.
    });