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.

// Add a reaction
const reaction = await channel.sendReaction(messageID, {
  type: "love",
});

// Add a reaction with custom data
const reaction = await channel.sendReaction(messageID, {
  type: "love",
  customField: "value",
});

// Replace all existing reactions from this user with the new one
const reaction = await channel.sendReaction(
  messageID,
  { type: "love" },
  { enforce_unique: true },
);

val channelClient = client.channel("messaging", "general")

// Add a reaction with custom data
val reaction = Reaction(
  messageId = "message-id",
  type = "like",
  score = 1,
  extraData = mutableMapOf("customField" to "value"),
)
channelClient.sendReaction(reaction).enqueue { result ->
  if (result is Result.Success) {
    val sentReaction: Reaction = result.value
  } else {
    // Handle Result.Failure
  }
}

// Replace all existing reactions from this user with the new one
channelClient.sendReaction(reaction, enforceUnique = true).enqueue { result ->
  // Handle result
}

let channelId = ChannelId(type: .messaging, id: "general")
let messageId = "message-id"
let messageController = chatClient.messageController(cid: channelId, messageId: messageId)

// Add a reaction
messageController.addReaction("like") { error in
  // Handle error
}

// Add a reaction
await channel.sendReaction(message, Reaction(type: 'like'));

// Add a reaction with custom data
await channel.sendReaction(
  message,
  Reaction(type: 'like', extraData: {'customField': 'value'}),
);

// Replace all existing reactions from this user with the new one
await channel.sendReaction(
  message,
  Reaction(type: 'like'),
  enforceUnique: true,
);

// 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);

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.send_reaction(message_id, Models::SendReactionRequest.new(
  reaction: Models::ReactionRequest.new(
    type: 'love',
    user_id: user_id,
    custom: { 'custom_field' => 123 }
  )
))

$response = $client->sendReaction("message-id", new Models\SendReactionRequest(
    reaction: new Models\ReactionRequest(
        type: "love",
        userID: $userId,
        custom: (object)["customField" => 123],
    ),
));

resp, err := client.Chat().SendReaction(ctx, msgID, &getstream.SendReactionRequest{
  Reaction: getstream.ReactionRequest{
    Type:   "love",
    UserID: getstream.PtrTo(userID),
    Custom: map[string]any{"custom_field": 123},
  },
})

var resp = await chat.SendReactionAsync(messageId,
    new SendReactionRequest
    {
        Reaction = new ReactionRequest
        {
            Type = "love",
            UserID = userId
        }
    });

ChannelClient channelClient = client.channel("messaging", "general");

Reaction reaction = new Reaction();
reaction.setMessageId("message-id");
reaction.setType("like");
reaction.setScore(1);
reaction.getExtraData().put("customField", "value");

channelClient.sendReaction(reaction, false).enqueue(result -> {
  if (result.isSuccess()) {
    Reaction sentReaction = result.data();
  } else {
    // Handle result.error()
  }
});

Reaction Parameters

Name	Type	Description	Default	Optional
message_id	string	ID of the message to react to
type	string	Reaction type. Each user can have one reaction of each type per message.
score	integer	Score for cumulative reactions	1	✓
user_id	string	User ID (required for server-side calls)		✓
enforce_unique	boolean	If true, replaces all existing reactions from this user with the new one	false	✓
skip_push	boolean	If true, do not send a push notification	false	✓
emoji_code	string	Unicode emoji for push notification display		✓
custom data	object	Custom 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.

channelClient.deleteReaction(
  messageId = "message-id",
  reactionType = "like",
).enqueue { result ->
  if (result is Result.Success) {
    val message: Message = result.value
  } else {
    // Handle Result.Failure
  }
}

await message.DeleteReactionAsync("like");

// Android SDK
channelClient.deleteReaction("message-id", "like").enqueue(result -> {
  if (result.isSuccess()) {
    Message message = result.data();
  } else {
    // Handle result.error()
  }
});

// Backend SDK
chat.deleteReaction(messageId, "like", DeleteReactionRequest.builder()
    .UserID(userId)
    .build()).execute();

Retrieving Reactions

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

