diff --git a/teams.md/src/components/include/essentials/sending-messages/csharp.incl.md b/teams.md/src/components/include/essentials/sending-messages/csharp.incl.md index eb23f8de6..76704b7fa 100644 --- a/teams.md/src/components/include/essentials/sending-messages/csharp.incl.md +++ b/teams.md/src/components/include/essentials/sending-messages/csharp.incl.md @@ -103,3 +103,27 @@ import TabItem from '@theme/TabItem'; ``` + + + + + + ```csharp + [Message] + public async Task OnMessage([Context] IContext.Client client) + { + // Send a private reply visible only to the sender + await client.Send("Hey! This is a private message just for you!", isTargeted: true); + } + ``` + + + ```csharp + app.OnMessage(async context => + { + // Send a targeted message visible only to the sender + await context.Send("Hey! This is a private message just for you!", isTargeted: true); + }); + ``` + + diff --git a/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/csharp.incl.md b/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/csharp.incl.md index 61d3d1bc8..c91541756 100644 --- a/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/csharp.incl.md +++ b/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/csharp.incl.md @@ -49,4 +49,26 @@ public static class Notifications await app.Send(conversationId, "Hey! It's been a while. How are you?"); } } +``` + + + +```csharp +public static class Notifications +{ + public static async Task SendProactiveTargeted(string userId) + { + var conversationId = (string?)storage.Get(userId); + + if (conversationId is null) return; + + // Set Recipient to specify who should receive the private message + var targetedMessage = new MessageActivity("This is a private reminder just for you!") + { + Recipient = new ChannelAccount { Id = userId } + }; + + await app.Send(conversationId, targetedMessage, isTargeted: true); + } +} ``` \ No newline at end of file diff --git a/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/python.incl.md b/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/python.incl.md index 9254f5b44..570556b41 100644 --- a/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/python.incl.md +++ b/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/python.incl.md @@ -34,4 +34,21 @@ async def send_proactive_notification(user_id: str): return activity = MessageActivityInput(text="Hey! It's been a while. How are you?") await app.send(conversation_id, activity) +``` + + + +```python +from microsoft_teams.api import MessageActivityInput, Account +# ... + +async def send_targeted_proactive_notification(user_id: str, recipient_id: str): + conversation_id = storage.get(user_id, "") + if not conversation_id: + return + + activity = MessageActivityInput(text="This is a private reminder just for you!") + activity.recipient = Account(id=recipient_id, role="user") + + await app.send(conversation_id, activity, is_targeted=True) ``` \ No newline at end of file diff --git a/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/typescript.incl.md b/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/typescript.incl.md index 2ea4cb056..17fae4251 100644 --- a/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/typescript.incl.md +++ b/teams.md/src/components/include/essentials/sending-messages/proactive-messaging/typescript.incl.md @@ -38,4 +38,24 @@ const sendProactiveNotification = async (userId: string) => { const activity = new MessageActivity('Hey! It\'s been a while. How are you?'); await app.send(conversationId, activity); }; +``` + + + +```typescript +import { MessageActivity, Account } from '@microsoft/teams.api'; +import { App } from '@microsoft/teams.apps'; +// ... + +const sendTargetedProactiveNotification = async (userId: string, recipientId: string) => { + const conversationId = myConversationIdStorage.get(userId); + if (!conversationId) { + return; + } + + const activity = new MessageActivity('This is a private reminder just for you!'); + activity.recipient = { id: recipientId, role: 'user' } as Account; + + await app.send(conversationId, activity, true); +}; ``` \ No newline at end of file diff --git a/teams.md/src/components/include/essentials/sending-messages/python.incl.md b/teams.md/src/components/include/essentials/sending-messages/python.incl.md index 3324d7bf7..a10412ddc 100644 --- a/teams.md/src/components/include/essentials/sending-messages/python.incl.md +++ b/teams.md/src/components/include/essentials/sending-messages/python.incl.md @@ -46,3 +46,12 @@ async def handle_message(ctx: ActivityContext[MessageActivity]): async def handle_message(ctx: ActivityContext[MessageActivity]): await ctx.send(MessageActivityInput(text='hi!').add_mention(account=ctx.activity.from_)) ``` + + + +```python +@app.on_message +async def handle_message(ctx: ActivityContext[MessageActivity]): + # Send a targeted message that only the sender can see + await ctx.send('This message is only visible to you!', is_targeted=True) +``` diff --git a/teams.md/src/components/include/essentials/sending-messages/typescript.incl.md b/teams.md/src/components/include/essentials/sending-messages/typescript.incl.md index 6e3ce9ffe..bb7ef4a1b 100644 --- a/teams.md/src/components/include/essentials/sending-messages/typescript.incl.md +++ b/teams.md/src/components/include/essentials/sending-messages/typescript.incl.md @@ -41,3 +41,12 @@ app.on('message', async ({ send, activity }) => { await send(new MessageActivity('hi!').addMention(activity.from)); }); ``` + + + +```typescript +app.on('message', async ({ send, activity }) => { + // Send a targeted message that only the sender can see + await send('This message is only visible to you!', undefined, true); +}); +``` diff --git a/teams.md/src/pages/templates/essentials/sending-messages/README.mdx b/teams.md/src/pages/templates/essentials/sending-messages/README.mdx index e8755c6e6..cd5921c5d 100644 --- a/teams.md/src/pages/templates/essentials/sending-messages/README.mdx +++ b/teams.md/src/pages/templates/essentials/sending-messages/README.mdx @@ -4,6 +4,8 @@ summary: Guide to sending messages from your Teams SDK agent, including replies, title: Sending Messages --- +import Language from '@site/src/components/Language'; + # 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. @@ -37,3 +39,28 @@ Streaming is currently only supported in 1:1 conversations, not group chats or c Sending a message at `@mentions` a user is as simple including the details of the user using the method + +## Targeted Messages + +:::info Preview Feature +Targeted messages are currently in preview. +::: + +Targeted messages allow you to send messages privately to a specific recipient in a conversation. +To send a targeted message, use the `isTargeted` parameter in your `send` method: + + + + + +## Errors + +The following table lists errors that may be returned when sending messages. + +| Error | Description | +|-------|-------------| +| `InvalidOperationException`
`app not started` | The app has not been started. Call `await app.Start()` before sending messages or using proactive messaging. | +| `ArgumentException`
`activity.Recipient is required for targeted messages` | When using `isTargeted: true`, the `Recipient` property must be set on the activity to specify who should receive the private message. | +| `Exception`
`no plugin that can send activities was found` | No sender plugin is configured. Ensure a sender plugin (like AspNetCorePlugin) is added to the app. | + + diff --git a/teams.md/src/pages/templates/essentials/sending-messages/proactive-messaging.mdx b/teams.md/src/pages/templates/essentials/sending-messages/proactive-messaging.mdx index 9e3cb5f2a..40aebe9ae 100644 --- a/teams.md/src/pages/templates/essentials/sending-messages/proactive-messaging.mdx +++ b/teams.md/src/pages/templates/essentials/sending-messages/proactive-messaging.mdx @@ -5,6 +5,8 @@ title: 'Proactive Messaging' summary: Learn how to send proactive messages to users without waiting for them to initiate the conversation, including storing conversation IDs and sending notifications. --- +import Language from '@site/src/components/Language'; + # Proactive Messaging In [Sending Messages](./), you were shown how to respond to an event when it happens. However, there are times when you want to send a message to the user without them sending a message first. This is called proactive messaging. You can do this by using the `send` method in the `app` instance. This approach is useful for sending notifications or reminders to the user. @@ -20,3 +22,17 @@ Then, when you want to send a proactive message, you can retrieve the using one of the activity handlers. This is a good place to store the conversation id, but you can also do this in other places like when the user installs the app or when they sign in. The important thing is that you have the conversation id stored somewhere so you can use it later. ::: + +## Targeted Proactive Messages + +:::info Preview Feature +Targeted proactive messages are currently in preview. +::: + +You can also send [targeted messages](./#targeted-messages) proactively to deliver private messages to a specific user in a conversation. + +:::info Requirements +- Recipient property must be set on the activity when using targeted messages +::: + +