Skip to main content

How to Handle Message Reactions in the Microsoft 365 Agents SDK in C#

· 7 min read
Jagdish Kumawat
Founder @ Dewiride

A like on your agent's answer is feedback you'd otherwise never hear about. In the Microsoft 365 Agents SDK, adding or removing a reaction reaches your agent as a messageReaction activity, and two route methods let you handle both.

Syntax​

C#
OnMessageReactionsAdded(handler);
OnMessageReactionsRemoved(handler);
  • OnMessageReactionsAdded matches messageReaction activities that add at least one reaction. OnMessageReactionsRemoved matches the ones that remove at least one. Both are methods of AgentApplication; call them in your agent's constructor.
  • handler is the method that runs, with the signature Task Name(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken).
  • In the handler, turnContext.Activity.ReactionsAdded or ReactionsRemoved lists the reactions, each with a Type such as like, and turnContext.Activity.ReplyToId is the id of the message they're on.

The Example​

The agent for this post answers every message and asks for a reaction. It thanks you when you react, and notices when you take the reaction back:

FeedbackAgent.cs
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;

namespace ReactionsDemo;

public class FeedbackAgent : AgentApplication
{
public FeedbackAgent(AgentApplicationOptions options) : base(options)
{
OnActivity(ActivityTypes.Message, AnswerAsync);
OnMessageReactionsAdded(ReactionsAddedAsync);
OnMessageReactionsRemoved(ReactionsRemovedAsync);
}

private async Task AnswerAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
await turnContext.SendActivityAsync("Here's my answer. React to this message to tell me what you think.", cancellationToken: cancellationToken);
}

private async Task ReactionsAddedAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
// ReplyToId is the id of the message the reaction is on.
foreach (MessageReaction reaction in turnContext.Activity.ReactionsAdded)
{
await turnContext.SendActivityAsync($"Thanks for the {reaction.Type} on message {turnContext.Activity.ReplyToId}!", cancellationToken: cancellationToken);
}
}

private async Task ReactionsRemovedAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
foreach (MessageReaction reaction in turnContext.Activity.ReactionsRemoved)
{
await turnContext.SendActivityAsync($"You took back your {reaction.Type} on message {turnContext.Activity.ReplyToId}.", cancellationToken: cancellationToken);
}
}
}

FeedbackAgent.cs in a macOS-style editor window: a constructor that registers OnActivity for messages, OnMessageReactionsAdded and OnMessageReactionsRemoved, an AnswerAsync handler that asks for a reaction, and two handlers that loop over ReactionsAdded and ReactionsRemoved and answer with each reaction's Type and the activity's ReplyToId

It's one class in an ASP.NET Core project with the Agents SDK, hosted with AddAgent<FeedbackAgent>() and listening on port 3978.

Prerequisites​

  • The Microsoft 365 Agents Playground, to send reactions on your own machine. agentsplayground --version should print 0.2.30; if the command isn't found, install it with npm install -g @microsoft/m365agentsplayground.

Step 1: Register the Reaction Routes​

FeedbackAgent.cs (the constructor)
public FeedbackAgent(AgentApplicationOptions options) : base(options)
{
OnActivity(ActivityTypes.Message, AnswerAsync);
OnMessageReactionsAdded(ReactionsAddedAsync);
OnMessageReactionsRemoved(ReactionsRemovedAsync);
}

A messageReaction activity isn't a message, so the message route never takes it: each reaction route gets the reactions of its kind.

Step 2: Read the Reactions​

One activity can carry several reactions, so the handlers loop over the list:

FeedbackAgent.cs (the reactions added)
private async Task ReactionsAddedAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
// ReplyToId is the id of the message the reaction is on.
foreach (MessageReaction reaction in turnContext.Activity.ReactionsAdded)
{
await turnContext.SendActivityAsync($"Thanks for the {reaction.Type} on message {turnContext.Activity.ReplyToId}!", cancellationToken: cancellationToken);
}
}

reaction.Type is the reaction's name, such as like. ReplyToId tells you which of your messages it's on, which is what makes a reaction useful as feedback: store your answers with the ids SendActivityAsync returns, and you can tell which answer was liked. The handler for removed reactions is the same, with ReactionsRemoved.

Step 3: Get a Message to React To​

Run the agent with dotnet run, start the Agents Playground in a second terminal, and send any message, such as How do I reset my password?:

Terminal 2
agentsplayground -e http://localhost:3978/api/messages -c emulator

A reaction needs the id of the message it's on. In the Playground's Log Panel, click the message 201 line of the agent's answer and open its Response tab, which shows the id the channel gave that answer:

The agent's answer (Log Panel, Response tab)
{
"id": "1795245112010"
}

Step 4: Send a Reaction​

Choose Mock an Activity → Custom activity. The dialog opens with an activity already addressed to your agent, ending in "type": "<custom-activity-type>". Replace that line with these three, using your own id:

Custom activity (replace the type line)
"type": "messageReaction",
"reactionsAdded": [{ "type": "like" }],
"replyToId": "1795245112010"

The Custom activity dialog: a JSON editor holding the serviceUrl, the recipient Test Bot, the conversation and from user-id-0, then type messageReaction, reactionsAdded with a like, and replyToId 1795245112010, above the Send activity and Cancel buttons

Select Send activity. Then open Custom activity once more and send the same like as removed, with reactionsRemoved in place of reactionsAdded:

Custom activity (replace the type line)
"type": "messageReaction",
"reactionsRemoved": [{ "type": "like" }],
"replyToId": "1795245112010"

Each route answers its own kind of reaction:

The Playground chat: How do I reset my password? gets Here's my answer. React to this message to tell me what you think.; then Thanks for the like on message 1795245112010!; then You took back your like on message 1795245112010.

The Playground doesn't draw the like on the message itself, because you sent the activity by hand, but the agent's answers show both routes received what they were meant to.

Common Mistakes​

MistakeWhat happensDo this instead
Handling only the first reactionOthers in the same activity are lostLoop over ReactionsAdded or ReactionsRemoved
Expecting the reacted message's text in the activityIt isn't there, only its idStore your messages with their ids when you send them
Expecting OnActivity(ActivityTypes.Message, ...) to see reactionsReactions are messageReaction activities, not messagesRegister the reaction routes
Replying to every reaction in a busy channelThe conversation fills with thank-yousRecord the feedback quietly, or answer only once

Troubleshooting​

SymptomLikely causeFix
No answer to the reactionNo reaction route, or the activity has no reactionsAdded listRegister OnMessageReactionsAdded, and check the JSON you sent
The id in the answer is emptyThe activity has no replyToIdCopy the id from the Response tab of the message's message 201 line

FAQ​

Which reactions does Microsoft Teams send?​

Microsoft's Teams documentation lists like, heart, laugh, surprised, sad and angry. Teams sends a messageReaction activity when someone adds or removes a reaction on a message your agent sent; reactions on other people's messages don't reach it.

Does the reaction tell me what the message said?​

No. Teams documents that the event doesn't contain the original message, only its id in replyToId. If you need the text, keep your messages and their ids when you send them.

Can I react to reactions in other channels?​

The routes work the same in every channel that sends messageReaction activities. Whether a channel sends them is up to the channel.

Conclusion​

Register OnMessageReactionsAdded and OnMessageReactionsRemoved, loop over ReactionsAdded or ReactionsRemoved, and use ReplyToId to know which of your messages the reaction is on. In the Agents Playground, a custom messageReaction activity with the id of the agent's answer tests both without Teams.

Additional Resources​