Compartir a través de

Canal y conversaciones de chat de grupo con un bot

  • Artículo

Importante

Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones posteriores del SDK de Bot Framework. Si busca documentación para versiones anteriores, consulte la sección bots - v3 SDK en la carpeta SDK heredados de la documentación.

Para instalar el bot de Microsoft Teams en un chat de grupo o equipo, agregue el ámbito teams o groupchat al bot. Esto permite que todos los miembros de la conversación interactúen con el bot. Una vez instalado el bot, tiene acceso a metadatos sobre la conversación, como la lista de miembros de la conversación. Además, cuando se instala en un equipo, el bot tiene acceso a los detalles sobre ese equipo y a la lista completa de canales.

Los bots de un grupo o canal solo reciben mensajes cuando se les menciona @botname. No reciben ningún otro mensaje enviado a la conversación. El bot debe estar @mentioned directamente. El bot no recibe un mensaje cuando se menciona el equipo o el canal, o cuando alguien responde a un mensaje del bot sin @mentioning él.

Nota:

Consulte el siguiente vídeo para obtener información sobre las conversaciones de chat de canal y grupo con un bot:


Directrices de diseño

A diferencia de los chats personales, en los chats y canales de grupo, el bot debe proporcionar una introducción rápida. Debe seguir estas y más instrucciones de diseño de bots. Para obtener más información sobre cómo diseñar bots en Teams, consulte cómo diseñar conversaciones de bots en canales y chats.

Ahora, puede crear nuevos subprocesos de conversación y administrar fácilmente diferentes conversaciones en canales.

Creación de nuevos subprocesos de conversación

Cuando el bot está instalado en un equipo, debe crear un nuevo subproceso de conversación en lugar de responder a uno existente. A veces, es difícil diferenciar entre dos conversaciones. Si la conversación está en subprocesos, es más fácil organizar y administrar diferentes conversaciones en canales. Se trata de una forma de mensajería proactiva.

A continuación, puede recuperar las menciones mediante el objeto entities y agregar menciones a los mensajes mediante el objeto Mention.

Trabajar con menciones

Cada mensaje al bot desde un grupo o canal contiene un @mention con su nombre en el texto del mensaje. El bot también puede recuperar otros usuarios mencionados en un mensaje y agregar menciones a cualquier mensaje que envíe. Los bots de los chats en grupo permiten menciones de usuario mediante @mention; sin embargo, no admiten @everyone menciones.

También debe quitar el @mentions contenido del mensaje que recibe el bot.

Recuperar menciones

Las menciones se devuelven en el objeto entities de entidades en carga y contienen tanto el id. único del usuario como, en la mayoría de los casos, el nombre del usuario mencionado. El texto del mensaje también incluye la mención, como <at>@John Smith<at>. Sin embargo, no confíe en el texto del mensaje para recuperar información sobre el usuario. Es posible que la persona que envía el mensaje lo altere. Por lo tanto, use el objeto entities.

Puede recuperar todas las menciones del mensaje llamando a la función GetMentions en el SDK de Bot Builder, que devuelve una matriz de objetos Mention.

En el siguiente código se muestra un ejemplo de recuperación de menciones:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Resolves the mentions from the entities activity.
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

Agregar menciones a los mensajes

Hay dos tipos de menciones:

Nota:

La mención de usuario y la mención de etiquetas se admiten para el mensaje de texto y la tarjeta adaptable.

Mención del usuario

El bot puede mencionar a otros usuarios en mensajes publicados en canales.

El objeto Mention tiene dos propiedades que debe establecer mediante lo siguiente:

  • Incluya @username en el texto del mensaje.
  • Incluya el objeto mention dentro de la colección entities.

El SDK de Bot Framework proporciona métodos auxiliares y objetos para crear menciones.

En el siguiente código se muestra un ejemplo de adición de menciones en los mensajes:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
        Type = "mention",
    };

    // Returns a simple text message.
    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

Ahora puede enviar un mensaje de introducción cuando el bot se instala por primera vez o se agrega a un grupo o equipo.

