Получение всех сообщений для ботов и агентов

Получение всех сообщений, даже без @mentions, улучшает работу ботов и агентов, обеспечивая лучший контекст, позволяя упреждающие ответы, персонализированное взаимодействие и более быстрое решение проблем. Модель разрешений "Согласие для конкретного ресурса" (RSC) API Microsoft Teams Graph повышает производительность и обеспечивает своевременные ответы.

Разработчики могут настроить поведение бота в соответствии с конкретными потребностями, указав разрешения в манифесте приложения. Владельцы бесед могут предоставить боту согласие на получение всех сообщений в каналах и чатах без @mentions. Согласие может быть предоставлено во время установки или обновления приложения. Дополнительные сведения см. в разделе Разрешения RSC.

Примечание. Боты, которые получают все сообщения беседы с помощью RSC, поддерживаются в облаке сообщества для государственных организаций (GCC), GCC High, Министерстве обороны (DoD) и Teams, управляемых средами 21Vianet .

Разрешить ботам получать все сообщения канала или чата

Разрешения RSC распространяются на ботов и агентов. При наличии согласия пользователя и установки приложения эти разрешения:

• Разрешите указанному приложению графа получать все сообщения в каналах и чатах соответственно.

• Разрешите боту, определенному в манифесте приложения, получать все сообщения бесед, не находясь @mentioned в соответствующих контекстах, где применяются следующие разрешения:

  • ChannelMessage.Read.Group
  • ChatMessage.Read.Chat

Чтобы разрешить ботам или агентам получать все сообщения, выполните приведенные далее действия.

• Фильтрация сообщений упоминание
• Использование REST API Graph для доступа ко всем сообщениям

Фильтрация сообщений упоминание

Вы можете включить разработчика для фильтрации сообщений бота и обработки только сообщений, которые @mention боты или агент. Это может быть полезно по нескольким причинам:

• Обеспечьте контекстную релевантность. Сообщения, направленные боту, скорее всего, будут иметь более высокую релевантность для пользователей бота или агента. Это помогает приложению точно реагировать и принимать значимые ответы.
• Повышение производительности бота. Фильтрация сообщений может уменьшить необходимость в ненужной обработке для бота или агента. Для повышения производительности бота можно избежать обработки контекстно нерелевантных сообщений. Это также может не допускать бота, агента или пользователя к реагированию на ненужные сообщения или активации ненужных действий.
• Улучшение взаимодействия с пользователем. Пользователи, скорее всего, будут взаимодействовать с ботом, если он реагирует только на обращение. Разработчик может создать простой и интуитивно понятный пользовательский интерфейс.
• Эффективная обработка сообщений. Фильтрация соответствующего сообщения позволяет боту или агенту обрабатывать больше бесед и делать их более полезными и легкомыслимыми.

Ниже приведен пример использования разрешений RSC для фильтрации @mention сообщений:

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

Разработчики могут создавать более эффективные и удобные диалоговые интерфейсы в ботах и агентах.

Использование REST API Graph для доступа ко всем сообщениям

Службы, которым требуется доступ ко всем данным сообщений Teams, должны использовать REST API Graph для доступа к архивным данным в каналах и чатах. Бот или агент должны использовать ChannelMessage.Read.Group разрешения И ChatMessage.Read.Chat RSC соответствующим образом для создания и улучшения взаимодействия с пользователями.

Дополнительные сведения об обновлении разрешений RSC в описании приложения см. в разделе Обновление описания приложения для ботов или агентов.

Использование разрешений RSC для улучшения агентов ИИ в Teams

Разрешения RSC в агентах ИИ можно использовать для запроса доступа к определенным ресурсам, таким как почта, календарь или файлы. Вместо широких разрешений RSC предоставляет разрешения, относящиеся к контексту ресурса, на уровне детализации. Необходимо определить ресурсы, к которым агенту ИИ требуется доступ в Microsoft Teams или Microsoft 365. Используйте разрешения RSC для:

• Чтение сообщений в каналах Teams.
• Доступ к сведениям или данным пользователя.
• Доступ к общим документам.

Например, используйте разрешения RSC для агента ИИ для управления содержимым канала.

Обновление манифеста приложения

Чтобы бот или агент получал все сообщения беседы, укажите соответствующие строки разрешений RSC в свойстве authorization.permissions.resourceSpecific манифеста приложения. Дополнительные сведения см. в разделе Схема манифеста приложения.

Ниже приведен пример манифеста приложения, за которым следует пример фрагмента кода:

В этом примере кода:

• webApplicationInfo.id: идентификатор приложения Microsoft Entra. Идентификатор приложения может совпадать с идентификатором бота.
• webApplicationInfo.resource: любая строка. Поле ресурса не имеет операции в RSC. Однако его необходимо добавить со значением, чтобы избежать ответа на ошибку.
• authorization.permissions.resourceSpecific: разрешения RSC для приложения с указанными или обоими ChannelMessage.Read.Group параметрами.ChatMessage.Read.Chat Подробнее см. в статье Разрешения для определенных ресурсов.

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

Отправка пользовательского приложения в беседе

После обновления манифеста приложения с необходимыми разрешениями RSC выполните следующие действия, чтобы отправить пользовательское приложение в Teams.

Обновление описания приложения для ботов или агентов

Чтобы пройти утверждение Microsoft Teams Store, в описании приложения должно быть описано, как бот или приложение агента использует считываемые данные:

• И ChannelMessage.Read.GroupChatMessage.Read.Chat не должны использоваться ботами для извлечения больших объемов данных клиентов.

• Возможность для ботов получать все сообщения в чатах с помощью ChatMessage.Read.Chat включена только после повторной установки или новой установки в чате:

  • Если у вас есть приложение, использующее ChatMessage.Read.Chat для сценариев Graph, протестируйте приложение, выполнив действия, описанные в статье Отправка пользовательского приложения в беседу и изменение приложения, прежде чем функция станет общедоступной.
  • Если вы не хотите, чтобы приложение получало все сообщения чата, используйте фрагмент кода для фильтрации @mention только сообщений.
  • Если никаких действий не выполняется, бот получает все сообщения после новой установки.

• Обратите внимание, что ChatMessage.Read.Chat приложение может читать сообщения чата без вошедшего пользователя. Дополнительные сведения см. в разделе Разрешения RSC.

• Приложение считывает только сведения, необходимые для его основных функций.

• Приложение использует данные, соответствующие конкретным бизнес-потребностям, которые оно решает для повышения производительности и совместной работы.

Дополнительные сведения см. в разделе описания приложений.

Фрагменты кода

В следующем коде приведен пример разрешений RSC:

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

Пример кода

См. также

• Отправка и получение сообщений
• Согласие для конкретного ресурса для приложения Teams
• Проверка разрешений согласия для определенных ресурсов в Teams
• Отправка приложения в Microsoft Teams
• Вывод списка ответов на сообщения в канале