Skip to main content

Sending Messages

Sending messages is a core part of an agent's functionality. With all activity handlers, a send method is provided which allows your handlers to send a message back to the user to the relevant conversation.

SDK 2.1

In SDK 2.1, the per-turn context.Send, context.Reply, and context.Quote helpers work the same way. The main difference is streaming — see the tabbed examples below.

teams.OnMessage(async (context, cancellationToken) =>
{
    await context.SendAsync($"you said: {context.Activity.Text}", cancellationToken);
});

In the above example, the handler gets a message activity, and uses the send method to send a reply to the user.

var flow = teams.GetOAuthFlow("graph");
flow.OnSignInComplete(async (context, tokenResponse, cancellationToken) =>
{
    await context.SendAsync("You have successfully signed in!", cancellationToken);
});

You are not restricted to only replying to message activities. In the above example, the handler is listening to OnSignInComplete events, which are sent when a user successfully signs in.

tip

This shows an example of sending a text message. Additionally, you are able to send back things like adaptive cards by using the same send method. Look at the adaptive card section for more details.

Streaming​

You may also stream messages to the user which can be useful for long messages, or AI generated messages. The SDK makes this simple for you by providing a stream function which you can use to send messages in chunks.

The 2.1 streams through a TeamsStreamingWriter. Create one from the turn context, push informative updates and response chunks, then finalize:

teams.OnMessage(async (context, cancellationToken) =>
{
    TeamsStreamingWriter writer = TeamsStreamingWriter.CreateFromContext(context);

    await writer.SendInformativeUpdateAsync("Thinking…", cancellationToken);

    await writer.AppendResponseAsync("hello", cancellationToken);
    await writer.AppendResponseAsync(", ", cancellationToken);
    await writer.AppendResponseAsync("world!", cancellationToken);

    // flush the accumulated text as the final message: "hello, world!"
    await writer.FinalizeResponseAsync(cancellationToken: cancellationToken);
});
note

Streaming is currently only supported in 1:1 conversations, not group chats or channels

Animated image showing agent response text incrementally appearing in the chat window.

@Mention​

Sending a message at @mentions a user is as simple including the details of the user using the AddMention method

teams.OnMessage(async (context, cancellationToken) =>
{
    await context.SendAsync(
        new MessageActivityInput()
            .WithText("hi!")
            .AddMention(context.Activity.From),
        cancellationToken);
});

Targeted Messages​

Preview

Targeted messages are available in public preview. General availability is planned for a future release.

Targeted messages, also known as ephemeral messages, are delivered to a specific user in a shared conversation. From a single user's perspective, they appear as regular inline messages in a conversation. Other participants won't see these messages, making them useful for authentication flows, help or error responses, personal reminders, or sharing contextual information without cluttering the group conversation.

To send a targeted message when responding to an incoming activity, use the WithRecipient method with the recipient account and set the targeting flag to true.

teams.OnMessage(async (context, cancellationToken) =>
{
    // Using WithRecipient with isTargeted=true explicitly targets the specified recipient
    await context.SendAsync(
        new MessageActivityInput()
            .WithText("This message is only visible to you!")
            .WithRecipient(context.Activity.From, isTargeted: true),
        cancellationToken
    );
});
.NET

In .NET, targeted message APIs are marked with [Experimental("ExperimentalTeamsTargeted")] and will produce a compiler error until you opt in. Suppress the diagnostic inline with #pragma warning disable ExperimentalTeamsTargeted or project-wide in your .csproj:

<PropertyGroup>
  <NoWarn>$(NoWarn);ExperimentalTeamsTargeted</NoWarn>
</PropertyGroup>

Prompt Preview​

Coming Soon

Prompt Preview is coming soon in June 2026.

Prompt Preview shows a compact, collapsible preview of the targeted message your agent is replying to, helping carry context from a private user-to-agent message into the reply.

Prompt Preview in targeted reply​

In a targeted (private) reply, both the prompt preview and the bot response are visible only to the targeted user.

Prompt Preview in a targeted reply.

Prompt Preview in public reply​

In a public reply, the same prompt preview appears above the bot response and is visible to everyone in the conversation.

Prompt Preview in a public reply.