Compatibilidad con Microsoft Entra id. de objeto y UPN en la mención del usuario

Los bots admiten identificadores de mención de usuario, como Microsoft Entra id. de objeto y nombre principal de usuario (UPN), además de los identificadores existentes. Los webhooks entrantes comienzan a admitir la mención del usuario en la tarjeta adaptable con el identificador de objeto Microsoft Entra y el UPN.

En el fragmento de código siguiente se muestra un ejemplo de mención a los usuarios con el id. de objeto Entra y UPN en un mensaje de texto:

var userId = "Adele@microsoft.com"; //User Principle Name
var mention = new ChannelAccount(userId, "Adele"); 
var mentionObj = new Mention 
{
    Mentioned = mention,
    Text = $"<at>{mention.Name}</at>" ,
    Type = "mention"
}; 

// Returns a simple text message.var replyActivity = MessageFactory.Text($"Hello {mentionObj.Text}.");replyActivity.Entities = new List<Entity> { mentionObj };

// Sends an activity to the sender of the incoming activity.await turnContext.SendActivityAsync(replyActivity, cancellationToken);

En el siguiente fragmento de código se muestra un ejemplo de mención a los usuarios con id. de objeto Entra y UPN en una tarjeta adaptable:

{
    "type": "mention",
    "text": "<at>Adele</at>",
    "mentioned": {
            "id": "Adele@microsoft.com" ,// User Principle Name
            "name": "Adele"
    }
}

Mención de etiquetas

El bot puede mencionar etiquetas en mensajes de texto y tarjetas adaptables publicadas en canales. Cuando el bot @mentions es la etiqueta de un canal, la etiqueta se resalta y se notifica a las personas asociadas a la etiqueta. Cuando un usuario mantiene el puntero sobre la etiqueta, aparece un elemento emergente con los detalles de la etiqueta.

Mención de etiquetas en un mensaje de texto

En el mention.properties objeto , agregue la propiedad 'type': 'tag'. Si no se agrega la propiedad 'type': 'tag' , el bot trata la mención como una mención del usuario.

Ejemplo:

type:tag se agrega como en Properties ChannelAccount.

Referencia del SDK

​var mention = new ChannelAccount(tagId, "Test Tag"); 
​mention.Properties = JObject.Parse("{'type': 'tag'}"); 
​var mentionObj = new Mention 
​{ 
​    Mentioned = mention, 
​    Text = "<at>Test Tag</at>" 
​}; 

​var replyActivity = MessageFactory.Text("Hello " + mentionObj.Text); 
​replyActivity.Entities = new List<Microsoft.Bot.Schema.Entity> { mentionObj }; 
​await turnContext.SendActivityAsync(replyActivity, cancellationToken);
Mencionar etiquetas en una tarjeta adaptable

En el esquema de tarjeta adaptable, en el mentioned objeto , agregue la "type": "tag" propiedad . Si no se agrega la "type": "tag" propiedad, el bot trata la mención como una mención del usuario.

Puede obtener la lista de las etiquetas disponibles en el canal mediante list teamworkTags API.

Ejemplo:

​{ 
​    "type": "mention", 
    ​"text": "<at>Test Tag</at>", 
​    "mentioned": { 
            ​"id": "base64 encoded id" ,// tag graph 64 base ID
​            "name": "Test Tag", 
            ​"type": "tag" 
​    } 
​}
Parámetros de consulta
Nombre Descripción
type Tipo de mención. El tipo admitido es tag.
id Identificador único de la etiqueta. Para obtener más información, consulte teamworkTag.
Código de error
Código de estado Código de error Valores de mensaje Solicitud de reintento Acción del desarrollador
400 Código: Bad Request La etiqueta mencionada con el identificador {id string} no existe en el equipo actual.
La etiqueta solo se puede mencionar en el canal
Etiqueta mencionada no válida porque no existe ninguna etiqueta en el equipo		 No Vuelva a evaluar la carga de la solicitud para los errores. Compruebe el mensaje de error devuelto para obtener más información.
502 Código: Bad Gateway Identificador de grupo de equipo no válido
Identificador de inquilino con formato incorrecto para la etiqueta
No se puede resolver el identificador de mención		 No Vuelva a intentarlo manualmente.
Superado la limitación