Reaction Fields in Messages

Field	Type	Description
reaction_counts	object	Count of reactions per type. Example: `{"love": 3, "fire": 2}`
reaction_scores	object	Sum of scores per type. Equals counts for standard reactions; differs for cumulative reactions.
reaction_groups	object	Detailed statistics per type including count, sum_scores, first_reaction_at, last_reaction_at
latest_reactions	array	The 10 most recent reactions with type, user_id, and created_at
own_reactions	array	The current user's reactions on this message

{
  "reaction_counts": {
    "love": 3,
    "fire": 2,
    "thumbsup": 1
  },
  "reaction_scores": {
    "love": 3,
    "fire": 2,
    "thumbsup": 1
  },
  "reaction_groups": {
    "love": {
      "count": 3,
      "sum_scores": 3,
      "first_reaction_at": "2024-12-11T14:32:00.000Z",
      "last_reaction_at": "2024-12-11T15:18:00.000Z"
    },
    "fire": {
      "count": 2,
      "sum_scores": 2,
      "first_reaction_at": "2024-12-11T14:35:00.000Z",
      "last_reaction_at": "2024-12-11T14:52:00.000Z"
    },
    "thumbsup": {
      "count": 1,
      "sum_scores": 1,
      "first_reaction_at": "2024-12-11T16:05:00.000Z",
      "last_reaction_at": "2024-12-11T16:05:00.000Z"
    }
  },
  "latest_reactions": [
    {
      "type": "thumbsup",
      "user_id": "sarah-miller",
      "created_at": "2024-12-11T16:05:00.000Z"
    },
    {
      "type": "love",
      "user_id": "mike-johnson",
      "created_at": "2024-12-11T15:18:00.000Z"
    },
    {
      "type": "fire",
      "user_id": "emma-wilson",
      "created_at": "2024-12-11T14:52:00.000Z"
    }
  ],
  "own_reactions": []
}

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.

Parameter	Maximum Value
limit	300
offset	1000

// 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,
});

// Get the first 10 reactions
channelClient.getReactions(
  messageId = "message-id",
  offset = 0,
  limit = 10,
).enqueue { result ->
  if (result is Result.Success) {
    val reactions: List<Reaction> = result.value
  } else {
    // Handle Result.Failure
  }
}

// Get reactions 11-20
channelClient.getReactions(
  messageId = "message-id",
  offset = 10,
  limit = 10,
).enqueue { /* ... */ }

// Get reactions after a specific reaction ID
channelClient.getReactions(
  messageId = "message-id",
  firstReactionId = "reaction-id",
  limit = 10,
).enqueue { /* ... */ }

// Load first 10 reactions
messageController.loadReactions(limit: 10, offset: 0) { result in
  let loadedReactions = messageController.reactions
}

// Load next 10 reactions
messageController.loadNextReactions(limit: 10) { error in
  let loadedReactions = messageController.reactions
}

// Get the first 10 reactions
await channel.getReactions(messageId, pagination: PaginationParams(limit: 10));

// Get reactions 11-13
await channel.getReactions(
  messageId,
  pagination: PaginationParams(limit: 3, offset: 10),
);

// Paginating reactions via API is not yet available in the Unity SDK.
// Please let us know if you'd like this feature implemented: https://github.com/GetStream/stream-chat-unity/issues
// Each message exposes a snapshot of the reaction summary instead:

// The 10 most recent reactions on the message
foreach (var reaction in message.LatestReactions)
{
    Debug.Log($"{reaction.Type} from {reaction.User?.Id}");
}

// The 10 most recent reactions left by the local user
foreach (var reaction in message.OwnReactions)
{
    Debug.Log($"My reaction: {reaction.Type}");
}

// Number of reactions per type, e.g. {"love": 3, "fire": 2}
foreach (var entry in message.ReactionCounts)
{
    Debug.Log($"{entry.Key}: {entry.Value} reactions");
}

// Sum of reaction scores per type (matches counts unless cumulative reactions are used)
foreach (var entry in message.ReactionScores)
{
    Debug.Log($"{entry.Key}: total score {entry.Value}");
}

require 'getstream_ruby'
Models = GetStream::Generated::Models

