Recepción de todos los mensajes de bots y agentes

Nota:

Aunque se admiten permisos de RSC para aplicaciones bot existentes, se recomienda migrar a agentes. En el caso de las nuevas aplicaciones, cree agentes desde cero y use permisos de RSC para mejorar la experiencia.

La recepción de todos los mensajes, incluso sin @mentions, mejora los bots y los agentes al proporcionar un mejor contexto, lo que permite respuestas proactivas, interacciones personalizadas y una resolución de problemas más rápida. El modelo de permisos de consentimiento específico de recursos (RSC) de las API de Microsoft Teams Graph mejora el rendimiento y garantiza respuestas oportunas.

Los desarrolladores pueden personalizar el comportamiento del bot para satisfacer necesidades específicas especificando permisos en el manifiesto de la aplicación. Los propietarios de conversaciones pueden dar su consentimiento para que un bot reciba todos los mensajes en canales y chats sin @mentions. El consentimiento se puede conceder durante el proceso de instalación o actualización de la aplicación. Para obtener más información, consulte Permisos de RSC.

Nota: Los bots que reciben todos los mensajes de conversación con RSC son compatibles con government community cloud (GCC), GCC High, Department of Defense (DoD) y Teams operados por entornos de 21Vianet .

Permitir que los bots reciban todos los mensajes de canal o chat

Los permisos de RSC se extienden a los bots y agentes, y con el consentimiento del usuario y la instalación de la aplicación, estos permisos:

• Permitir que una aplicación de grafos especificada obtenga todos los mensajes en canales y chats, respectivamente.

• Habilite un bot definido en el manifiesto de la aplicación para recibir todos los mensajes de conversación sin estar @mentioned en contextos pertinentes, donde se aplican los permisos siguientes:

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

Para permitir que los bots o agentes reciban todos los mensajes:

• Filtrar en mensajes de mención
• Uso de las API REST de Graph para acceder a todos los mensajes

Filtrar en mensajes de mención

Puede permitir que el desarrollador filtre los mensajes del bot y procese solo los mensajes que @mention los bots o el agente. Esto puede ser útil por varias razones:

• Garantizar la relevancia contextual: es probable que los mensajes dirigidos al bot tengan una mayor relevancia para los usuarios del bot o del agente. Ayuda a la aplicación a responder con precisión y a participar en respuestas significativas.
• Mejor rendimiento del bot: el filtrado de mensajes puede reducir la necesidad de procesamiento innecesario para el bot o el agente. El procesamiento de mensajes contextualmente irrelevantes se puede evitar para mejorar el rendimiento del bot. También puede impedir que el bot, el agente o el usuario respondan a mensajes irrelevantes o desencadenen acciones innecesarias.
• Mejorar la experiencia del usuario: es más probable que los usuarios interactúen con el bot si solo responde cuando se aborda. El desarrollador puede crear una experiencia de usuario sencilla e intuitiva.
• Control eficaz de mensajes: el filtrado de mensajes pertinentes permite al bot o al agente controlar un mayor volumen de conversaciones y hacerlo más útil y relatable.

Este es un ejemplo del uso de permisos de RSC para filtrar @mention mensajes:

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

Los desarrolladores pueden crear interfaces conversacionales más eficaces y fáciles de usar en los bots y agentes.

Uso de las API REST de Graph para acceder a todos los mensajes

Los servicios que necesitan acceso a todos los datos de mensajes de Teams deben usar las API REST de Graph para acceder a los datos archivados en canales y chats. El bot o el agente deben usar los ChannelMessage.Read.Group permisos y ChatMessage.Read.Chat RSC adecuadamente para crear y mejorar la experiencia atractiva para los usuarios.

Para obtener más información sobre cómo actualizar los permisos de RSC en la descripción de la aplicación, consulte Actualización de la descripción de la aplicación para bots o agentes.

Uso de permisos de RSC para mejorar los agentes de inteligencia artificial en Teams

Puede usar permisos de RSC en agentes de inteligencia artificial para solicitar acceso a recursos específicos, como correo, calendario o archivos. En lugar de permisos amplios, RSC permite permisos específicos para el contexto de un recurso en un nivel granular. Debe determinar los recursos a los que el agente de inteligencia artificial necesita acceso dentro de Microsoft Teams o Microsoft 365. Use permisos de RSC para:

• Leer mensajes en canales de Teams.
• Acceda a los datos o detalles del usuario.
• Acceso a documentos compartidos.

Por ejemplo, use permisos de RSC para que un agente de inteligencia artificial administre el contenido del canal.

Caso de uso	Cómo puede ayudar el permiso RSC en el agente de inteligencia artificial
Contexto: un líder de equipo necesita que su equipo colabore en un proyecto próximo. Objetivo: Garantizar que solo se incluya contenido relevante y aprobado en la conversación del canal.	Solución: use un agente para administrar el contenido de la conversación. El agente puede usar los siguientes permisos de RSC: • ChannelMessage.Read.All • ChannelMessage.Delete.All • ChannelMessage.Send Resultado esperado: • Filtrar contenido irrelevante • Recibir actualizaciones oportunas • La conversación está organizada

Actualizar el manifiesto de la aplicación

Para que el bot o agente reciba todos los mensajes de conversación, especifique las cadenas de permiso RSC pertinentes en la authorization.permissions.resourceSpecific propiedad del manifiesto de la aplicación. Para obtener más información, consulte esquema de manifiesto de aplicación.

