Send and receive targeted messages in group conversations

With targeted messaging, users and agents can privately interact without distracting other users or exposing information that isn't meant for the group. Consider the following scenarios:

• A user can ask an agent to generate a summary of the discussion without the other participants seeing the request or the response.
• A user can privately ask for information from an agent with the intent of sharing it with the group but wants to confirm the contents of the message first. The agent can respond privately, with a suggested action requesting the user's approval to share its response. When the user approves, the agent resends the message publicly. For more information, see best practices and design guidance.
• A user can direct and monitor background work with agents, referencing the context of the conversation, without distracting the other participants.
• An agent can detect a new user entering a large, long-running conversation and proactively send them a private welcome message and a summary.

Key aspects of targeted messages

Targeted messages:

• Can be used only for one-to-one interactions between an agent and a user in channels, group chats, and meeting chats.
• Support all the capabilities of standard messages like buttons, images, Adaptive Cards, and files, but don't support reactions, replies, or forwarding.
• Generally operate the same way as standard messages, with the same API operations. Users and agents can modify or delete targeted messages after sending them but can't change their visibility. If a scenario calls for a private message to be made public, the sender should delete it and resend it as a standard message; see best practices and design guidance.
• Expire 24 hours after being sent. When a targeted message expires, Teams deletes it from all clients, although it might be retained in secure storage based on organizational policy.
• Aren't visible to untargeted users, even if they're using an older version of the Teams client that doesn't support targeted messages.

User experience

Targeted messages sent or received by a user are presented in the flow of the conversation with an indicator stating Only you can see this message.

Users send targeted messages to an agent in a channel, group chat, or meeting chat by invoking its name as a slash command.

When a user enters a / in an empty compose box, Teams displays an autocomplete menu containing built-in commands for common tasks. If the conversation includes agents that are eligible to receive targeted messages, the menu will also include a targeted-message command for each of them, named after the agent and displaying its icon.

Activating an agent's targeted message command switches the compose box to targeted message mode. After the user composes a message and selects Send, the resulting message will be targeted to the agent and can't be seen by other participants in the conversation.

For more information about slash commands, including how to register extra named slash commands that can be dispatched to your agent, see expose slash commands from agents and apps.

Prompt Preview in targeted messages

Prompt Preview helps preserve conversational context in targeted messaging scenarios by displaying a compact preview of the user's original request above the agent's response. Prompt Preview helps users understand the context of a response without exposing the original prompt to other participants. A single agent response can contain multiple prompt previews.

Prompt Preview can appear in both private and public agent responses:

Quoted replies in targeted messages

Quoted replies reference an earlier message in a thread, helping readers identify what a response relates to and navigate back to the original context. Use a quoted reply when responding to an earlier point in a busy thread or when readers may need to return to the referenced message. Quoted replies support thread navigation, while Prompt Preview preserves the private prompt-response relationship for targeted agent responses and approval-based sharing.

For more information, see quoted replies.

Implement targeted messages

Targeted messages are sent and received using the same operations as standard single-recipient messages in the Teams SDK but have a Boolean property indicating whether they're targeted.

Receive targeted messages

An agent must opt in via its manifest to be able to receive targeted messages. If not opted in, Teams won't give users the option to send a targeted message to the agent.

Agents that opt in to receive targeted messages should always check the visibility of messages they receive and take it into consideration when generating responses and tracking the context of a conversation. For more information, see best practices and design guidance.

To opt in to receive targeted messages, set supportsTargetedMessages property to true in your agent’s bots entry in the app manifest.

{
    "bots": [
        {
            "botId": "{{BOT_ID}}",
            "scopes": ["personal", "team", "groupChat"],
            "supportsTargetedMessages": true
        }
    ]
}

Agents receive messages via standard message events. Targeted messages can be distinguished from public messages as shown in the following snippet:

  app.on('message', async ({ send, activity }) => {
    if(activity.Recipient.isTargeted) {
       // Handle message event
      }
  });

  teams.OnMessage(async (context, cancellationToken) => {
    if (context.Activity.Recipient?.IsTargeted == true){
      // Handle message event
    }
  });

  @app.on_message
  async def handle_message(ctx):
    if getattr(ctx.activity.recipient, "is_targeted", False):
      # Handle message event

Send a targeted message

All agents in Teams are automatically eligible to send targeted messages. To send a targeted message, use withRecipient to specify a single recipient by their ID, and provide a value of true for the isTargeted argument. The recipient must be a member of the chat or channel.

import { MessageActivity } from '@microsoft/teams.api';

app.on('message', async ({ send, activity }) => {
  // Using withRecipient with isTargeted=true explicitly targets the specified recipient
  await send(
    new MessageActivity('This message is only visible to you!')
      .withRecipient(activity.from, true)
  );
});

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

