Compartir vía

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

  • Artículo

Importante

Este artículo se basa en el SDK de Bot Framework v3. Si busca la versión 4.6 o posterior de la documentación actual del SDK, consulte la sección bots conversacionales .

Microsoft Teams permite a los usuarios incluir bots en sus conversaciones de chat de canal o grupo. Al agregar un bot a un equipo o chat, todos los usuarios de la conversación pueden aprovechar la funcionalidad del bot directamente en la conversación. También puede acceder a la funcionalidad específica de Teams dentro del bot, como consultar la información del equipo y @mentioning los usuarios.

Chat en canales y chats grupales difiere del chat personal en que el usuario necesita para @mention el bot. Si se usa un bot en varios ámbitos, como personal, chat en grupo o canal, debe detectar de qué ámbito proceden los mensajes del bot y procesarlos en consecuencia.

Diseño de un bot excelente para canales o grupos

Los bots agregados a un equipo se convierten en otro miembro del equipo y pueden formar @mentioned parte de la conversación. De hecho, los bots solo reciben mensajes cuando son @mentioned, por lo que otras conversaciones en el canal no se envían al bot.

Un bot de un grupo o canal debe proporcionar información relevante y adecuada para todos los miembros. Aunque el bot puede proporcionar sin duda cualquier información relevante para la experiencia, tenga en cuenta que las conversaciones con él son visibles para todos los usuarios. Por lo tanto, un bot excelente en un grupo o canal debe agregar valor a todos los usuarios y, sin duda, no compartir accidentalmente información más adecuada para una conversación uno a uno.

El bot, tal como es, puede ser totalmente relevante en todos los ámbitos sin necesidad de más trabajo. En Teams, no hay ninguna expectativa de que el bot funcione en todos los ámbitos, pero debe asegurarse de que el bot proporciona el valor de usuario en los ámbitos que elija admitir.

El desarrollo de un bot que funciona en grupos o canales usa gran parte de la misma funcionalidad que las conversaciones personales. Los eventos y datos adicionales de la carga proporcionan información de grupo y canal de Teams. Estas diferencias, así como las diferencias clave en la funcionalidad común, se describen en las secciones siguientes.

Creación de mensajes

Para obtener más información sobre los bots que crean mensajes en canales, consulte Mensajería proactiva para bots y, específicamente, Creación de una conversación de canal.

Recepción de mensajes

Para un bot de un grupo o canal, además del esquema de mensajes de registro, el bot también recibe las siguientes propiedades:

  • channelData Consultar Datos del canal de Teams. En un chat grupal, contiene información específica de ese chat.
  • conversation.id El identificador de la cadena de respuesta, que consta del identificador de canal más el identificador del primer mensaje de la cadena de respuesta.
  • conversation.isGroup Es true para mensajes de bot en canales o chats grupales.
  • conversation.conversationTypeYa sea groupChat o channel.
  • entities Puede contener una o varias menciones. Para obtener más información, consulte Menciones.

Responder a mensajes

Para responder a un mensaje existente, llame a ReplyToActivity en .NET o session.senden Node.js. El Bot Builder de SDK controla todos los detalles.

Si decide usar la API rest, también puede llamar al punto de conexión /conversations/{conversationId}/activities/{activityId}.

En un canal, la respuesta a un mensaje se muestra como una respuesta a la cadena de respuesta inicial. El conversation.id contiene el canal y el identificador de mensaje de nivel superior. Aunque el Bot Framework se encarga de los detalles, puede almacenar en caché ese conversation.id para futuras respuestas a ese hilo de conversación según sea necesario.

Procedimiento recomendado: Mensajes de bienvenida en Teams

Cuando el bot se agrega por primera vez al grupo o equipo, es útil enviar un mensaje de bienvenida que presenta el bot a todos los usuarios. El mensaje de bienvenida debe proporcionar una descripción de la funcionalidad del bot y las ventajas del usuario. Lo ideal es que el mensaje también incluya comandos para que el usuario interactúe con la aplicación. Para ello, asegúrese de que el bot responde al mensaje conversationUpdate con teamsAddMembers eventType en el objeto channelData. Asegúrese de que el identificador de memberAdded es el propio identificador de aplicación del bot, ya que el mismo evento se envía cuando se agrega un usuario a un equipo. Para obtener más información, consulte Adición de bot o miembro del equipo.

También puede enviar un mensaje personal a cada miembro del equipo cuando se agregue el bot. Para ello, podría buscar la lista del equipo y enviar a cada usuario un mensaje directo.

Se recomienda que el bot no enviar un mensaje de bienvenida en las situaciones siguientes:

  • El equipo es grande (obviamente subjetivo, por ejemplo, más de 100 miembros). Es posible que el bot se vea como "correo no deseado" y que la persona que lo agregó reciba 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, en lugar de agregarse 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.

Menciones @

Dado que los bots de un grupo o canal responden solo cuando se mencionan ("@botname") en un mensaje, cada mensaje recibido por un bot en un canal de grupo contiene su propio nombre y debe asegurarse de que el análisis de mensajes lo controla. Además, los bots pueden analizar otros usuarios mencionados y mencionar a los usuarios como parte de sus mensajes.

Recuperación de 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. Puede recuperar todas las menciones del mensaje llamando a la función GetMentions en el SDK de Bot Builder para .NET, que devuelve una matriz de objetos Mentioned.

Código de ejemplo de .NET: buscar y quitar @bot mención

Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}

Nota:

También puede usar la función de extensión de Teams GetTextWithoutMentions, que elimina todas las menciones, incluido el bot.

Node.js código de ejemplo: Buscar y quitar @bot mención

var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

También puede usar la función de extensión de Teams getTextWithoutMentions, que elimina todas las menciones, incluido el bot.

Construcción de menciones

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

  • Incluya <at>@username</at> en el texto del mensaje.
  • Incluya el objeto mention dentro de la colección de entidades.

Ejemplo de .NET

En este ejemplo se usa el Microsoft.Bot.Connector.Teams paquete NuGet.

// Create reply activity
Activity replyActivity = activity.CreateReply();

// Construct text of the form @sender Hello
replyActivity.Text = "Hello ";
replyActivity.AddMentionToText(activity.From, MentionTextLocation.AppendText);

// Send the reply activity
await client.Conversations.ReplyToActivityAsync(replyActivity);

Ejemplo de Node.js

// User to mention
var toMention: builder.IIdentity = {
    name: 'John Doe',
    id: userId
};

// Create a message and add mention to it
var msg = new teams.TeamsMessage(session).text(teams.TeamsMessage.getTenantId(session.message));
var mentionedMsg = msg.addMentionToText(toMention);

// Post the message
var generalMessage = mentionedMsg.routeReplyToGeneralChannel();
session.send(generalMessage);

Ejemplo: mensaje saliente con el usuario mencionado

{
    "type": "message", 
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "28:9e52142b-5e5e-4d7b-bb3e- e82dcf620000",
        "name": "SchemaTestBot"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Acceso a groupChat o ámbito de canal

El bot puede hacer más que enviar y recibir mensajes en grupos y equipos. Por ejemplo, también puede capturar la lista de miembros, incluida su información de perfil, y la lista de canales. Para obtener más información, vea Obtenga el contexto para su bot de Microsoft Teams.

Vea también

Ejemplos de Bot Framework.