Este es un ejemplo de manifiesto de aplicación seguido de un fragmento de código de ejemplo:

En este ejemplo de código:

• webApplicationInfo.id: identificador de la aplicación de Microsoft Entra. El identificador de la aplicación puede ser el mismo que el identificador del bot.
• webApplicationInfo.resource: cualquier cadena. El campo de recurso no tiene ninguna operación en RSC. Sin embargo, debe agregarse con un valor para evitar la respuesta al error.
• authorization.permissions.resourceSpecific: permisos de RSC para la aplicación con o ambos ChannelMessage.Read.Group y ChatMessage.Read.Chat especificados. Para obtener más información, vea permisos específicos del recurso.

Seleccione esta opción para ver un fragmento de código de ejemplo para el manifiesto de aplicación versión 1.12 o posterior

El siguiente fragmento de código proporciona un ejemplo de cómo puede declarar permisos de RSC en el manifiesto de la aplicación:

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

Carga de una aplicación personalizada en una conversación

Después de actualizar el manifiesto de aplicación con los permisos de RSC necesarios, siga estos pasos para cargar la aplicación personalizada en Teams.

Mensajes del canal

Los pasos siguientes le guían para cargar y validar un bot que recibe todos los mensajes de canal en un equipo sin ser @mentioned:

1. Seleccione o cree un equipo.

2. Seleccione ●●● en el panel izquierdo. Aparece el menú desplegable.

3. Seleccione Administrar equipo en el menú desplegable.

   

4. Seleccione Aplicaciones. Aparecen varias aplicaciones.

5. Seleccione Cargar una aplicación personalizada en la esquina inferior derecha.

   

6. Seleccione Abrir.

   

7. Seleccione Agregar en el elemento emergente detalles de la aplicación para agregar la aplicación al equipo seleccionado.

   

8. Seleccione un canal y escriba un mensaje en el canal de la aplicación.

   El bot o agente recibe el mensaje sin ser @mentioned.

   

Mensajes de chat

Los pasos siguientes le guían para cargar y validar un bot que recibe todos los mensajes de chat en un chat sin ser @mentioned:

1. Seleccione o cree un chat de grupo.

2. Seleccione los puntos suspensivos ●●● en el chat de grupo. Aparece el menú desplegable.

3. Seleccione Administrar aplicaciones en el menú desplegable.

   

4. Seleccione Cargar una aplicación personalizada en la esquina inferior derecha de Administrar aplicaciones.

   

5. Seleccione el paquete de la aplicación en el cuadro de diálogo Abrir.

6. Seleccione Abrir.

   

7. Seleccione Agregar en la ventana emergente de detalles de la aplicación para agregar el bot al chat de grupo seleccionado.

   

8. Escriba un mensaje en el chat de grupo del bot.

   

   El bot recibe el mensaje sin ser @mentioned.

   

Actualización de la descripción de la aplicación para bots o agentes

Para pasar la aprobación de Microsoft Teams Store, la descripción de la aplicación debe incluir cómo el bot o la aplicación del agente usa los datos que lee:

• Los ChannelMessage.Read.Group bots no necesitan usar y ChatMessage.Read.Chat para extraer grandes cantidades de datos de clientes.

• La posibilidad de que los bots reciban todos los mensajes en chats mediante ChatMessage.Read.Chat solo está habilitada después de una nueva instalación o una nueva instalación en un chat:

  • Si tiene una aplicación que usa para ChatMessage.Read.Chat escenarios de Graph, pruebe la aplicación siguiendo los pasos descritos en Cargar una aplicación personalizada en una conversación y modifique la aplicación antes de que la característica esté disponible con carácter general.
  • Si no quieres que la aplicación reciba todos los mensajes de chat, usa el fragmento de código para filtrar solo los @mention mensajes.
  • Si no se realiza ninguna acción, el bot recibe todos los mensajes después de la nueva instalación.

• Tenga en cuenta que permite que ChatMessage.Read.Chat la aplicación lea mensajes de chat sin que un usuario haya iniciado sesión. Para obtener más información, consulte Permisos de RSC.

• La aplicación solo lee la información necesaria para sus funciones principales.

• La aplicación usa datos relevantes para las necesidades empresariales específicas que aborda para aumentar la productividad y la colaboración.

Para obtener más información, consulte descripciones de aplicaciones.

Fragmentos de código

El código siguiente proporciona un ejemplo de los permisos de RSC:

C#

• Referencia del SDK
• Referencia de código de ejemplo

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

• Referencia del SDK
• Referencia de código de ejemplo

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

• Referencia del SDK
• Referencia de código de ejemplo

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

Ejemplo de código

Ejemplo de nombre	Descripción	.NET	Node.js	Python	Manifiesto de la aplicación
Mensajes de canal con permisos RSC	Esta aplicación de ejemplo muestra cómo un bot puede recibir todos los mensajes de canal con RSC sin ser @mentioned.	View	View	View	Ver

Consulte también

• Envío y recepción de mensajes
• Consentimiento específico de recursos para la aplicación de Teams
• Probar permisos de consentimiento específicos del recurso en Teams
• Cargar la aplicación en Microsoft Teams
• Enumerar las respuestas a los mensajes de un canal