# Get the first 10 reactions
client.chat.get_reactions(message_id, 10)

# Get reactions 11-13
client.chat.get_reactions(message_id, 3, 10)

// Get the first 10 reactions
var resp = await chat.GetReactionsAsync(messageId, new { limit = 10 });

// Get reactions 11-13
var nextResp = await chat.GetReactionsAsync(messageId, new { limit = 3, offset = 10 });

// Android SDK
int offset = 0;
int limit = 10;

// Get the first 10 reactions
channelClient.getReactions("message-id", offset, limit).enqueue(result -> {
  if (result.isSuccess()) {
    List<Reaction> reactions = result.data();
  } else {
    // Handle result.error()
  }
});

// Get reactions 11-20
channelClient.getReactions("message-id", 10, limit).enqueue(result -> { /* ... */ });

// Backend SDK
chat.getReactions(messageId, GetReactionsRequest.builder()
    .Limit(10).Offset(0).build()).execute();

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 },
);

// Query reactions by type
await client.queryReactions(
  messageId,
  filter: Filter.equal('type', 'like'),
);

// Query reactions by user
await client.queryReactions(
  messageId,
  filter: Filter.equal('user_id', userId),
);

// Paginate results
final firstPage = await client.queryReactions(messageId);
final secondPage = await client.queryReactions(
  messageId,
  pagination: PaginationParams(limit: 5, next: firstPage.next),
);

// This feature is not yet available in the Unity SDK.
// Please let us know if you'd like this feature implemented: https://github.com/GetStream/stream-chat-unity/issues

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

// User claps 5 times
await channel.sendReaction(messageID, {
  type: "clap",
  score: 5,
});

// Same user claps 20 more times (total becomes 25)
await channel.sendReaction(messageID, {
  type: "clap",
  score: 25,
});

await message.SendReactionAsync("clap", score: 5);

from getstream.models import ReactionRequest

# User claps 5 times
client.chat.send_reaction(
    id=message_id,
    reaction=ReactionRequest(type="clap", score=5, user_id=user_id),
)

# Same user claps 20 more times
client.chat.send_reaction(
    id=message_id,
    reaction=ReactionRequest(type="clap", score=25, user_id=user_id),
)

require 'getstream_ruby'
Models = GetStream::Generated::Models

# User claps 5 times
client.chat.send_reaction(message_id, Models::SendReactionRequest.new(
  reaction: Models::ReactionRequest.new(
    type: 'clap',
    score: 5,
    user_id: user_id
  )
))

# Same user claps 20 more times
client.chat.send_reaction(message_id, Models::SendReactionRequest.new(
  reaction: Models::ReactionRequest.new(
    type: 'clap',
    score: 25,
    user_id: user_id
  )
))

// User claps 5 times
$client->sendReaction("message-id", new Models\SendReactionRequest(
    reaction: new Models\ReactionRequest(type: "clap", score: 5, userID: $userId),
));

// Same user claps 20 more times
$client->sendReaction("message-id", new Models\SendReactionRequest(
    reaction: new Models\ReactionRequest(type: "clap", score: 25, userID: $userId),
));

_, err = client.Chat().SendReaction(ctx, msgID, &getstream.SendReactionRequest{
  Reaction: getstream.ReactionRequest{
    Type:   "clap",
    Score:  getstream.PtrTo(25),
    UserID: getstream.PtrTo(userID),
  },
})

var resp = await chat.SendReactionAsync(messageId,
    new SendReactionRequest
    {
        Reaction = new ReactionRequest
        {
            Type = "clap",
            UserID = userId,
            Score = 5
        }
    });

// Android SDK
Reaction reaction = new Reaction();
reaction.setMessageId("message-id");
reaction.setType("clap");
reaction.setScore(5);

channelClient.sendReaction(reaction, false).enqueue(result -> { /* ... */ });

// Backend SDK
chat.sendReaction(messageId, SendReactionRequest.builder()
    .reaction(ReactionRequest.builder()
        .type("clap")
        .score(5)
        .userID(userId)
        .build())
    .build()).execute();

Threads & Replies

Pinned Messages