Conversaciones de chat de canal y grupo con un bot de Microsoft Teams

Importante

Los ejemplos de código de esta sección se basan en 4,6 y versiones posteriores del SDK de bot Framework. Si está buscando documentación para versiones anteriores, vea la sección SDK de bots-V3 en la carpeta recursos de la documentación.

Al agregar el ámbito o al bot, puede estar disponible para instalarse en un chat de teams groupchat grupo o equipo. Esto permite que todos los miembros de la conversación interactúen con el bot. Una vez instalado, también tendrá acceso a metadatos sobre la conversación, como la lista de miembros de la conversación, y cuando se instala en los detalles de un equipo sobre ese equipo y la lista completa de canales.

Los bots de un grupo o canal solo reciben mensajes cuando se mencionan (@botname), no reciben ningún otro mensaje enviado a la conversación.

Nota

El bot debe ser @mentioned directamente. El bot no recibirá un mensaje cuando se menciona al equipo o al canal, o cuando alguien responda a un mensaje de su bot sin @mentioning lo haga.

Directrices de diseño

Vea cómo diseñar conversaciones de bot en canales y chats.

Creación de nuevos subprocesos de conversación

Cuando el bot está instalado en un equipo, a veces puede ser necesario crear un nuevo hilo de conversación en lugar de responder a uno existente. Se trata de una forma de mensajería proactiva.

Trabajar con menciones

Cada mensaje a su bot desde un grupo o canal contendrá un @mention con su propio nombre en el texto del mensaje, por lo que tendrá que asegurarse de que el análisis de mensajes lo controla. El bot también puede recuperar otros usuarios mencionados en un mensaje y agregar menciones a los mensajes que envíe.

Quitar menciones del texto del mensaje

Es posible que sea necesario quitar el @mentions del texto del mensaje que recibe el bot.

Recuperar menciones

Las menciones se devuelven en el objeto en carga y contienen el identificador único del usuario y, en la mayoría de los casos, el nombre entities del usuario mencionado. El texto del mensaje también incluirá la mención como <at>@John Smith<at> . Sin embargo, no debe confiar en el texto del mensaje para recuperar información sobre el usuario; es posible que la persona que envía el mensaje lo modifique. En su lugar, use el entities objeto.

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

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

Agregar menciones a los mensajes

El bot puede mencionar a otros usuarios en mensajes publicados en canales. Para ello, el mensaje debe hacer lo siguiente:

El Mention objeto tiene dos propiedades que deberá establecer:

  • Incluir @username en el texto del mensaje
  • Incluir el objeto de mención dentro de la colección de entidades

El SDK de Bot Framework proporciona objetos y métodos auxiliares para facilitar la construcción de la mención.

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>",
    };

    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

Enviar un mensaje durante la instalación

Cuando el bot se agrega por primera vez al grupo o equipo, puede resultar útil enviar un mensaje que lo presenta. El mensaje debe proporcionar una breve descripción de las características del bot y cómo usarlas. You'll want to subscribe to the conversationUpdate event, with the teamMemberAdded eventType. Dado que el evento se envía cuando se agrega un nuevo miembro del equipo, debe comprobar si el nuevo miembro agregado es el bot. Consulte Enviar un mensaje de bienvenida a un nuevo miembro del equipo para obtener más información.

Es posible que también desee enviar un mensaje personal a cada miembro del equipo cuando se agrega el bot. Para ello, puede obtener la lista del equipo y enviar un mensaje directo a cada usuario.

No se recomienda enviar un mensaje en las siguientes situaciones:

  • El equipo es grande (obviamente subjetivo, pero por ejemplo más de 100 miembros). Es posible que el bot se vea como "spammy" y la persona que lo agregó puede recibir quejas a menos que comunique claramente la propuesta de valor del bot a todos los usuarios que vean el mensaje de bienvenida.
  • El bot se menciona por primera vez en un grupo o canal (frente a que se agrega por primera vez a un equipo)
  • Se cambia el nombre de un grupo o canal
  • Se agrega un miembro del equipo a un grupo o canal

Más información

El bot tiene acceso a información adicional sobre el chat en grupo o el equipo en el que está instalado. Vea obtener el contexto de teams para obtener api adicionales disponibles para su bot.

También hay eventos adicionales a los que el bot puede suscribirse y responder. Vea suscribirse a eventos de conversación para obtener información sobre cómo hacerlo.

Ejemplos de robots de Teams

Para obtener una muestra completa que muestre algunas de estas funciones, consulte los ejemplos de Microsoft Teams para bot Framework

Muestra Descripción .NET Core JavaScript Python
Bot de conversación de Microsoft Teams Control de eventos de mensajería y conversación. View View View
Autenticación con OAuthPrompt Authentication and Basic Messaging in Bot Framework V4. View View View
Carga de archivos de Teams Intercambio de archivos con un bot en una conversación de uno a uno. View View View
Módulo de tareas Demostración de cómo recuperar un módulo de tareas y valores de tarjetas en él, para obtener una extensión de mensajería. View View View
Iniciar un nuevo hilo en un canal Demostrar cómo se crea un nuevo hilo en un canal. View View View