diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index dfbc41f7917..60c4c08cb7d 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1225,6 +1225,10 @@ "redirect_url": "/microsoftteams/platform/tabs/what-are-tabs" }, { + "source_path": "msteams-platform/bots/how-to/conversations/channel-messages-with-rsc.md", + "redirect_url": "/microsoftteams/platform/bots/how-to/conversations/channel-messages-for-bots-and-agents" + }, + { "source_path": "msteams-platform/bots/how-to/update-and-delete-bot-messages.md", "redirect_url": "/microsoftteams/platform/bots/build-conversational-capability#update-and-delete-messages-sent-from-bot" }, diff --git a/msteams-platform/TOC.yml b/msteams-platform/TOC.yml index 3903eba48a6..75d36aff239 100644 --- a/msteams-platform/TOC.yml +++ b/msteams-platform/TOC.yml @@ -477,8 +477,8 @@ - name: Build conversational capability href: bots/build-conversational-capability.md displayName: chat, Messages sent between your Microsoft Teams bot and one or more user, Teams channel data, RSC, conversation with RSC - - name: Conversation Messages with RSC - href: bots/how-to/conversations/channel-messages-with-rsc.md + - name: Receive all messages for bots and agents + href: bots/how-to/conversations/channel-messages-for-bots-and-agents.md - name: Channel and group chat conversations with a bot href: bots/how-to/conversations/channel-and-group-conversations.md displayName: Teams conversational bots, mention, tag mention, user mention diff --git a/msteams-platform/apps-in-teams-meetings/build-extensible-conversation-for-meeting-chat.md b/msteams-platform/apps-in-teams-meetings/build-extensible-conversation-for-meeting-chat.md index 18d264de528..9d0ea984223 100644 --- a/msteams-platform/apps-in-teams-meetings/build-extensible-conversation-for-meeting-chat.md +++ b/msteams-platform/apps-in-teams-meetings/build-extensible-conversation-for-meeting-chat.md @@ -56,6 +56,6 @@ The following table provides the user types and lists the features that each use * [Apps for Teams meetings and calls](teams-apps-in-meetings.md) * [Design your Microsoft Teams message extension](../messaging-extensions/design/messaging-extension-design.md) * [Design dialogs for your Microsoft Teams app](../task-modules-and-cards/task-modules/design-teams-task-modules.md) -* [Receive all conversation messages with RSC](../bots/how-to/conversations/channel-messages-with-rsc.md) +* [Receive all conversation messages with RSC](../bots/how-to/conversations/channel-messages-for-bots-and-agents.md) * [Conversation basics](../bots/how-to/conversations/conversation-basics.md) * [Adaptive Card](../task-modules-and-cards/cards/cards-reference.md#adaptive-card) diff --git a/msteams-platform/assets/images/bots/Chats_Manage_Apps_Page.png b/msteams-platform/assets/images/bots/Chats_Manage_Apps_Page.png index 76f76cc74d3..89f718f636c 100644 Binary files a/msteams-platform/assets/images/bots/Chats_Manage_Apps_Page.png and b/msteams-platform/assets/images/bots/Chats_Manage_Apps_Page.png differ diff --git a/msteams-platform/bots/how-to/conversations/Media/Chats_Manage_Apps_Page.png b/msteams-platform/bots/how-to/conversations/Media/Chats_Manage_Apps_Page.png new file mode 100644 index 00000000000..9bcfe2add1a Binary files /dev/null and b/msteams-platform/bots/how-to/conversations/Media/Chats_Manage_Apps_Page.png differ diff --git a/msteams-platform/bots/how-to/conversations/Media/uploading-custom-app.png b/msteams-platform/bots/how-to/conversations/Media/uploading-custom-app.png index 4b7454c724f..a6857e442c0 100644 Binary files a/msteams-platform/bots/how-to/conversations/Media/uploading-custom-app.png and b/msteams-platform/bots/how-to/conversations/Media/uploading-custom-app.png differ diff --git a/msteams-platform/bots/how-to/conversations/channel-and-group-conversations.md b/msteams-platform/bots/how-to/conversations/channel-and-group-conversations.md index 17e0a79e869..311c7153b38 100644 --- a/msteams-platform/bots/how-to/conversations/channel-and-group-conversations.md +++ b/msteams-platform/bots/how-to/conversations/channel-and-group-conversations.md @@ -19,7 +19,7 @@ Bots in a group or channel only receive messages when they're mentioned @botname > [!NOTE] > > * RSC for all *chat* messages is available only in [public developer preview](../../../resources/dev-preview/developer-preview-intro.md). -> * Using resource-specific consent (RSC), a bot can receive all channel messages in teams that it's installed in without being @mentioned. For more information, see [receive all channel messages with RSC](channel-messages-with-rsc.md). +> * Using resource-specific consent (RSC), a bot can receive all channel messages in teams that it's installed in without being @mentioned. For more information, see [receive all channel messages with RSC](channel-messages-for-bots-and-agents.md). > * Posting a message or Adaptive Card to a private channel isn't supported. See the following video to learn about channel and group chat conversations with a bot: diff --git a/msteams-platform/bots/how-to/conversations/channel-messages-for-bots-and-agents.md b/msteams-platform/bots/how-to/conversations/channel-messages-for-bots-and-agents.md new file mode 100644 index 00000000000..08e27ec532a --- /dev/null +++ b/msteams-platform/bots/how-to/conversations/channel-messages-for-bots-and-agents.md @@ -0,0 +1,346 @@ +--- +title: Get All Channel and Chat Messages for Bot and Agents +author: surbhigupta12 +description: Enable bots to receive all conversation messages without being @mentioned using RSC permissions. Read on webApplicationInfo or authorization section in manifest. +ms.topic: conceptual +ms.localizationpriority: medium +ms.date: 01/23/2025 +--- + +# Receive all messages for bots and agents + +> [!NOTE] +> +>While RSC permissions are supported for existing bot apps, we recommend [migrating to agents](../teams-conversational-ai/how-conversation-ai-get-started.md#migrate-your-bot-to-use-teams-ai-library). For new apps, build [agents](/microsoft-365-copilot/extensibility/overview-custom-engine-agent?toc=/microsoftteams/platform/toc.json&bc=/microsoftteams/platform/breadcrumb/toc.json) from scratch and use RSC permissions to enhance the experience. + +Receiving all messages, even without @mentions, enhances bots and agents by providing better context, allowing proactive responses, personalized interactions, and faster issue resolution. The Resource-specific Consent (RSC) permissions model of Microsoft Teams Graph APIs improves performance and ensures timely responses. + +Developers can customize bot behavior to fit specific needs by specifying permissions in the app manifest. Conversation owners can consent for a bot to receive all messages in channels and chats without @mentions. Consent can be granted during the app installation or upgrade process. For more information, see [RSC permissions](../../../graph-api/rsc/resource-specific-consent.md). + +**Note**: Bots that receive all conversation messages with RSC are supported in [Government Community Cloud (GCC), GCC High, Department of Defense (DoD)](../../../concepts/cloud-overview.md#teams-app-capabilities), and [Teams operated by 21Vianet](../../../concepts/sovereign-cloud.md) environments. + +## Enable bots to receive all channel or chat messages + +The RSC permissions are extended to bots and agents, and with user consent and app installation, these permissions: + +- Allow a specified graph application to get all messages in channels and chats, respectively. +- Enable a bot defined in the app manifest to receive all conversations messages without being @mentioned in relevant contexts, where the following permissions apply: + + - `ChannelMessage.Read.Group` + - `ChatMessage.Read.Chat` + +To enable bots or agents to receive all messages: + +- [Filter at mention messages](#filter-at-mention-messages) +- [Use Graph REST APIs to access all messages](#use-graph-rest-apis-to-access-all-messages) + +### Filter at mention messages + +You can enable the developer to filter bot messages and process only the messages that @mention the bots or the agent. This can be useful for several reasons: + +- **Ensure contextual relevance**: Messages that are directed to the bot are likely to have higher relevance for the users of the bot or the agent. It helps the app to respond accurately and to engage in meaningful responses. +- **Better bot performance**: Filtering messages can reduce the need for unnecessary processing for the bot or the agent. Processing contextually irrelevant messages can be avoided to improve the bot performance. It can also keep the bot, the agent, or the user from responding to irrelevant messages or triggering unnecessary actions. +- **Enhance user experience**: Users are more likely to engage with the bot if it responds only when it's addressed. The developer can create a seamless and intuitive user experience. +- **Efficient message handling**: Filtering relevant message enables the bot or the agent to handle larger volume of conversations and make it more useful and relatable. + +Here's an example of using RSC permissions to filter @mention messages: + +```csharp +// When ChannelMessage.Read.Group or ChatMessage.Read.Chat RSC is in the app manifest, this method is called even when bot is not @mentioned. +// This code snippet allows the bot to ignore all messages that do not @mention the bot. +protected override async Task OnMessageActivityAsync(ITurnContext turnContext, CancellationToken cancellationToken) +{ + // Ignore the message if bot was not mentioned. + // Remove this if block to process all messages received by the bot. + if (!turnContext.Activity.GetMentions().Any(mention => mention.Mentioned.Id.Equals(turnContext.Activity.Recipient.Id, StringComparison.OrdinalIgnoreCase))) + { + return; + } + // Sends an activity to the sender of the incoming activity. + await turnContext.SendActivityAsync(MessageFactory.Text("Using RSC the bot can receive messages across channels or chats in team without being @mentioned.")); +} +``` + +Developers can create more efficient and user-friendly conversational interfaces in the bots and agents. + +### Use Graph REST APIs to access all messages + +Services that need access to all Teams message data must use the Graph REST APIs to access archived data in channels and chats. The bot or the agent must use the `ChannelMessage.Read.Group` and `ChatMessage.Read.Chat` RSC permissions appropriately to build and enhance engaging experience for users. + +For more information about updating RSC permissions in app description, see [Update app description for bots or agents](#update-app-description-for-bots-or-agents). + +## Use RSC permissions to enhance AI agents in Teams + +You can use RSC permissions in AI agents to request access to specific resources like mail, calendar, or files. Instead of broad permissions, RSC allows permissions specific to the context of a resource at a granular level. You must determine the resources that your AI agent needs access to within Microsoft Teams or Microsoft 365. Use RSC permissions to: + +- Read messages in Teams channels. +- Access user's details or data. +- Access shared documents. + +For example, use RSC permissions for an AI agent to manage channel content. + +| Use case | How RSC permission in the AI agent can help | +| --- | --- | +| **Context**: A team leader needs their team to collaborate on an upcoming project.

**Goal**: To ensure only relevant and approved content is included in the channel conversation. | **Solution**: Use an agent to manage conversation content. The agent can use the following RSC permissions:
• `ChannelMessage.Read.All`
• `ChannelMessage.Delete.All`
• `ChannelMessage.Send`

**Expected outcome**:
• Filter irrelevant content
• Receive timely updates
• Conversation is organized | + +## Update app manifest + +For your bot or agent to receive all conversation messages, specify the relevant RSC permission strings in the `authorization.permissions.resourceSpecific` property of your app manifest. For more information, see [app manifest schema](../../../resources/schema/manifest-schema.md). + +Here's an app manifest example followed by a sample code snippet: + +:::image type="content" source="../../../assets/images/bots/RSC/appmanifest_2.png" alt-text="Screenshot shows the changes to be made in the app manifest."::: + +In this code example: + +- **webApplicationInfo.id**: Your Microsoft Entra app ID. The app ID can be the same as your bot ID. +- **webApplicationInfo.resource**: Any string. The resource field has no operation in RSC. However, it must be added with a value to avoid error response. +- **authorization.permissions.resourceSpecific**: RSC permissions for your app with either or both `ChannelMessage.Read.Group` and `ChatMessage.Read.Chat` specified. For more information, see [resource-specific permissions](../../../graph-api/rsc/resource-specific-consent.md#supported-rsc-permissions). + +
+Select to view a sample code snippet for app manifest version 1.12 or later + +The following code snippet provides an example of how you can declare RSC permissions in the app manifest: + +```json +{ + "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.21/MicrosoftTeams.schema.json", + "manifestVersion": "1.21", + "version": "1.0.0", + "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "packageName": "com.contoso.rscechobot", + "developer": { + "name": "Contoso", + "websiteUrl": "https://www.contoso.com", + "privacyUrl": "https://www.contoso.com/privacy", + "termsOfUseUrl": "https://www.contoso.com/tos" + }, + "icons": { + "color": "color.png", + "outline": "outline.png" + }, + "name": { + "short": "RscEchoBot", + "full": "Echo bot with RSC configured for all conversation messages" + }, + "description": { + "short": "Echo bot with RSC configured for all channel and chat messages", + "full": "Echo bot configured with all channel and chat messages RSC permission in manifest" + }, + "accentColor": "#FFFFFF", + "staticTabs": [ + { + "entityId": "conversations", + "scopes": [ + "personal" + ] + }, + { + "entityId": "about", + "scopes": [ + "personal" + ] + } + ], + "webApplicationInfo": { + "id": "07338883-af76-47b3-86e4-2603c50be638", + "resource": "https://AnyString" + }, + "authorization": { + "permissions": { + "resourceSpecific": [ + { + "type": "Application", + "name": "ChannelMessage.Read.Group" + }, + { + "type": "Application", + "name": "ChatMessage.Read.Chat" + } + ] + } + }, + "bots": [ + { + "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "scopes": [ + "personal", + "team", + "groupchat" + ], + "supportsFiles": false, + "isNotificationOnly": false + } + ], + "permissions": [ + "identity", + "messageTeamMembers" + ], + "validDomains": [] +} +``` + +
+ +## Upload a custom app in a conversation + +After you've updated the app manifest with the required RSC permissions, follow these steps to upload your custom app to Teams. + +# [Channel messages](#tab/channel) + +The following steps guide you to upload and validate a bot that receives all channel messages in a Team without being @mentioned: + +1. Select or create a team. +1. Select ●●● from the left pane. The dropdown menu appears. +1. Select **Manage team** from the dropdown menu. + + :::image type="content" source="Media/managing-team.png" alt-text="Screenshot shows the managing team option in Teams application."::: + +1. Select **Apps**. Multiple apps appear. + +1. Select **Upload a custom app** from the lower right corner. + + :::image type="content" source="Media/uploading-custom-app.png" alt-text="Screenshot shows the Upload a custom app option."::: + +1. Select **Open**. + + :::image type="content" source="Media/select-apppackage.png" alt-text="Screenshot shows the open dialog box to select the app package." lightbox="Media/select-apppackage.png"::: + +1. Select **Add** from the app details pop-up, to add the app to your selected team. + + :::image type="content" source="Media/adding-bot.png" alt-text="Screenshot shows the Add button to add the app to a team." lightbox="Media/adding-bot.png"::: + +1. Select a channel and enter a message in the channel for your app. + + The bot or agent receives the message without being @mentioned. + + :::image type="content" source="Media/bot-receiving-message.png" alt-text="Screenshot shows a bot receiving message in a channel." lightbox="Media/bot-receiving-message.png"::: + +# [Chat messages](#tab/chat) + +The following steps guide you to upload and validate a bot that receives all chat messages in a chat without being @mentioned: + +1. Select or create a group chat. +1. Select the ellipses ●●● from the group chat. The dropdown menu appears. +1. Select **Manage apps** from the dropdown menu. + + :::image type="content" source="../../../assets/images/bots/chats-manage-apps-entry.png" alt-text="Screenshot shows the Manage apps option from the dropdown menu of a Teams chat." lightbox="../../../assets/images/bots/chats-manage-apps-entry.png"::: + +1. Select **Upload a custom app** from the lower right corner of **Manage apps**. + + :::image type="content" source="../../../assets/images/bots/Chats_Manage_Apps_Page.png" alt-text="Screenshot shows the Upload an app option." lightbox="../../../assets/images/bots/Chats_Manage_Apps_Page.png"::: + +1. Select the app package from the **Open** dialog box. +1. Select **Open**. + + :::image type="content" source="../../../assets/images/bots/Chats_Sideload_App_FilePicker.png" alt-text= "Screenshot shows the window where the app package is selected."::: + +1. Select **Add** from the app details pop-up to add the bot to your selected group chat. + + :::image type="content" source="../../../assets/images/bots/Chats_Install_Dialog.png" alt-text="Screenshot shows the addition of the bot to the group chat."::: + +1. Enter a message in the group chat for your bot. + + :::image type="content" source="../../../assets/images/bots/Bot_ReceiveMessage.png" alt-text="Screenshot shows the bot replying to a message."::: + + The bot receives the message without being @mentioned. + + :::image type="content" source="../../../assets/images/bots/Bot_NoMention.png" alt-text="Screenshot shows the bot replying to a message without @mention."::: + +--- + +## Update app description for bots or agents + +To pass the Microsoft Teams Store approval, the app description must include how the bot or the agent app uses the data it reads: + +- The `ChannelMessage.Read.Group` and `ChatMessage.Read.Chat` need not be used by bots to extract large amounts of customer data. +- The ability for bots to receive all messages in chats using `ChatMessage.Read.Chat` is only enabled after a re-installation or new installation into a chat: + + - If you have an app that's using the `ChatMessage.Read.Chat` for Graph scenarios, then test the app following the steps in [upload a custom app in a conversation](#upload-a-custom-app-in-a-conversation) and modify the app before the feature is [generally available](https://www.microsoft.com/microsoft-365/roadmap?filters=&searchterms=receive%2Call%2Cgroup%2Cchat%2Cmessages). + - If you don't want your app to receive all chat messages, use the [code snippet](#filter-at-mention-messages) for filtering the @mention messages only. + - If no action is taken, your bot receives all the messages after the new installation. + +- Note that `ChatMessage.Read.Chat` allows the app to read chat messages, without a signed-in user. For more information, see [RSC permissions](/graph/permissions-reference). +- The app reads only the information that's necessary for its core functions. +- The app uses data relevant to the specific business needs that it addresses to increase productivity and collaboration. + +For more information, see [app descriptions](../../../concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines.md#app-descriptions). + +## Code snippets + +The following code provides an example of the RSC permissions: + +# [C#](#tab/dotnet) + +- [SDK reference](/dotnet/api/microsoft.bot.builder.activityhandler.onmessageactivityasync?view=botbuilder-dotnet-stable&preserve-view=true) +- [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/meetings-token-app/csharp/Bots/TokenBot.cs#L52) + +```csharp + +// Handle when a message is addressed to the bot. +// When rsc is enabled the method will be called even when bot is addressed without being @mentioned. +protected override async Task OnMessageActivityAsync(ITurnContext turnContext, CancellationToken cancellationToken) +{ + // Sends an activity to the sender of the incoming activity. + await turnContext.SendActivityAsync(MessageFactory.Text("Using RSC the bot can receive messages across channels or chats in a team without being @mentioned.")); +} + +``` + +# [Node.js](#tab/nodejs) + +- [SDK reference](/javascript/api/botbuilder/teamsactivityhandler?view=botbuilder-ts-latest#botbuilder-teamsactivityhandler-onmessage&preserve-view=true) +- [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/app-localization/nodejs/server/bot/botActivityHandler.js#L25) + +```javascript + +// Handle when a message is addressed to the bot. +// When rsc is enabled the method will be called even when bot is addressed without being @mentioned. + +this.onMessage(async (context, next) => { + // Sends a message activity to the sender of the incoming activity. + await context.sendActivity(MessageFactory.text("Using RSC the bot can receive messages across channels or chats in team without being @mentioned.")) + await next(); +}); + +``` + +# [Python](#tab/python) + +- [SDK reference](/python/api/botbuilder-core/botbuilder.core.turncontext?view=botbuilder-py-latest&preserve-view=true#botbuilder-core-turncontext-send-activity) +- [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-receive-channel-messages-withRSC/python/bots/botActivityHandler.py#L34) + +```python + + # Event handler for when new members are added to a team + async def on_teams_members_added( + self, + teams_members_added: list[TeamsChannelAccount], # List of new members added + team_info: TeamInfo, # Information about the team + turn_context: TurnContext, # Context for the current turn + ): + # Welcome message for new members + welcome_text = "Hello and welcome! With this sample, your bot can receive user messages across standard channels in a team without being @mentioned." + + for member in teams_members_added: + # Ensure the bot does not send a welcome message to itself + if member.id != turn_context.activity.recipient.id: + await turn_context.send_activity(MessageFactory.text(welcome_text)) + +``` + +--- + +## Code sample + +| Sample name | Description | .NET | Node.js | Python | App manifest | +| --- | --- | --- | --- | --- | +|Channel messages with RSC permissions| This sample app shows how a bot can receive all channel messages with RSC without being @mentioned.|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-receive-channel-messages-withRSC/csharp) |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-receive-channel-messages-withRSC/nodejs) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-receive-channel-messages-withRSC/python) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-receive-channel-messages-withRSC/csharp/demo-manifest/Bot-RSC.zip) | + +## See also + +- [Send and receive messages](../../build-conversational-capability.md) +- [Resource-specific consent for your Teams app](../../../graph-api/rsc/resource-specific-consent.md) +- [Test resource-specific consent permissions in Teams](../../../graph-api/rsc/test-resource-specific-consent.md) +- [Upload your app in Teams](../../../concepts/deploy-and-publish/apps-upload.md) +- [List replies to messages in a channel](/graph/api/chatmessage-list-replies?view=graph-rest-1.0&tabs=http&preserve-view=true) diff --git a/msteams-platform/bots/how-to/conversations/channel-messages-with-rsc.md b/msteams-platform/bots/how-to/conversations/channel-messages-with-rsc.md deleted file mode 100644 index 5a838c333ee..00000000000 --- a/msteams-platform/bots/how-to/conversations/channel-messages-with-rsc.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Get All Conversation Messages with RSC -author: surbhigupta12 -description: Enable bots to receive all conversation messages without being @mentioned using RSC permissions. Read on webApplicationInfo or authorization section in manifest. -ms.topic: conceptual -ms.localizationpriority: medium -ms.owner: angovil -ms.date: 01/23/2025 ---- - -# Receive conversation messages with RSC - -The resource-specific consent (RSC) permissions model, originally developed for Microsoft Teams Graph APIs, is being extended to bot scenarios. With RSC, conversation owners can consent for a bot to receive all user messages in standard channels and chats without being @mentioned. This can be enabled by specifying the `ChannelMessage.Read.Group` or `ChatMessage.Read.Chat` permission strings in your app manifest (previously called Teams app manifest). Conversation owners can grant consent during the app installation or upgrade process after the app updates are published. For more information about enabling RSC for your app and inside of a tenant, see [resource-specific consent](../../../graph-api/rsc/resource-specific-consent.md). - -> [!NOTE] -> Bots that receive all conversation messages with RSC are supported in [Government Community Cloud (GCC), GCC High, Department of Defense (DoD)](../../../concepts/cloud-overview.md#teams-app-capabilities), and [Teams operated by 21Vianet](../../../concepts/sovereign-cloud.md) environments. - -## Enable bots to receive all channel or chat messages - -The `ChannelMessage.Read.Group` and `ChatMessage.Read.Chat` RSC permissions are being extended to bots. With user consent and app installation, these permissions: - -* Allow a specified graph application to get all messages in channels and chats, respectively. -* Enable a bot defined in the app manifest to receive all conversations messages without being @mentioned in relevant contexts where the permissions apply. - -### Filtering at mention messages - -```csharp -// When ChannelMessage.Read.Group or ChatMessage.Read.Chat RSC is in the app manifest, this method is called even when bot is not @mentioned. -// This code snippet allows the bot to ignore all messages that do not @mention the bot. -protected override async Task OnMessageActivityAsync(ITurnContext turnContext, CancellationToken cancellationToken) -{ - // Ignore the message if bot was not mentioned. - // Remove this if block to process all messages received by the bot. - if (!turnContext.Activity.GetMentions().Any(mention => mention.Mentioned.Id.Equals(turnContext.Activity.Recipient.Id, StringComparison.OrdinalIgnoreCase))) - { - return; - } - // Sends an activity to the sender of the incoming activity. - await turnContext.SendActivityAsync(MessageFactory.Text("Using RSC the bot can receive messages across channels or chats in team without being @mentioned.")); -} -``` - -### RSC permission - -Services that need access to all Teams message data must use the Graph APIs that provide access to archived data in channels and chats. Bots must use the `ChannelMessage.Read.Group` and `ChatMessage.Read.Chat` RSC permission appropriately to build and enhance engaging experience for users to pass the Microsoft Teams Store approval. The app description must include how the bot uses the data it reads: - -* The `ChannelMessage.Read.Group` and `ChatMessage.Read.Chat` RSC permission may not be used by bots to extract large amounts of customer data. -* The ability for bots to receive all messages in chats using `ChatMessage.Read.Chat` is only enabled after a re-installation or new installation into a chat. -* If you have an app that's using the `ChatMessage.Read.Chat` RSC permission for Graph scenarios, then test the app following the steps in [upload a custom app in a conversation](channel-messages-with-rsc.md#upload-a-custom-app-in-a-conversation) and modify the app before the feature is [generally available](https://www.microsoft.com/microsoft-365/roadmap?filters=&searchterms=receive%2Call%2Cgroup%2Cchat%2Cmessages). If you don't want your bot to receive all chat messages, implement the following [code snippet](#filtering-at-mention-messages). If no action is taken, your bot receives all messages after new installations. - -## Update app manifest - -For your bot to receive all conversation messages, the relevant RSC permission strings must be specified in the `authorization.permissions.resourceSpecific` property of your app manifest. For more information, see [app manifest schema](../../../resources/schema/manifest-schema.md). - -:::image type="content" source="../../../assets/images/bots/RSC/appmanifest_2.png" alt-text="Screenshot shows the changes to be made in the app manifest."::: - -The following code provides an example of the app manifest: - -* **webApplicationInfo.id**: Your Microsoft Entra app ID. The app ID can be the same as your bot ID. -* **webApplicationInfo.resource**: Any string. The resource field has no operation in RSC, but must be added with a value to avoid error response. -* **authorization.permissions.resourceSpecific**: RSC permissions for your app with either or both `ChannelMessage.Read.Group` and `ChatMessage.Read.Chat` specified. For more information, see [resource-specific permissions](../../../graph-api/rsc/resource-specific-consent.md#supported-rsc-permissions). - -The following code provides an example of the app manifest version 1.12 or later: - -```json -{ - "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.12/MicrosoftTeams.schema.json", - "manifestVersion": "1.12", - "version": "1.0.0", - "id": "8239c8f3-ed78-4512-933e-babfd28856f1", - "packageName": "com.contoso.rscechobot", - "developer": { - "name": "Contoso", - "websiteUrl": "https://www.contoso.com", - "privacyUrl": "https://www.contoso.com/privacy", - "termsOfUseUrl": "https://www.contoso.com/tos" - }, - "icons": { - "color": "color.png", - "outline": "outline.png" - }, - "name": { - "short": "RscEchoBot", - "full": "Echo bot with RSC configured for all conversation messages" - }, - "description": { - "short": "Echo bot with RSC configured for all channel and chat messages", - "full": "Echo bot configured with all channel and chat messages RSC permission in manifest" - }, - "accentColor": "#FFFFFF", - "staticTabs": [ - { - "entityId": "conversations", - "scopes": [ - "personal" - ] - }, - { - "entityId": "about", - "scopes": [ - "personal" - ] - } - ], - "webApplicationInfo": { - "id": "07338883-af76-47b3-86e4-2603c50be638", - "resource": "https://AnyString" - }, - "authorization": { - "permissions": { - "resourceSpecific": [ - { - "type": "Application", - "name": "ChannelMessage.Read.Group" - }, - { - "type": "Application", - "name": "ChatMessage.Read.Chat" - } - ] - } - }, - "bots": [ - { - "botId": "07338883-af76-47b3-86e4-2603c50be638", - "scopes": [ - "personal", - "team", - "groupchat" - ], - "supportsFiles": false, - "isNotificationOnly": false - } - ], - "permissions": [ - "identity", - "messageTeamMembers" - ], - "validDomains": [] -} -``` - -## Upload a custom app in a conversation - -# [Channel messages](#tab/channel) - -The following steps guide you to upload and validate bot that receives all channel messages in a Team without being @mentioned: - -1. Select or create a team. -1. Select ●●● from the left pane. The dropdown menu appears. -1. Select **Manage team** from the dropdown menu. - - :::image type="content" source="Media/managing-team.png" alt-text="Screenshot shows the managing team option in Teams application."::: - -1. Select **Apps**. Multiple apps appear. - -1. Select **Upload a custom app** from the lower right corner. - - :::image type="content" source="Media/uploading-custom-app.png" alt-text="Screenshot shows the upload a custom app option."::: - -1. Select **Open**. - - :::image type="content" source="Media/select-apppackage.png" alt-text="Screenshot shows the open dialog box to select the app package." lightbox="Media/select-apppackage.png"::: - -1. Select **Add** from the app details pop-up, to add the bot to your selected team. - - :::image type="content" source="Media/adding-bot.png" alt-text="Screenshot shows the add button to add a bot to a team." lightbox="Media/adding-bot.png"::: - -1. Select a channel and enter a message in the channel for your bot. - - The bot receives the message without being @mentioned. - - :::image type="content" source="Media/bot-receiving-message.png" alt-text="Screenshot shows a bot receiving message in a channel." lightbox="Media/bot-receiving-message.png"::: - -# [Chat messages](#tab/chat) - -The following steps guide you to upload and validate bot that receives all chat messages in a chat without being @mentioned: - -1. Select or create a group chat. -1. Select the ellipses ●●● from the group chat. The dropdown menu appears. -1. Select **Manage apps** from the dropdown menu. - - :::image type="content" source="../../../assets/images/bots/chats-manage-apps-entry.png" alt-text="Screenshot shows the manage apps option from the dropdown menu of a Teams chat." lightbox="../../../assets/images/bots/chats-manage-apps-entry.png"::: - -1. Select **Upload a custom app** from the lower right corner of **Manage apps**. - - :::image type="content" source="../../../assets/images/bots/Chats_Manage_Apps_Page.png" alt-text="Screenshot shows the upload an app option." lightbox="../../../assets/images/bots/Chats_Manage_Apps_Page.png"::: - -1. Select the app package from the **Open** dialog box. -1. Select **Open**. - - :::image type="content" source="../../../assets/images/bots/Chats_Sideload_App_FilePicker.png" alt-text= "Screenshot shows the window where the app package is selected."::: - -1. Select **Add** from the app details pop-up, to add the bot to your selected group chat. - - :::image type="content" source="../../../assets/images/bots/Chats_Install_Dialog.png" alt-text="Screenshot shows the addition of the bot to the group chat."::: - -1. Enter a message in the group chat for your bot. - - :::image type="content" source="../../../assets/images/bots/Bot_ReceiveMessage.png" alt-text="Screenshot shows the bot replying to a message."::: - - The bot receives the message without being @mentioned. - - :::image type="content" source="../../../assets/images/bots/Bot_NoMention.png" alt-text="Screenshot shows the bot replying to a message without a mention."::: - ---- - -## Code snippets - -The following code provides an example of the RSC permissions: - -# [C#](#tab/dotnet) - -* [SDK reference](/dotnet/api/microsoft.bot.builder.activityhandler.onmessageactivityasync?view=botbuilder-dotnet-stable&preserve-view=true) -* [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/meetings-token-app/csharp/Bots/TokenBot.cs#L52) - -```csharp - -// Handle when a message is addressed to the bot. -// When rsc is enabled the method will be called even when bot is addressed without being @mentioned. -protected override async Task OnMessageActivityAsync(ITurnContext turnContext, CancellationToken cancellationToken) -{ - // Sends an activity to the sender of the incoming activity. - await turnContext.SendActivityAsync(MessageFactory.Text("Using RSC the bot can receive messages across channels or chats in team without being @mentioned.")); -} - -``` - -# [Node.js](#tab/nodejs) - -* [SDK reference](/javascript/api/botbuilder/teamsactivityhandler?view=botbuilder-ts-latest#botbuilder-teamsactivityhandler-onmessage&preserve-view=true) -* [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/app-localization/nodejs/server/bot/botActivityHandler.js#L25) - -```javascript - -// Handle when a message is addressed to the bot. -// When rsc is enabled the method will be called even when bot is addressed without being @mentioned. - -this.onMessage(async (context, next) => { - // Sends a message activity to the sender of the incoming activity. - await context.sendActivity(MessageFactory.text("Using RSC the bot can receive messages across channels or chats in team without being @mentioned.")) - await next(); -}); - -``` - ---- - -## Code sample - -| Sample name | Description | .NET |Node.js| App manifest -|-------------|-------------|------|----|----| -|Channel messages with RSC permissions| This sample app shows how a bot can receive all channel messages with RSC without being @mentioned.|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-receive-channel-messages-withRSC/csharp) |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-receive-channel-messages-withRSC/nodejs) |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-receive-channel-messages-withRSC/csharp/demo-manifest/Bot-RSC.zip) | - -## See also - -* [Send and receive messages](../../build-conversational-capability.md) -* [Resource-specific consent for your Teams app](../../../graph-api/rsc/resource-specific-consent.md) -* [Test resource-specific consent permissions in Teams](../../../graph-api/rsc/test-resource-specific-consent.md) -* [Upload your app in Teams](../../../concepts/deploy-and-publish/apps-upload.md) -* [List replies to messages in a channel](/graph/api/chatmessage-list-replies?view=graph-rest-1.0&tabs=http&preserve-view=true) diff --git a/msteams-platform/bots/how-to/conversations/subscribe-to-conversation-events.md b/msteams-platform/bots/how-to/conversations/subscribe-to-conversation-events.md index 32231a9024c..abdd0753c7c 100644 --- a/msteams-platform/bots/how-to/conversations/subscribe-to-conversation-events.md +++ b/msteams-platform/bots/how-to/conversations/subscribe-to-conversation-events.md @@ -1351,7 +1351,6 @@ The following code shows an example of reactions removed from bot message: * [SDK reference](/dotnet/api/microsoft.bot.builder.activityhandler.onreactionsremovedasync?view=botbuilder-dotnet-stable&preserve-view=true#definition) * [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/bot-message-reaction/csharp/Bots/MessageReactionBot.cs#L44) - ```csharp protected override async Task OnReactionsRemovedAsync(IList messageReactions, ITurnContext turnContext, CancellationToken cancellationToken) { @@ -1653,6 +1652,6 @@ In the development phase, it's always helpful to send meaningful messages in con * [Build bots for Teams](../../what-are-bots.md) * [API reference for the Bot Framework Connector service](/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference) * [Channel and group chat conversations with a bot](channel-and-group-conversations.md) -* [Receive all conversation messages with RSC](channel-messages-with-rsc.md) +* [Receive all channel messages for bot and agents](channel-messages-for-bots-and-agents.md) * [Create Teams conversation bot](../../../sbs-teams-conversation-bot.yml) * [Triggers in Bot Framework Composer](/composer/concept-events-and-triggers) diff --git a/msteams-platform/resources/troubleshoot.md b/msteams-platform/resources/troubleshoot.md index 9e7589b2fd5..61cff31aec1 100644 --- a/msteams-platform/resources/troubleshoot.md +++ b/msteams-platform/resources/troubleshoot.md @@ -139,4 +139,4 @@ If you’re unable to resolve the errors, we recommend contacting [Microsoft Tea * [Build tabs for meeting](../apps-in-teams-meetings/build-tabs-for-meeting.md) * [Build bots for Teams](../bots/what-are-bots.md) * [Enable SSO for tab app](../tabs/how-to/authentication/tab-sso-overview.md) -* [Receive all conversation messages with RSC](../bots/how-to/conversations/channel-messages-with-rsc.md) +* [Receive all channel messages for bots and agents](../bots/how-to/conversations/channel-messages-for-bots-and-agents.md) diff --git a/msteams-platform/whats-new.md b/msteams-platform/whats-new.md index b95f6f290c0..3d8b07ed8b1 100644 --- a/msteams-platform/whats-new.md +++ b/msteams-platform/whats-new.md @@ -197,10 +197,10 @@ Teams platform features that are available to all app developers. | 23/02/2023 | Enable single sign-on (SSO) authentication to access Adaptive Cards Universal Actions in a bot. | Add authentication > Enable SSO for your Teams app > Enable SSO for Adaptive Cards Universal Actions in your bot > [Overview](task-modules-and-cards/cards/Universal-actions-for-adaptive-cards/enable-sso-for-your-adaptive-cards-universal-action.md) | |23/02/2023| Enable third party authentication to add user-specific views in instances where an Adaptive Card with Universal Action is shared. | Add authentication > Use third party IdP authentication > [Third party authentication for Adaptive Cards Universal Actions](task-modules-and-cards/cards/Universal-actions-for-adaptive-cards/authentication-flow-in-universal-action-for-adaptive-cards.md) | |21/02/2023| Send notifications to specific participants on a meeting stage with targeted in-meeting notification. | Build apps for Teams meetings and calls > Enable and configure apps for Teams meeting > [Targeted in-meeting notification for apps in Teams](apps-in-teams-meetings/in-meeting-notification-for-meeting.md#targeted-in-meeting-notification) | -|20/02/2023| Plan, strategize, and execute your app growth in Teams to make it a successful app on the marketplace. | Grow your app > [Strategize and execute growth for your app](concepts/deploy-and-publish/appsource/post-publish/app-growth/overview-app-growth.md)| -|17/02/2023| Build a dashboard tab app that acts as a tool to track, analyze, monitor, display, and extract data. | Build Tabs > [Build a dashboard tab app](tabs/how-to/build-a-dashboard-tab-app.md#build-a-dashboard-tab-app)| +|20/02/2023| Plan, strategize, and execute your app growth in Teams to make it a successful app on the marketplace. | Grow your app > [Strategize and execute growth for your app](concepts/deploy-and-publish/appsource/post-publish/app-growth/overview-app-growth.md) | +|17/02/2023| Build a dashboard tab app that acts as a tool to track, analyze, monitor, display, and extract data. | Build Tabs > [Build a dashboard tab app](tabs/how-to/build-a-dashboard-tab-app.md#build-a-dashboard-tab-app) | |09/02/2023| Build apps for anonymous users that support anonymous users to attend Teams meetings with an alternative authentication experience. | Build apps for Teams meetings and calls > Enable and configure apps for Teams meeting > [Build apps for anonymous users](apps-in-teams-meetings/build-apps-for-anonymous-user.md) | -|31/01/2023| Get update and soft delete activity notification in a bot when you edit, undelete or soft delete a message in a chat. | Build bots > Bot conversations > [Messages in bot conversations](bots/how-to/conversations/conversation-messages.md#get-edit-message-activity) +|31/01/2023| Get update and soft delete activity notification in a bot when you edit, undelete or soft delete a message in a chat. | Build bots > Bot conversations > [Messages in bot conversations](bots/how-to/conversations/conversation-messages.md#get-edit-message-activity) |
@@ -307,7 +307,7 @@ Explore updates from the previous GA releases listed here. |11/24/2021| Introduced step-by-step guide to generate meeting token | Build apps for Teams meetings > Enable and configure apps for meetings > [Step-by-step guide to create meeting token in Teams](sbs-meeting-token-generator.yml)| |11/17/2021| Updated Teams Store validation guidelines|[Teams Store validation guidelines](~/concepts/deploy-and-publish/appsource/prepare/teams-store-validation-guidelines.md)| |11/17/2021| Static and dynamic typeahead search for desktop and mobile users | • Build cards and task modules > Build cards > [Typeahead search in Adaptive Cards](task-modules-and-cards/cards/dynamic-search.md)
• Build cards and task modules > Build cards > Overview > [Typeahead search in Adaptive Cards](task-modules-and-cards/what-are-cards.md#typeahead search-in-adaptive-cards)
• Build cards and task modules > Overview > [Cards and task modules](task-modules-and-cards/cards-and-task-modules.md)| -|11/13/2021| Bots can be enabled to receive all channel messages using resource-specific consent (RSC) | • Build bots > Bot conversations > Messages in bot conversations > [Receive all channel messages with RSC](~/bots/how-to/conversations/channel-messages-with-rsc.md)
• Build bots > Bot conversations > [Bot conversation overview](~/bots/how-to/conversations/conversation-basics.md)
• Build bots > Bot conversations > [Channel and group conversations](~/bots/how-to/conversations/channel-and-group-conversations.md) | +|11/13/2021| Bots can be enabled to receive all channel messages using resource-specific consent (RSC) | • Build bots > Bot conversations > Messages in bot conversations > [Receive all channel messages with RSC](~/bots/how-to/conversations/channel-messages-for-bots-and-agents.md)
• Build bots > Bot conversations > [Bot conversation overview](~/bots/how-to/conversations/conversation-basics.md)
• Build bots > Bot conversations > [Channel and group conversations](~/bots/how-to/conversations/channel-and-group-conversations.md) | |10/28/2021| Monetize your Teams app with a transactable SaaS offer | Publish your app > Publish to the Teams Store > [Include a SaaS offer with your Teams app](~/concepts/deploy-and-publish/appsource/prepare/include-saas-offer.md) | |10/25/2021| Updated Get started module for Microsoft Teams Developer Documentation with new structure and procedures in a step-by-step guide | Get started > [Get started with your first Teams app](get-started/get-started-overview.md) | |10/20/2021| Meeting stage is now available in GA | Build apps for Teams meetings > [Enable and configure your apps for Teams meetings](apps-in-teams-meetings/build-tabs-for-meeting.md) | @@ -552,7 +552,7 @@ Developer preview is a public program that provides early access to unreleased T | **Date** | **Update** | **Find here** | | -------- | --------- | ------------------ | |05/12/2022| Use share in meeting to share any document or third-party app to the meeting stage.|Build apps for Teams meetings and calls > Enable and configure apps for meetings > [Share in meeting](concepts/build-and-test/share-in-meeting.md) | -|10/11/2022| Enable bots to receive all conversation messages without being @mentioned in relevant contexts.|Build bots > Bot conversations > Message in bot conversations > [Receive all conversation messages with RSC](bots/how-to/conversations/channel-messages-with-rsc.md) | +|10/11/2022| Enable bots to receive all conversation messages without being @mentioned in relevant contexts.|Build bots > Bot conversations > Message in bot conversations > [Receive all conversation messages with RSC](bots/how-to/conversations/channel-messages-for-bots-and-agents.md) | | 09/23/2022 | Use apps in Teams meetings scheduled through public channels. | Build apps for Teams meetings and calls > [Apps for Teams meetings and calls](apps-in-teams-meetings/teams-apps-in-meetings.md) | | 08/23/2022 | Share apps to the Teams meeting stage in mobile. | Build apps for Teams meetings and calls > [Enable and configure apps for meetings](apps-in-teams-meetings/teams-apps-in-meetings.md) | | 08/03/2022 | Use toggle incoming audio API to toggle the incoming audio state setting for the user in Teams meeting stage from mute to unmute or vice-versa. | Build apps for Teams meetings and calls > [Meeting apps API references](/microsoftteams/platform/apps-in-teams-meetings/api-references?tabs=dotnet) |