MessageReactions

The MessageReactions interface provides methods to send, delete, and subscribe to reactions on specific messages. Unlike room reactions, message reactions are persisted and associated with individual chat messages. Access it via room.messages.reactions.

const reactions = room.messages.reactions;

Message reactions support three counting strategies:

• Unique: One reaction per client per message (like iMessage, WhatsApp)
• Distinct: One reaction of each type per client (like Slack)
• Multiple: Unlimited reactions including repeats (like Medium claps)

Send a reaction to a message

Sends a reaction to a specific chat message. The reaction is persisted and contributes to the message's reaction summary.

This method uses the Ably Chat REST API and does not require the room to be attached.

await room.messages.reactions.send('message-serial-123', {
  name: '👍'
});

Parameters

The send() method takes the following parameters:

Returns

Promise<void>

Returns a promise. The promise is fulfilled when the reaction has been sent, or rejected with an ErrorInfo object.

Delete a reaction from a message

Removes a previously sent reaction from a chat message.

This method uses the Ably Chat REST API and does not require the room to be attached.

await room.messages.reactions.delete('message-serial-123', {
  name: '👍'
});

Parameters

The delete() method takes the following parameters:

Returns

Promise<void>

Returns a promise. The promise is fulfilled when the reaction has been deleted, or rejected with an ErrorInfo object.

Subscribe to reaction summaries

Subscribes to aggregated reaction count summaries for messages. Receives updates when the total reaction counts change on any message in the room.

The room must be attached to receive reaction summary events.

const { unsubscribe } = room.messages.reactions.subscribe((event) => {
  console.log('Message:', event.messageSerial);
  console.log('Reactions:', event.reactions);
});

// To stop receiving reaction summaries
unsubscribe();

Parameters

The subscribe() method takes the following parameters:

Returns

Subscription

Returns an object with the following methods:

Unsubscribe from reaction summaries

Call unsubscribe() to stop receiving reaction summary events.

Subscribe to individual reaction events

Subscribes to individual reaction events, receiving notifications each time a user adds or removes a reaction. This provides more granular updates than the summary subscription.

The room must be attached to receive raw reaction events. Raw message reactions must also be enabled when creating the room by setting rawMessageReactions: true in the MessagesOptions.

const { unsubscribe } = room.messages.reactions.subscribeRaw((event) => {
  if (event.type === 'reaction.create') {
    console.log(`${event.reaction.clientId} reacted with ${event.reaction.name}`);
  } else if (event.type === 'reaction.delete') {
    console.log(`${event.reaction.clientId} removed ${event.reaction.name}`);
  }
});

// To stop receiving raw events
unsubscribe();

Parameters

The subscribeRaw() method takes the following parameters:

Returns

Subscription

Returns an object with the following methods:

Unsubscribe from raw reaction events

Call unsubscribe() to stop receiving raw reaction events.

Get reactions for a specific client

Retrieves the reaction data for a specific client on a message. If no client ID is provided, returns reactions for the current user.

// Get current user's reactions on a message
const myReactions = await room.messages.reactions.clientReactions('message-serial-123');

// Get another user's reactions
const theirReactions = await room.messages.reactions.clientReactions('message-serial-123', 'user-456');

Parameters

The clientReactions() method takes the following parameters:

Returns

Promise<MessageReactionSummary>

Returns a promise. The promise is fulfilled with the reaction data for the specified client, or rejected with an ErrorInfo object.

Example

import { MessageReactionType, MessageReactionRawEventType } from '@ably/chat';

const room = await chatClient.rooms.get('my-room', {
  messages: { rawMessageReactions: true }
});
await room.attach();

// Subscribe to reaction summaries
const { unsubscribe: unsubscribeSummary } = room.messages.reactions.subscribe((event) => {
  const { messageSerial, reactions } = event;

  // Update UI with reaction counts
  for (const [name, summary] of Object.entries(reactions.distinct)) {
    console.log(`${name}: ${summary.total} reactions from ${summary.clientIds.length} clients`);
  }
});

// Subscribe to individual reaction events for animations
const { unsubscribe: unsubscribeRaw } = room.messages.reactions.subscribeRaw((event) => {
  if (event.type === MessageReactionRawEventType.Create) {
    // Show reaction animation
    showReactionAnimation(event.reaction.name, event.reaction.clientId);
  }
});

// Send a distinct reaction (Slack-style)
await room.messages.reactions.send('message-serial-123', {
  name: '👍',
  type: MessageReactionType.Distinct
});

// Send multiple reactions (Medium-style claps)
await room.messages.reactions.send('message-serial-456', {
  name: '👏',
  type: MessageReactionType.Multiple,
  count: 5
});

// Remove a reaction
await room.messages.reactions.delete('message-serial-123', {
  name: '👍'
});

// Check what reactions I've sent on a message
const myReactions = await room.messages.reactions.clientReactions('message-serial-123');
console.log('My reactions:', myReactions);

// Clean up
unsubscribeSummary();
unsubscribeRaw();