[Docs] Add Targeted Messages Support#2707
[Docs] Add Targeted Messages Support#2707ShanmathiMayuramKrithivasan wants to merge 1 commit intomicrosoft:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Adds documentation and language-specific snippets for “Targeted Messages” (ephemeral, per-user messages) and how to send them both in-response and proactively within the Teams SDK docs.
Changes:
- Adds “Targeted Messages” section to the general Sending Messages template page.
- Adds “Targeted Proactive Messages” section to the Proactive Messaging template page.
- Introduces new LanguageInclude snippets (TS/Python/C#) documenting the targeted-recipient APIs and examples.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| teams.md/src/pages/templates/essentials/sending-messages/proactive-messaging.mdx | Adds a new “Targeted Proactive Messages” docs section and example include. |
| teams.md/src/pages/templates/essentials/sending-messages/README.mdx | Adds a new “Targeted Messages” docs section and example include. |
| teams.md/src/components/include/essentials/sending-messages/typescript.incl.md | Adds TS method name + targeted send example snippet. |
| teams.md/src/components/include/essentials/sending-messages/python.incl.md | Adds Python method name + targeted send example snippet. |
| teams.md/src/components/include/essentials/sending-messages/csharp.incl.md | Adds C# method name + targeted send example snippet. |
| teams.md/src/components/include/essentials/sending-messages/proactive-messaging/typescript.incl.md | Adds TS proactive targeted example snippet. |
| teams.md/src/components/include/essentials/sending-messages/proactive-messaging/python.incl.md | Adds Python proactive targeted example snippet. |
| teams.md/src/components/include/essentials/sending-messages/proactive-messaging/csharp.incl.md | Adds C# proactive targeted example snippet. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // When sending proactively, you must provide the explicit user ID | ||
| public static async Task SendTargetedNotification(string conversationId, string userId) | ||
| { | ||
| var teams = app.UseTeams(); | ||
| await teams.Send( | ||
| conversationId, | ||
| new MessageActivity("This is a private notification just for you!") | ||
| .WithTargetedRecipient(userId) |
There was a problem hiding this comment.
This comment says “explicit user ID”, but the surrounding docs/examples typically use the user’s AAD object ID as the identifier. Consider clarifying the expected identifier (AAD object ID vs another Teams user identifier) for WithTargetedRecipient(...) so readers pass the correct value.
| // When sending proactively, you must provide the explicit user ID | |
| public static async Task SendTargetedNotification(string conversationId, string userId) | |
| { | |
| var teams = app.UseTeams(); | |
| await teams.Send( | |
| conversationId, | |
| new MessageActivity("This is a private notification just for you!") | |
| .WithTargetedRecipient(userId) | |
| // When sending proactively, you must provide the user's AAD object ID as the targeted recipient ID | |
| public static async Task SendTargetedNotification(string conversationId, string userAadObjectId) | |
| { | |
| var teams = app.UseTeams(); | |
| await teams.Send( | |
| conversationId, | |
| new MessageActivity("This is a private notification just for you!") | |
| .WithTargetedRecipient(userAadObjectId) |
| :::info[Preview] | ||
| Targeted messages are currently in preview. | ||
| ::: |
There was a problem hiding this comment.
The admonition title syntax here (":::info[Preview]") doesn’t match the rest of the docs, which use the space-delimited title form (e.g. ":::info Azure Setup Required" in essentials/app-authentication.mdx). Consider changing to the consistent form (":::info Preview") to avoid rendering/build issues.
| Targeted messages are currently in preview. | ||
| ::: | ||
|
|
||
| Targeted messages, also known as ephemeral messages, are delivered to a specific user in a shared conversation. From a single user's perspective, it appears as regular inline messages in a conversation. Other participants won't see these messages. |
There was a problem hiding this comment.
Grammar: “Targeted messages … are delivered … From a single user's perspective, it appears …” mixes plural and singular. Consider changing “it appears” to “they appear” to match “Targeted messages … are delivered”.
| Targeted messages, also known as ephemeral messages, are delivered to a specific user in a shared conversation. From a single user's perspective, it appears as regular inline messages in a conversation. Other participants won't see these messages. | |
| 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. |
|
|
||
| Targeted messages, also known as ephemeral messages, are delivered to a specific user in a shared conversation. From a single user's perspective, it appears as regular inline messages in a conversation. Other participants won't see these messages. | ||
|
|
||
| When sending targeted messages proactively, you must explicitly specify the recipient's user ID. |
There was a problem hiding this comment.
This text says to specify the recipient’s “user ID”, but earlier examples key users by AAD object ID (e.g., activity.from.aadObjectId). Consider clarifying which identifier is required for targeted recipients (AAD object ID vs another Teams user identifier) to prevent misuse.
| When sending targeted messages proactively, you must explicitly specify the recipient's user ID. | |
| When sending targeted messages proactively, you must explicitly specify the recipient's Azure AD (AAD) object ID (for example, the value from `activity.from.aadObjectId`). |
| :::info[Preview] | ||
| Targeted messages are currently in preview. | ||
| ::: |
There was a problem hiding this comment.
The admonition title syntax here (":::info[Preview]") is inconsistent with the rest of the docs, which use the space-delimited title form (e.g. ":::info Azure Setup Required"). Consider switching to ":::info Preview" for consistency and to avoid potential admonition parsing issues.
| Targeted messages are currently in preview. | ||
| ::: | ||
|
|
||
| Targeted messages, also known as ephemeral messages, are delivered to a specific user in a shared conversation. From a single user's perspective, it appears 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. |
There was a problem hiding this comment.
Grammar: “Targeted messages … are delivered … From a single user's perspective, it appears …” mixes plural and singular. Consider changing “it appears” to “they appear” to match the plural subject.
| Targeted messages, also known as ephemeral messages, are delivered to a specific user in a shared conversation. From a single user's perspective, it appears 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. | |
| 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. |
| // When sending proactively, you must provide the explicit user ID | ||
| const sendTargetedNotification = async (conversationId: string, userId: string) => { | ||
| await app.send( |
There was a problem hiding this comment.
This comment says “explicit user ID”, but the rest of the proactive messaging examples use the user’s AAD object ID (activity.from.aadObjectId) as the user identifier. Consider renaming the parameter/comment to explicitly reference the AAD object ID (or whatever identifier the SDK requires) to avoid confusion.
| # When sending proactively, you must provide the explicit user ID | ||
| async def send_targeted_notification(conversation_id: str, user_id: str): | ||
| await app.send( | ||
| conversation_id, | ||
| MessageActivityInput(text="This is a private notification just for you!") | ||
| .with_targeted_recipient(user_id) |
There was a problem hiding this comment.
This comment says “explicit user ID”, but elsewhere the examples use AAD object ID as the user identifier (e.g., ctx.activity.from_.aad_object_id). Consider clarifying which user identifier should be passed to with_targeted_recipient(...) to avoid confusion.
| # When sending proactively, you must provide the explicit user ID | |
| async def send_targeted_notification(conversation_id: str, user_id: str): | |
| await app.send( | |
| conversation_id, | |
| MessageActivityInput(text="This is a private notification just for you!") | |
| .with_targeted_recipient(user_id) | |
| # When sending proactively, you must provide the user's AAD object ID | |
| # (for example, ctx.activity.from_.aad_object_id from an earlier activity) | |
| async def send_targeted_notification(conversation_id: str, aad_object_id: str): | |
| await app.send( | |
| conversation_id, | |
| MessageActivityInput(text="This is a private notification just for you!") | |
| .with_targeted_recipient(aad_object_id) |
PR #2707 documented targeted messages using the old API. This updates it to match the API refactor from teams.net#318, teams.py#275, and teams.ts#449, which consolidated targeted message handling into the existing recipient methods. ## Changes **API Migration:** - **C#**: `WithTargetedRecipient(true|userId)` → `WithRecipient(account, isTargeted: true)` - **Python**: `with_targeted_recipient(True|user_id)` → `with_recipient(account, is_targeted=True)` - **TypeScript**: `withTargetedRecipient(true|userId)` → `withRecipient(account, true)` **Documentation updates:** - Method name references changed from `WithTargetedRecipient`/`with_targeted_recipient`/`withTargetedRecipient` to `WithRecipient`/`with_recipient`/`withRecipient` - All examples now explicitly pass Account objects rather than relying on implicit inference or accepting ID-only strings - Updated descriptive text to clarify explicit recipient passing requirement ## Example **Before:** ```typescript await send( new MessageActivity('Private message') .withTargetedRecipient(true) // Implicitly uses incoming message sender ); ``` **After:** ```typescript await send( new MessageActivity('Private message') .withRecipient(activity.from, true) // Explicit recipient + targeting flag ); ``` Applies to reactive and proactive messaging patterns across all three SDKs. <!-- START COPILOT CODING AGENT TIPS --> --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Shanmathi Mayuram Krithivasan <37715033+ShanmathiMayuramKrithivasan@users.noreply.github.com> Co-authored-by: rido-min <14916339+rido-min@users.noreply.github.com> Co-authored-by: Rido <rido-min@users.noreply.github.com> Co-authored-by: Corina <14900841+corinagum@users.noreply.github.com>
|
superseed by #2711 |
Add Targeted Messages Support in Docs