Receber todas as mensagens para bots e agentes

Observação

Embora as permissões RSC sejam suportadas para aplicações de bot existentes, recomendamos a migração para agentes. Para novas aplicações, crie agentes do zero e utilize permissões RSC para melhorar a experiência.

Receber todas as mensagens, mesmo sem @mentions, melhora bots e agentes ao fornecer melhor contexto, permitindo respostas proativas, interações personalizadas e resolução de problemas mais rápida. O modelo de permissões consentimento específico do recurso (RSC) das Graph APIs do Microsoft Teams melhora o desempenho e garante respostas atempadamente.

Os programadores podem personalizar o comportamento do bot de acordo com necessidades específicas ao especificar permissões no manifesto da aplicação. Os proprietários de conversações podem consentir que um bot receba todas as mensagens em canais e chats sem @mentions. O consentimento pode ser concedido durante o processo de instalação ou atualização da aplicação. Para obter mais informações, veja Permissões RSC.

Nota: os bots que recebem todas as mensagens de conversação com RSC são suportados na Cloud da Comunidade Governamental (GCC), GCC High, Departamento de Defesa (DoD) e Teams operados por ambientes da 21Vianet .

Permitir que os bots recebam todas as mensagens de canal ou chat

As permissões RSC são expandidas para bots e agentes e, com o consentimento do utilizador e a instalação da aplicação, estas permissões:

• Permitir que uma aplicação de grafo especificada obtenha todas as mensagens em canais e chats, respetivamente.

• Ative um bot definido no manifesto da aplicação para receber todas as mensagens de conversações sem estar @mentioned em contextos relevantes, onde se aplicam as seguintes permissões:

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

Para permitir que os bots ou agentes recebam todas as mensagens:

• Filtrar em mensagens menção
• Utilizar as APIs REST do Graph para aceder a todas as mensagens

Filtrar em mensagens menção

Pode permitir que o programador filtre mensagens de bot e processe apenas as mensagens que @mention os bots ou o agente. Isto pode ser útil por vários motivos:

• Garantir relevância contextual: é provável que as mensagens direcionadas para o bot tenham maior relevância para os utilizadores do bot ou do agente. Ajuda a aplicação a responder com precisão e a envolver-se em respostas significativas.
• Melhor desempenho do bot: filtrar mensagens pode reduzir a necessidade de processamento desnecessário para o bot ou o agente. O processamento de mensagens contextualmente irrelevantes pode ser evitado para melhorar o desempenho do bot. Também pode impedir que o bot, o agente ou o utilizador respondam a mensagens irrelevantes ou acionem ações desnecessárias.
• Melhorar a experiência do utilizador: é mais provável que os utilizadores interajam com o bot se este responder apenas quando este é abordado. O programador pode criar uma experiência de utilizador totalmente integrada e intuitiva.
• Processamento eficiente de mensagens: a filtragem de mensagens relevantes permite ao bot ou ao agente processar um maior volume de conversações e torná-lo mais útil e relacionável.

Eis um exemplo da utilização de permissões RSC para filtrar @mention mensagens:

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

Os programadores podem criar interfaces de conversação mais eficientes e fáceis de utilizar nos bots e agentes.

Utilizar as APIs REST do Graph para aceder a todas as mensagens

Os serviços que precisam de acesso a todos os dados de mensagens do Teams têm de utilizar as APIs REST do Graph para aceder a dados arquivados em canais e chats. O bot ou o agente tem de utilizar as ChannelMessage.Read.Group permissões E ChatMessage.Read.Chat RSC adequadamente para criar e melhorar a experiência envolvente para os utilizadores.

Para obter mais informações sobre a atualização de permissões RSC na descrição da aplicação, consulte Atualizar a descrição da aplicação para bots ou agentes.

Utilizar permissões RSC para melhorar os agentes de IA no Teams

Pode utilizar permissões RSC em agentes de IA para pedir acesso a recursos específicos, como correio, calendário ou ficheiros. Em vez de permissões abrangentes, o RSC permite permissões específicas do contexto de um recurso a um nível granular. Tem de determinar os recursos aos quais o agente de IA precisa de acesso no Microsoft Teams ou no Microsoft 365. Utilize permissões RSC para:

• Ler mensagens em canais do Teams.
• Aceder aos dados ou detalhes do utilizador.
• Aceder a documentos partilhados.

Por exemplo, utilize permissões RSC para um agente de IA para gerir conteúdos de canais.

Caso de uso	Como a permissão RSC no agente de IA pode ajudar
Contexto: um líder de equipa precisa que a equipa colabore num projeto futuro. Objetivo: para garantir que apenas os conteúdos relevantes e aprovados estão incluídos na conversação do canal.	Solução: utilize um agente para gerir conteúdos de conversação. O agente pode utilizar as seguintes permissões RSC: • ChannelMessage.Read.All • ChannelMessage.Delete.All • ChannelMessage.Send Resultado esperado: • Filtrar conteúdo irrelevante • Receber atualizações oportunas • A conversação está organizada

Atualizar manifesto do aplicativo

Para que o bot ou agente receba todas as mensagens de conversação, especifique as cadeias de permissão RSC relevantes na propriedade do authorization.permissions.resourceSpecific manifesto da sua aplicação. Para obter mais informações, veja esquema de manifesto de aplicação.

