Teams Targeted Messages: Ephemeral Private Messaging for Agents and Bots in Group Chats

Why It Matters

Teams agent and bot developers have long faced a critical challenge: responses to bots in group chats or channels — including authentication prompts, personal notifications, and user-specific information — were visible to all participants. This cluttered conversation threads and degraded the user experience.

Microsoft has now released Targeted Messages, one of the most requested features for the Teams platform, in developer preview. This capability allows agents and bots to send temporary, private messages visible only to specific users within group chats and channels.

What Are Targeted Messages?

Targeted messages are temporary messages sent by an agent or bot to a specific user within a group chat, channel, or meeting chat. Recipients see these messages as normal inline chat messages, but with a label reading "Only you can see this message."

Key Characteristics

Feature	Description
Visibility	Only the targeted user can see the message
Auto-purge	Automatically removed from clients after 24 hours
User actions	Reactions, replies, and forwarding are not supported
Retention	May be retained in secure storage based on organizational policy
Content support	Text, buttons, images, Adaptive Cards, and files
Sender restriction	Only agents or bots can send; users cannot

Supported Operations

Three core operations can be performed on targeted messages:

• Send: Deliver a targeted message to a specific user
• Update: Edit the content of a previously sent targeted message
• Delete: Remove a targeted message within 24 hours of sending

Use Cases

Targeted messages provide an ideal solution for scenarios requiring contextual information or personalized assistance.

AI and Copilot Summaries

When a new participant joins a long-running group chat, the agent can send a targeted message containing a summary of the discussion so far. This prevents disruption of the ongoing conversation while allowing the newcomer to quickly catch up on context.

Support Messages

User-specific support messages, onboarding reminders, personal check-ins, and quick notifications can be delivered as targeted messages without disturbing the group. Instead of making a public announcement, only the relevant person is reached.

Approval Workflows (Human-in-the-Loop)

In approval processes where the agent needs to request confirmation from a specific user or send informational messages, targeted messages are ideal. The user can progress through a workflow without switching context or being redirected elsewhere.

Authentication Prompts

When bots need to request authentication from a user in a group chat, auth prompts can be shown only to the relevant user. This prevents other participants from encountering unnecessary authentication messages and keeps the conversation thread clean.

Personalized Recommendations

In meeting chats or project channels, when the agent needs to send a personalized recommendation, insight, or follow-up to a specific user, targeted messages ensure that irrelevant information is not shared with other participants.

Technical Implementation Guide