from microsoft_teams.api import MessageActivity, MessageActivityInput
from microsoft_teams.apps import ActivityContext

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
  # Using with_recipient with is_targeted=True explicitly targets the specified recipient
  await ctx.send(
      MessageActivityInput(text="This message is only visible to you!")
          .with_recipient(ctx.activity.from_, is_targeted=True)
  )

Integrate prompt preview in a targeted message

Prompt Preview can appear in both private and public agent responses, but the implementation mechanism is the same in both cases: the agent includes targetedMessageInfo that references the original targeted message. The difference is only who can see the reply after it is sent.

Prompt Preview is automatically supported in reactive scenarios, such as when an agent replies to a user’s targeted message or slash-command request using send() or reply() through the Teams SDK or REST API. In these cases, the SDK typically adds the targetedMessageInfo entity automatically, linking the response to the original user request.

In proactive scenarios, the response is sent outside the original conversation turn. As a result, the agent must explicitly include the targetedMessageInfo entity and provide the targeted message ID before sending the private or public message.

This ensures the response remains associated with the correct original request and enables Prompt Preview to display the appropriate user prompt.

To render prompt preview, include a targetedMessageInfo entity in the reply activity and set its messageId value to the message ID of the original targeted message, which Teams uses to show the user's original request above the agent response, as shown in this example:

if (isTargeted) {
    response.addTargetedMessageInfo(targetedMessageId);
}

if (isTargeted)
{
    response.AddTargetedMessageInfo(targetedMessageId);
}

if is_targeted:
response.add_targeted_message_info(activity.id)

Send replies using REST APIs

If you are sending replies through REST APIs, use the same targetedMessageInfo entity in the activity payload.

POST {cloud}/v3/conversations/{conversationId}/activities?isTargetedActivity=true
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

JSON
{
  "type": "message",
  "from": {
    "id": "28:c9e...",
    "name": "Contoso"
  },
  "conversation": {
    "id": "x:17I0...",
    "name": "Convo1"
  },
  "recipient": {
    "id": "29:1XJ...",
    "name": "Megan Bowen"
  },
  "text": "My agent's reply",
  "entities": [
    {
      "type": "targetedMessageInfo",
      "messageId": "1772129782775"
    }
  ]
}

Use isTargetedActivity=true for the private reply. For a public repost, send the message normally but keep the same targetedMessageInfo entity.

To render prompt preview, include a targetedMessageInfo entity in the reply activity and set its messageId value to the message ID of the original targeted message to show the user's original request above the agent response, as shown in this example:

"entities": [{
  "type": "targetedMessageInfo",
  "messageId": "xxxxxxxxxxxxx"
}]

This example adds a targetedMessageInfo entity type to the activity’s entities array and references the original user message through its messageId. This association enables Prompt Preview and enables the original request to appear above the agent response.

Update or delete a targeted message

Targeted messages can be updated and deleted in the same way as standard messages, with the following limitations:

• The visibility of a targeted message can't be changed.
• Targeted messages expire after 24 hours and are automatically deleted from clients. Attempting to modify or delete an expired message results in an error.

For more information on updating or deleting a targeted message, see Teams SDK.

Approval workflow using suggested actions

User approval is a key safeguard in targeted messaging workflows. Since an agent’s response may contain user-specific information, explicit user consent is required before sharing it in a public conversation.

The agent can respond privately, with a suggested action requesting the user's approval to share its response. When the user approves, the agent resends the message publicly. The approval experience can be implemented through interactive review surfaces such as Adaptive Cards or suggested actions. Here's a recommended user approval workflow:

1. Receive the user’s targeted request.
2. Send the agent’s response privately, including a prompt preview for context.
3. Present approval options using Suggested Actions or an Adaptive Card.
4. Publish the response to the conversation only after the user approves sharing.

Recommended actions can include Approve, Reject, Share, and Update.

Best practices and design guidance

The ability for users and agents to communicate privately with targeted messaging is a fundamental consideration in group conversations. Agents should always consider the visibility of messages they receive and use it to inform response generation, response visibility, and whether the original request should be tracked as part of the conversation's context.

When designing agent interactions for group conversations, choosing between public and targeted messages in different situations requires careful judgment:

• A targeted request to an agent should result in a targeted response unless the user or the situation explicitly calls for a public response.
• Public messages should be used in situations that are purely informational and don't require user-specific context. They should benefit the entire group and shouldn't contain any private information.
• Take care when using Adaptive Cards in targeted messages. Although the message itself is targeted, interactions with a card can still generate public activity that users might not expect.
• Use Prompt Preview whenever an agent responds to a targeted user request. Compared with quoted replies, this helps users understand the relationship between their original prompt and the agent’s response without requiring them to locate the earlier message.

Handle errors

Ensure to handle these errors appropriately in your agent or app.

More details on other messaging error codes can be found here.

Code sample

Related content

• Proactive messages
• Send and receive messages
• Expose slash commands from agents and apps
• Suggested actions