In reactive scenarios, when replying to an inbound targeted activity through Send() or Reply(), the SDK automatically includes targeted message info.

For proactive scenarios (using app.SendAsync()), attach targeted message info using the targeted message ID you are replying to.

var targetedMessageId = "1772050244572";
var conversationId = "19:groupchat-id@thread.v2";
var userAccount = new Account
{
    Id = "29:1AbCDef...",
    Name = "Adele Vance"
};

var targetedMessage = new MessageActivity("Here is the result!")
    .AddTargetedMessageInfo(targetedMessageId)
    .WithRecipient(userAccount, isTargeted: true);

// Targeted reply (only the user sees it)
await app.Send(conversationId, targetedMessage);

// OR public reply (everyone sees it)
var publicMessage = new MessageActivity("Here is the result!")
    .AddTargetedMessageInfo(targetedMessageId);
await app.Send(conversationId, publicMessage);

Reactions​

Reactions allow your agent to add or remove emoji reactions on messages in a conversation, and to receive reactions added by users. See the Message Reactions guide for full coverage.

Threading​

In Teams channels, messages can be organized into threads. The SDK provides helpers to simplify working with threads.

Reactive Threading (Within a Handler)​

When your agent receives a message in a thread, the conversation context already carries the thread ID. Use Send() to send a message in the same thread without quoting, or Reply() to send with a visual quote of the inbound message.

teams.OnMessage(async (context, cancellationToken) =>
{
    // Send in the same thread, no quote
    await context.SendAsync("Acknowledged", cancellationToken);

    // Send in the same thread with a visual quote of the inbound message
    await context.Reply("Got it!", cancellationToken);
});

For proactive threading (sending to a thread outside of a handler), see Proactive Messaging.

Quoted Replies​

Quoted replies let your agent reference a previous message in the conversation. When a user sends a message that quotes another message, your agent receives structured metadata about the quoted content. Your agent can also send messages that quote previous messages.

Receiving Quoted Replies​

When a user quotes a message and sends it to your agent, the quoted reply metadata is available on the inbound activity. Use the GetQuotedMessages() method to access all quoted reply entities.

teams.OnMessage(async (context, cancellationToken) =>
{
    var quotes = context.Activity.GetQuotedMessages();

    if (quotes.Count > 0)
    {
        var quote = quotes[0].QuotedReply;
        await context.Reply(
            $"You quoted message {quote.MessageId} from {quote.SenderName}: \"{quote.Preview}\"",
            cancellationToken);
    }
});

Each quoted reply entity contains the quoted message's ID, sender information, a preview of the quoted text, and whether the quoted message has been deleted.

Sending a Quoted Reply​

When your agent calls Reply(), the SDK automatically stamps a quoted reply entity referencing the inbound message. The reply will appear as a quoted reply in Teams.

teams.OnMessage(async (context, cancellationToken) =>
{
    // Reply() automatically quotes the inbound message
    await context.Reply("Got it!", cancellationToken);
});

To quote a different message in the same conversation (not the inbound message), use the Quote() method with the message ID you want to quote.

teams.OnMessage(async (context, cancellationToken) =>
{
    // Quote a specific message by its ID
    var parentMessageId = "1772050244572";
    await context.Quote(parentMessageId, "Referencing an earlier message", cancellationToken);
});

Building Quoted Replies for Proactive Send​

For proactive scenarios (using app.Send()) or when quoting multiple messages, use the AddQuote() method on a message activity. Pass the message ID and an optional response text.

var parentMessageId = "1772050244572";
var firstMessageId = "1772050244573";
var secondMessageId = "1772050244574";

// Single quote with response below it
var msg = new MessageActivity()
    .AddQuote(parentMessageId, "Here is my response");
await app.Send(conversationId, msg);

// Multiple quotes with interleaved responses
msg = new MessageActivity()
    .AddQuote(firstMessageId, "response to first")
    .AddQuote(secondMessageId, "response to second");
await app.Send(conversationId, msg);

// Grouped quotes — omit response to group quotes together
msg = new MessageActivity("see below for previous messages")
    .AddQuote(firstMessageId)
    .AddQuote(secondMessageId, "response to both");
await app.Send(conversationId, msg);