Eis um exemplo de manifesto de aplicação seguido de um fragmento de código de exemplo:

Neste exemplo de código:

• webApplicationInfo.id: O ID da aplicação Microsoft Entra. O ID da aplicação pode ser o mesmo que o ID do bot.
• webApplicationInfo.resource: qualquer cadeia. O campo de recurso não tem nenhuma operação no RSC. No entanto, tem de ser adicionado com um valor para evitar a resposta ao erro.
• authorization.permissions.resourceSpecific: permissões RSC para a sua aplicação com ou ambos ChannelMessage.Read.Group e ChatMessage.Read.Chat especificados. Para obter mais informações, consulte permissões específicas do recurso.

Selecione para ver um fragmento de código de exemplo para a versão 1.12 ou posterior do manifesto da aplicação

O fragmento de código seguinte fornece um exemplo de como pode declarar permissões RSC no manifesto da aplicação:

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

Carregar uma aplicação personalizada numa conversação

Depois de atualizar o manifesto da aplicação com as permissões RSC necessárias, siga estes passos para carregar a sua aplicação personalizada para o Teams.

Mensagens do canal

Os passos seguintes orientam-no para carregar e validar um bot que recebe todas as mensagens de canal numa Equipa sem ser @mentioned:

1. Selecione ou crie uma equipe.

2. Selecione ●●● no painel esquerdo. É apresentado o menu pendente.

3. Selecione Gerir equipa no menu pendente.

   

4. Selecione Aplicativos. Múltiplos aplicativos aparecem.

5. Escolha Upload um aplicativo personalizado no canto inferior direito.

   

6. Selecione Abrir.

   

7. Selecione Adicionar a partir do pop-up de detalhes da aplicação para adicionar a aplicação à sua equipa selecionada.

   

8. Selecione um canal e introduza uma mensagem no canal da sua aplicação.

   O bot ou agente recebe a mensagem sem ser @mentioned.

   

Mensagens de chat

Os passos seguintes orientam-no para carregar e validar um bot que recebe todas as mensagens de chat num chat sem ser @mentioned:

1. Selecione ou crie uma conversa de grupo.

2. Selecione as reticências ●●● na conversa de grupo. É apresentado o menu pendente.

3. Selecione Gerir aplicações no menu pendente.

   

4. Selecione Carregar uma aplicação personalizada no canto inferior direito de Gerir aplicações.

   

5. Selecione o pacote do aplicativo a partir da caixa de diálogo Abrir.

6. Selecione Abrir.

   

7. Selecione Adicionar no pop-up de detalhes da aplicação para adicionar o bot à sua conversa de grupo selecionada.

   

8. Introduza uma mensagem no chat de grupo do bot.

   

   O bot recebe a mensagem sem ser @mentioned.

   

Atualizar a descrição da aplicação para bots ou agentes

Para passar a aprovação da Microsoft Teams Store, a descrição da aplicação tem de incluir a forma como o bot ou a aplicação do agente utiliza os dados que lê:

• Os ChannelMessage.Read.Group bots e ChatMessage.Read.Chat não precisam de ser utilizados para extrair grandes quantidades de dados de clientes.

• A capacidade de os bots receberem todas as mensagens em chats utilizando ChatMessage.Read.Chat só é ativada após uma nova instalação ou instalação nova num chat:

  • Se tiver uma aplicação que esteja a utilizar o ChatMessage.Read.Chat para cenários do Graph, teste a aplicação ao seguir os passos em carregar uma aplicação personalizada numa conversação e modifique a aplicação antes de a funcionalidade estar geralmente disponível.
  • Se não quiser que a sua aplicação receba todas as mensagens de chat, utilize o fragmento de código para filtrar apenas as @mention mensagens.
  • Se não for efetuada nenhuma ação, o bot recebe todas as mensagens após a nova instalação.

• Tenha em atenção que permite que ChatMessage.Read.Chat a aplicação leia mensagens de chat, sem um utilizador com sessão iniciada. Para obter mais informações, veja Permissões RSC.

• A aplicação lê apenas as informações necessárias para as suas funções principais.

• A aplicação utiliza dados relevantes para as necessidades empresariais específicas que aborda para aumentar a produtividade e a colaboração.

Para obter mais informações, veja descrições de aplicações.

Trechos de código

O código seguinte fornece um exemplo das permissões RSC:

C#

• Referência do SDK
• Referência de código de exemplo

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

Node.js

• Referência do SDK
• Referência de código de exemplo

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

• Referência do SDK
• Referência de código de exemplo

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

Exemplo de código

Nome do exemplo	Descrição	.NET	Node.js	Python	Manifesto do aplicativo
Mensagens de canal com permissões RSC	Esta aplicação de exemplo mostra como um bot pode receber todas as mensagens de canal com RSC sem ser @mentioned.	View	View	View	Exibir

Confira também

• Enviar e receber mensagens
• Consentimento específico do recurso para a sua aplicação Teams
• Teste permissões de consentimento específicas do recurso no Teams
• Carregar seu aplicativo no Teams
• Listar respostas a mensagens num canal