Receive conversation messages with RSC

發行項
12/18/2024

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.

Note

Bots that receive all conversation messages with RSC are supported in Government Community Cloud (GCC), GCC-High, and Department of Defense (DOD) 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

// 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<IMessageActivity> 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 and modify the app before the feature is generally available. If you don't want your bot to receive all chat messages, implement the following code snippet. 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.

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.

The following code provides an example of the app manifest version 1.12 or later:

{
    "$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": []
}

The following steps guide you to upload and validate bot that receives all channel messages in a Team without being @mentioned:

Select or create a team.
Select ●●● from the left pane. The dropdown menu appears.
Select Manage team from the dropdown menu.
Select Apps. Multiple apps appear.
Select Upload a custom app from the lower right corner.
Select Open.
Select Add from the app details pop-up, to add the bot to your selected team.
Select a channel and enter a message in the channel for your bot.

The bot receives the message without being @mentioned.

Code snippets

The following code provides an example of the RSC permissions:

C#
Node.js


// 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<IMessageActivity> 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."));
}


// 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	View	View

共用方式為