Receive all messages for bots and agents

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.

Note: Bots that receive all conversation messages with RSC are supported in Government Community Cloud (GCC), GCC High, Department of Defense (DoD), and Teams operated by 21Vianet 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
• 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:

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

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.

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.

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.

Here's an app manifest example followed by a sample code snippet:

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.

{
    "$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.

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

• 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.

Code snippets

The following code provides an example of the RSC permissions:

// 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 a 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();
});

 # 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

See also

• Send and receive messages
• Resource-specific consent for your Teams app
• Test resource-specific consent permissions in Teams
• Upload your app in Teams
• List replies to messages in a channel