Edit

Enable an agent to receive all chat messages

By default, the only chat messages that agents receive or can access via Graph APIs are the ones where they're @mentioned. This behavior predates LLM-driven agents: historically, scripted or flow-based bots had no need to receive messages that didn't directly invoke them. Additionally, requiring the explicit consent of conversation owners for agents to access all of their conversation's messages aligns with Teams' stance on data privacy.

Modern agents are most effective when they can observe and process all of the messages in conversations where they participate. To receive and access all chat messages in a channel or chat, an agent must request the appropriate resource-specific consent permissions via its manifest.

Note

This capability is supported in Microsoft Teams commercial environments, Government Community Cloud (GCC), GCC High, Department of Defense (DoD), and Teams operated by 21Vianet environments.

Update requested RSC permissions

To enable your agent to receive all conversation messages, include one or both of the following RSC permission declarations in the agent's app manifest:

  • ChannelMessage.Read.Group: Receive all messages in the channels of the team where the app is installed.
  • ChatMessage.Read.Chat: Receive all messages in the group chat where the app is installed.

Example:

{
"webApplicationInfo": {
  "id": "",
  "resource": "https://RscBasedStoreApp"
},
"authorization": {
  "permissions": {
    "resourceSpecific": [
      {
        "name": "ChannelMessage.Read.Group",
        "type": "Application"
      },
      {
        "name": "ChatMessage.Read.Chat",
        "type": "Application"
        }
    ]
  }
}
}

After you update the permissions, install or upgrade the app in the target team or group chat. The team or chat owner must consent to the requested RSC permissions during installation.

For more information, see the app manifest schema documentation.

Update permissions in Developer Portal

Alternatively, use Teams Developer Portal to configure RSC permissions instead of editing the app manifest directly:

  1. Sign in to Developer Portal for Teams.
  2. Select Apps, and then select your app.
  3. Under Configure, select Permissions.
  4. Under Team permissions, add ChannelMessage.Read.Group to receive channel messages.
  5. Under Chat/Meeting permissions, add ChatMessage.Read.Chat to receive group chat messages.
  6. Select Save.

Filter @mention messages

In some scenarios, once an agent has access to all messages in a conversation, it can be helpful to distinguish between messages where the agent is @mentioned and where it isn't. Messages in which the agent is @mentioned typically include direct requests from users and are of the highest relevance, and you might want to prioritize their processing when the agent is under load. When retrieving and using historical messages to assemble context, @mention messages might be considered higher-priority than other messages.

The following code illustrates how to create a filter to determine whether the agent is @mentioned in a message. Here, it's shown in use as a filter on received messages, but it can be applied to message activities in any scenario.

// When ChannelMessage.Read.Group or ChatMessage.Read.Chat RSC is in the app manifest, this method is called even when agent is not @mentioned.
// This code snippet allows the agent to ignore all messages that do not @mention the agent.
teams.OnMessage(async (context, cancellationToken) =>
{
    // Ignore the message if agent was not mentioned.
    // Remove this if block to process all messages received by the agent.
    if (!context.Activity.GetMentions().Any(mention => mention.Mentioned.Id.Equals(context.Activity.Recipient.Id, StringComparison.OrdinalIgnoreCase)))
    {
        return;
    }

// Sends an activity to the sender of the incoming activity.
await context.SendAsync(
    "Using RSC the agent can receive messages across channels or chats in team without being @mentioned.",
    cancellationToken);
});

// When ChannelMessage.Read.Group or ChatMessage.Read.Chat RSC is in the app manifest, this method is called even when agent is not @mentioned.
// This code snippet allows the agent to ignore all messages that do not @mention the agent.
app.on('message', async ({ activity, send }) => {
  // Ignore the message if agent was not mentioned.
  // Remove this if block to process all messages received by the agent.
  const mentioned = activity.entities?.some(
    (entity) =>
      entity.type === 'mention' &&
      entity.mentioned?.id === activity.recipient.id
  );

  if (!mentioned) {
    return;
  }

  // Sends an activity to the sender of the incoming activity.
  await send(
    'Using RSC the agent can receive messages across channels or chats in team without being @mentioned.'
  );
});

# When ChannelMessage.Read.Group or ChatMessage.Read.Chat RSC is in the app manifest, this method is called even when agent is not @mentioned.
# This code snippet allows the agent to ignore all messages that do not @mention the agent.
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Ignore the message if agent was not mentioned.
    # Remove this if block to process all messages received by the agent.
    mentioned = any(
        entity.type == "mention"
        and entity.mentioned.id == ctx.activity.recipient.id
        for entity in (ctx.activity.entities or [])
    )

    if not mentioned:
        return

    # Sends an activity to the sender of the incoming activity.
    await ctx.send(
        "Using RSC the agent can receive messages across channels or chats in team without being @mentioned."
    )

Update the app description

To pass the Microsoft Teams Store approval, the app description must describe how an agent uses the data it has access to, including chat messages. If your agent receives all messages in conversations in which it participates, consider including a statement about how it uses and protects that data.

For more information, see app descriptions.

See also

  • Last updated on