Cualquier solicitud se puede evaluar con varios límites, según el ámbito, el tipo de ventana (corto y largo), el número de etiquetas por mensaje y otros factores. El primer límite alcanzado activa la limitación de solicitudes.

Asegúrese de que no supera los límites de limitación para evitar la entrega de mensajes con errores. Por ejemplo, un bot solo puede enviar dos mensajes con mención de etiquetas en una ventana de cinco segundos y cada mensaje solo puede tener hasta 10 etiquetas.

En la tabla siguiente se enumeran los límites de limitación de las menciones de etiquetas en un bot:

Alcance Tipo de ventana Número de etiquetas por mensaje Ventanas de tiempo (s) Número máximo de mensajes por período de tiempo
Por bot por subproceso Corto 10 5 2
  Largo 10 60 5
Todos los bots por subproceso Corto 10 5 4
  Long 10 60 5
Limitaciones
  • Las menciones de etiquetas solo se admiten en el flujo de mensajes de bot a cliente con texto y tarjeta adaptable.
  • Las menciones de etiquetas no se admiten en canales compartidos y privados.
  • Las menciones de etiquetas no se admiten en los conectores.
  • Las menciones de etiquetas no admiten el flujo de invocación en un bot.

Enviar un mensaje durante la instalación

Cuando el bot se agrega por primera vez al grupo o equipo, se debe enviar un mensaje de introducción. El mensaje debe proporcionar una breve descripción de las características del bot y cómo usarlas. Debe suscribirse al evento conversationUpdate con el eventType teamMemberAdded. El evento se envía cuando se agrega un nuevo miembro del equipo. Compruebe si el nuevo miembro agregado es el bot. Para obtener más información, consulte Envío de un mensaje de bienvenida a un nuevo miembro del equipo.

Puede enviar un mensaje personal a cada miembro del equipo cuando se agregue el bot. Para ello, recupere la lista de equipos y envíe un mensaje directo a cada usuario.

Nota:

Asegúrese de que el mensaje enviado por el bot es relevante y agrega valor al mensaje inicial y no envía correo no deseado a los usuarios.

No envíe un mensaje en los siguientes casos:

  • Cuando el equipo es grande, por ejemplo, más de 100 miembros. El bot se puede ver como correo no deseado y la persona que lo agregó puede recibir quejas. Debe comunicar claramente la propuesta de valor del bot a todos los usuarios que ven el mensaje de bienvenida.
  • El bot se menciona por primera vez en un grupo o canal en lugar de agregarse primero a un equipo.
  • Se cambia el nombre del grupo o canal.
  • Un miembro del equipo se agrega a un grupo o canal.

Ejemplos de bot de Teams

Ejemplo de código

Para obtener ejemplos de trabajo completos que muestran la funcionalidad, consulte los siguientes ejemplos de Teams para Bot Framework:

Ejemplo de nombre Descripción .NET Node.js Python Manifiesto
Bot de conversación de Teams En este ejemplo se muestra cómo usar diferentes eventos de conversación de bot disponibles en bot framework v4 para el ámbito personal y de teams. View View View View
Autenticación con OAuthPrompt En este ejemplo se muestra la autenticación y la mensajería básica en Bot Framework v4. View View View View
Carga de archivos de Teams En este ejemplo se muestra cómo usar archivos con un bot en una conversación uno a uno. View View View View
Cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x) En este ejemplo se muestra cómo usar un cuadro de diálogo y los valores de las tarjetas en él para una extensión de mensaje. View View View View
Inicio de un nuevo subproceso en un canal En este ejemplo se muestra cómo usar un nuevo subproceso en un canal mediante bot. View View View View
Localización de aplicaciones de Teams En este ejemplo se muestra cómo usar la localización de aplicaciones de Teams mediante bot y pestaña. View View ND View

Guía paso a paso

Siga la guía paso a paso para crear un bot de conversación de Teams.

Paso siguiente

Suscribirse a eventos de conversación

Consulte también