Targeted messages can be enabled through the Teams SDK (C#, TypeScript, Python) and REST APIs. Implementation details for each platform are provided below.

Prerequisites

• Enrollment in the Teams developer preview program
• Current version of the Teams SDK (C#, TypeScript, or Python)
• The bot must be installed in the relevant chat or channel
• The target user must be a member of the relevant chat or channel

Sending Messages

Sending a targeted message is similar to sending a regular message. The agent indicates that the message is intended for a specific user, and the platform delivers it only to that user. The agent does not initiate a separate conversation or create a new chat.

C# implementation:

Mark the message as targeted using the WithRecipient method with isTargeted: true parameter. The context.Activity.From property identifies the triggering user as the target.

TypeScript implementation:

Create a message using the MessageActivity class and specify the target with withRecipient(activity.from, true).

Python implementation:

Create a message using the MessageActivityInput class and specify the target user with with_recipient(ctx.activity.from_, is_targeted=True).

REST API implementation:

Include the isTargetedActivity=true query parameter in the POST request. Specify the target user's Teams ID (MRI) in the recipient field of the request body.

Endpoint: POST {cloud}/v3/conversations/{conversationId}/activities?isTargetedActivity=true

Send type, from, conversation, recipient, and text fields in the request body using the standard message activity format.

Updating Messages

The agent can edit a previously sent targeted message when needed. The updated message appears only in the targeted user's view.

For update operations, you must first store the activityId of the original message. Then use the UpdateTargeted (C#), updateTargeted (TypeScript), or update_targeted (Python) methods in the SDK to update the message.

REST API usage: PUT {cloud}/v3/conversations/{conversationId}/activities/{activityId}?isTargetedActivity=true

Deleting Messages

Agents can delete targeted messages sent within 24 hours. Messages are automatically purged from clients after 24 hours regardless; however, early deletion of messages that are no longer needed or have been acted upon provides a cleaner experience.

Use the DeleteTargeted (C#), deleteTargeted (TypeScript), or delete_targeted (Python) methods in the SDK.

REST API usage: DELETE {cloud}/v3/conversations/{conversationId}/activities/{activityId}?isTargetedActivity=true

Error Handling

Error codes that may be encountered when sending targeted messages and recommended actions:

Status Code	Error Code	Description	Developer Action
400	Bad argument	Recipient information missing when creating targeted message	Ensure WithRecipient is called with a valid Account object
400	Bad argument	Recipient information sent during update or delete operation	Do not send recipient information in update and delete operations
403	BotNotInConversationRoster	Bot is not a member of the conversation	Ensure the bot is installed in the conversation before sending targeted messages
404	ActivityNotFoundInConversation	Specified message ID not found; message may have been deleted or auto-removed after 24 hours	Send a new targeted message or wait for user input based on business logic

If sending a targeted message fails, consider a fallback mechanism such as sending a 1:1 chat message to the user.

Using Adaptive Cards

Targeted messages support all Teams message content types, including Adaptive Cards. This enables rich, interactive cards to be shown only to specific users.

Important Considerations

A critical point when using Adaptive Cards in targeted messages: user actions on the card must not inadvertently create a public response. For example, when an "Approve" button on an approval card is clicked, ensure that the response message is also sent as a targeted message. Otherwise, an action on a privately sent card could generate a message visible to everyone.

Best Practices

• Configure card action responses to also be targeted
• After approval actions, update the card to reflect the completed state
• For cards containing file sharing, ensure file access permissions are compatible with the target user

Limitations and Considerations

Keep the following limitations in mind when using targeted messages:

• Developer preview status: This feature is currently in developer preview and has not yet reached general availability for production environments. API behavior and interfaces may change.
• 24-hour auto-purge: Targeted messages are automatically removed from clients after 24 hours. For scenarios requiring persistent information, use standard messages instead.
• Organizational retention policies: Even after messages are removed from clients, they may be retained in secure storage based on organizational compliance and retention policies.
• Backward compatibility: Teams' backward compatibility mechanism ensures that targeted messages are not displayed on older clients that do not support the feature.
• Bot or agent only: Users cannot send targeted messages directly; this functionality is reserved for agents and bots.
• Membership requirement: The target user must be a member of the chat or channel where the message is sent.

Enterprise Impact and Future Outlook

Targeted messages represent a significant building block in strengthening Microsoft's agent ecosystem on the Teams platform. Combined with the Agent 365 control plane and Copilot Studio, they substantially improve the enterprise agent experience.

Integration with the Agent 365 Ecosystem

Microsoft's Agent 365 vision envisions agents autonomously executing tasks in enterprise workflows. Targeted messages are a critical component of this vision: agents can deliver personalized information and instructions to individual users in group settings, request approvals, or provide status updates — all without cluttering the conversation flow.

Usage with Copilot Studio

Agents built with Copilot Studio can leverage targeted messages to create more sophisticated interactions in group chats. An IT support agent can send personalized troubleshooting steps as a targeted message to a user requesting help in a channel, while other channel members do not see these details.

The Future of Group Chat Experience

Targeted messages have the potential to fundamentally change the agent and bot interaction model in Teams. They create a clear message hierarchy in group chats: permanent content meant for everyone is separated from temporary, contextual information meant for specific individuals. This separation significantly improves chat quality and usability, especially in large teams and multi-participant channels.