Reactions

Your bot can react to any server message it can see, remove its own reaction, and hear when reactions change anywhere it is watching. Reactions are keyed by an opaque reactionId: a unicode emoji for the common case, or a custom emoji id for server-specific emoji. This page covers both sides, adding reactions and listening for them.

Reactions do not work on direct messages. react() and unreact() reject with a plain Error on any message where msg.isDM is true, regardless of permissions, before a frame is built. Direct messages arrive on the same messageCreate event as server messages, so guard every handler.

Add a reaction

Call msg.react(reactionId) on a Message to add the bot’s reaction. It returns Promise<void> and requires the reaction_add permission. For a plain emoji, pass the unicode character directly.

client.on('messageCreate', (msg) => {
  if (msg.authorId === client.user?.id) return; // ignore our own messages
  if (msg.isDM || !msg.serverId) return; // reactions are server-only
  if (msg.content.trim() !== '!celebrate') return;
  if (!client.can('reaction_add', msg.serverId)) return; // advisory pre-gate
  msg.react('🎉').catch((e) => console.error('react failed', e));
});

The if (msg.isDM || !msg.serverId) return; guard does two jobs. It keeps react() away from DM messages, and it narrows msg.serverId from string | null to string so can() accepts it. Without it, TypeScript rejects the can() call and plain JavaScript silently returns false for a null server. The reactionId is opaque. The SDK does not validate it and passes it straight through to the server. An invalid id is refused by the server, not caught locally.

Remove the bot’s reaction

Call msg.unreact(reactionId) to remove the bot’s own reaction from a message. It only affects the reaction the bot added, not anyone else’s.

await msg.react('👀');
// later, once the bot is done looking
await msg.unreact('👀');

React with a custom emoji

For a server’s custom emoji, pass its id instead of a unicode character. Get ids from client.fetchEmojis(), which returns Promise<{ emojis, category }>, the global emoji catalog. Its ids are exactly the custom-emoji ids that react() accepts.

const { emojis, category } = await client.fetchEmojis();
// The shape of emojis and category is server-defined. Treat the catalog
// as data you look an id up in, then hand that id to react().
const partyId = findEmojiId(emojis, 'party_blob');
await msg.react(partyId);

The shape of emojis and category is defined by the server, so treat them as data to look ids up in rather than a fixed structure.

Listen for reaction changes

The reactionUpdate event fires when a reaction is added or removed on a message your bot can see. It is not scoped to a channel you selected: on a current Cloak server it arrives for every server the bot is in, the same way messageCreate does. Filter on channelId if you care about one place.

client.on('reactionUpdate', ({ messageId, reactionId, count, userId, serverId, channelId }) => {
  if (channelId !== watchedChannelId) return;
  console.log(`${reactionId} on ${messageId} is now at ${count}`);
});

string

The message whose reactions changed.

string

The reaction that changed, the same opaque id you pass to react().

number

The new total for that reaction on the message. The event does not say whether the change was an add or a remove, only the new count.

string

The user who added or removed the reaction.

string

The server the message belongs to.

string

The channel the message belongs to.

Because count is the new total and no add-or-remove flag is included, treat the event as “this reaction now has this many”, not “someone just added one”.

Filter out the bot’s own reactions

reactionUpdate fires for the bot’s own reactions too, including the ones it adds with react(). When that matters, filter on userId.

client.on('reactionUpdate', (evt) => {
  if (evt.userId === client.user?.id) return; // skip our own reactions
  console.log(`someone reacted with ${evt.reactionId}`);
});

On an older Cloak server, serverId and channelId on reactionUpdate can fall back to the bot’s currently selected server and channel. An up-to-date Cloak server always reports the message’s own location.

React to being mentioned

A reaction acknowledges something without adding a message to the channel, which makes it a good pairing with msg.mentionsMe.

client.on('messageCreate', (msg) => {
  if (msg.isDM || !msg.serverId) return;
  if (!msg.mentionsMe) return;
  if (!client.can('reaction_add', msg.serverId)) return;
  msg.react('👍').catch((e) => console.error('react failed', e));
});

See Mentions and replies for what mentionsMe does and does not cover.

Handling errors

Three different failures are worth telling apart.

Plain Error, before the wire

react() and unreact() reject with a plain Error in two cases. On a direct message, unconditionally. And when the message has no createdAt, which the server needs to locate the row. Live messages from messageCreate and messages loaded with fetchMessages both carry createdAt, so in practice only the DM case comes up.

CloakActionError, from the server

Both methods reject with CloakActionError when the server refuses. Read .code for the reason and .permission for the missing permission when the code maps to one.

Code	Meaning
`-1`	Not authenticated
`-2`	Server error while updating the reaction
`-3`	No reaction to remove on that message
`-4`	Reaction limit reached for that message
`-5`	Message or reaction not found
`-6`	Already reacted with that emoji
`-7`	No existing reaction from you to remove
`-8`	Missing `reaction_add`
`-9`	Rate limited (bot reaction throttle)
`-10`	The bot is timed out in this server

A timeout on an older server

Confirming a reaction needs a Cloak server new enough to send the bot a success acknowledgement. Against an older backend the call cannot confirm and times out even though the reaction landed. See What the server must support.

Pre-gate with can('reaction_add', serverId) to skip actions the server would only refuse, and still catch the promise for the cases you cannot predict.

import { CloakActionError } from '@cloak-software/bot-sdk';

try {
  await msg.react('👍');
} catch (err) {
  if (err instanceof CloakActionError) {
    console.error(`the server refused the reaction (${err.code}): ${err.message}`);
    if (err.permission) console.error(`missing ${err.permission}`);
  } else {
    console.error('could not react', err);
  }
}

Editing, deleting, and pinning

The other four message actions, under the same DM rule.

The Message object

Every field and method a received message carries.

Handling errors

Working with CloakActionError and friends.

Permissions

Why reaction_add must be granted first.

Get started

Core concepts

Messaging

Slash commands

Embeds and cards

Voice

Server management

Advanced

Running in production

Examples

API reference

Reference

Add a reaction

Remove the bot’s reaction

React with a custom emoji

Listen for reaction changes

Filter out the bot’s own reactions

React to being mentioned

Handling errors

Next

Editing, deleting, and pinning

The Message object

Handling errors

Permissions

​Add a reaction

​Remove the bot’s reaction

​React with a custom emoji

​Listen for reaction changes

​Filter out the bot’s own reactions

​React to being mentioned

​Handling errors

​Next

Editing, deleting, and pinning

The Message object

Handling errors

Permissions

Add a reaction

Remove the bot’s reaction

React with a custom emoji

Listen for reaction changes

Filter out the bot’s own reactions

React to being mentioned

Handling errors

Next