Reactions

Stream Chat supports message reactions such as likes, hearts, and custom reaction types. Users can react to messages, and reactions can include custom data and scores for cumulative reactions.

Sending a Reaction

Add a reaction to a message using the sendReaction method. Each user can have one reaction of each type per message.

// Send a reaction with default score of 1
await message.SendReactionAsync("like");

// Send a reaction with custom score
await message.SendReactionAsync("clap", 10);

// Replace all previous reactions from this user
await message.SendReactionAsync("love", enforceUnique: true);

Reaction Parameters

NameTypeDescriptionDefaultOptional
message_idstringID of the message to react to
typestringReaction type. Each user can have one reaction of each type per message.
scoreintegerScore for cumulative reactions1
user_idstringUser ID (required for server-side calls)
enforce_uniquebooleanIf true, replaces all existing reactions from this user with the new onefalse
skip_pushbooleanIf true, do not send a push notificationfalse
emoji_codestringUnicode emoji for push notification display
custom dataobjectCustom fields for the reaction

Custom data for reactions is limited to 1KB.

Removing a Reaction

Remove a reaction by specifying the message ID and reaction type.

await message.DeleteReactionAsync("like");

Retrieving Reactions

Reactions are included in the message object. Messages returned by the API include the 10 most recent reactions.

Reaction Fields in Messages

FieldTypeDescription
reaction_countsobjectCount of reactions per type. Example: {"love": 3, "fire": 2}
reaction_scoresobjectSum of scores per type. Equals counts for standard reactions; differs for cumulative reactions.
reaction_groupsobjectDetailed statistics per type including count, sum_scores, first_reaction_at, last_reaction_at
latest_reactionsarrayThe 10 most recent reactions with type, user_id, and created_at
own_reactionsarrayThe current user’s reactions on this message

Use reaction_groups instead of reaction_counts for if you’re building a custom implementation. The reaction_groups field provides additional metadata including timestamps and is the recommended approach.

To retrieve more than 10 reactions, use pagination.

Paginating Reactions

Retrieve reactions with pagination using limit and offset parameters.

ParameterMaximum Value
limit300
offset1000
// Get the first 10 reactions
const response = await channel.getReactions(messageID, { limit: 10 });

// Get reactions 11-13
const response = await channel.getReactions(messageID, {
  limit: 3,
  offset: 10,
});

Querying Reactions

Filter reactions by type or user on a specific message. This endpoint requires the user to have read permission on the channel when called client-side.

// Query reactions by type
await client.queryReactions(message.id, { type: "like" });

// Query reactions by user
await client.queryReactions(message.id, { user_id: userId });

// Paginate results
const firstPage = await client.queryReactions(message.id, {});
const secondPage = await client.queryReactions(
  message.id,
  {},
  {},
  { limit: 5, next: firstPage.next },
);

Cumulative Reactions

Cumulative reactions allow users to react multiple times to the same message, with the total score tracked. This is useful for features like Medium’s “clap” functionality.

Set a score value when sending the reaction. The API returns:

  • sum_scores: Total score across all users
  • Individual user scores
await message.SendReactionAsync("clap", score: 5);