Canais e conversas de chat em grupo com um bot do Microsoft Teams

Importante

Este artigo baseia-se no SDK v3 do Bot Framework. Se estiver à procura da versão atual da documentação 4.6 ou posterior do SDK, consulte a secção bots de conversação .

O Microsoft Teams permite que os usuários tragam bots para seu canal ou conversas de chat em grupo. Ao adicionar um bot a uma equipe ou chat, todos os usuários da conversa podem aproveitar a funcionalidade do bot diretamente na conversa. Também pode aceder a funcionalidades específicas do Teams no seu bot, como consultar os utilizadores e @mentioning as informações da equipa.

O chat em canais e conversas de grupo difere do chat pessoal, na qual o utilizador precisa @mention do bot. Se um bot for utilizado em vários âmbitos, como pessoal, chat de grupo ou canal, tem de detetar o âmbito de onde as mensagens do bot vieram e processá-las em conformidade.

Projetando um ótimo bot para canais ou grupos

Os bots adicionados a uma equipa tornam-se outro membro da equipa e podem fazer @mentioned parte da conversação. Na verdade, os bots só recebem mensagens quando são @mentioned, para que outras conversações no canal não sejam enviadas para o bot.

Um bot em um grupo ou canal deve fornecer informações relevantes e apropriadas para todos os membros. Embora seu bot certamente possa fornecer qualquer informação relevante para a experiência, lembre-se de que as conversas com ele são visíveis para todos. Portanto, um ótimo bot em um grupo ou canal deve agregar valor a todos os usuários e, certamente, não compartilhar inadvertidamente informações mais apropriadas para uma conversa individual.

O bot, tal como está, pode ser totalmente relevante em todos os âmbitos sem precisar de mais trabalho. No Teams, não existe nenhuma expectativa de que o bot funcione em todos os âmbitos, mas deve certificar-se de que o bot fornece valor de utilizador em qualquer âmbito que opte por suportar.

O desenvolvimento de um bot que funciona em grupos ou canais usa muito da mesma funcionalidade das conversas pessoais. Eventos e dados adicionais na carga útil fornecem informações de grupo e canal do Teams. Essas diferenças, bem como as principais diferenças na funcionalidade comum, são descritas nas seções a seguir.

Criando mensagens

Para obter mais informações sobre bots que criam mensagens em canais, consulte Mensagens proativas para bots e, especificamente, Criar uma conversação de canal.

Recebendo mensagens

Para um bot em um grupo ou canal, além do esquema de mensagem normal, seu bot também recebe as seguintes propriedades:

• channelData Consulte Dados do canal do Teams. Em um chat em grupo, contém informações específicas desse chat.
• conversation.id O ID da cadeia de resposta, consistindo no ID do canal mais o ID da primeira mensagem na cadeia de resposta.
• conversation.isGroup É true para mensagens de bot em canais ou chats em grupo.
• conversation.conversationType Ou groupChat ou channel.
• entities Pode conter uma ou mais menções. Para obter mais informações, consulte Menções.

Respondendo a mensagens

Para responder a uma mensagem existente, chame ReplyToActivity em .NET ou session.send em Node.js. O SDK do Bot Builder lida com todos os detalhes.

Se você optar por usar a API REST, também poderá chamar o ponto de extremidade /conversations/{conversationId}/activities/{activityId}.

Em um canal, responder a uma mensagem é exibido como uma resposta à cadeia de resposta inicial. O conversation.id contém o canal e o ID da mensagem de nível superior. Embora o Bot Framework cuide dos detalhes, você pode armazenar em cache esse conversation.id para futuras respostas a esse tópico de conversa, conforme necessário.

Prática recomendada: mensagens de boas-vindas no Teams

Quando o bot é adicionado pela primeira vez ao grupo ou equipa, é útil enviar uma mensagem de boas-vindas apresentando o bot a todos os utilizadores. A mensagem de boas-vindas deve fornecer uma descrição da funcionalidade do bot e dos benefícios do usuário. Idealmente, a mensagem também deve incluir comandos para o usuário interagir com o aplicativo. Para fazer isso, certifique-se de que seu bot responda à mensagem conversationUpdate, com o eventType teamsAddMembers no objeto channelData. Certifique-se de que o ID memberAdded seja o próprio ID do aplicativo do bot, pois o mesmo evento é enviado quando um usuário é adicionado a uma equipe. Para obter mais informações, consulte a adição de membro de equipa ou bot.

Você também pode enviar uma mensagem pessoal para cada membro da equipe quando o bot for adicionado. Para fazer isso, você pode buscar a lista da equipe e enviar a cada usuário uma mensagem direta.

Recomendamos que seu bot não envie uma mensagem de boas-vindas nas seguintes situações:

• A equipa é grande (obviamente subjetiva, por exemplo, mais de 100 membros). Seu bot pode ser visto como 'spam' e a pessoa que o adicionou pode receber reclamações, a menos que você comunique claramente a proposta de valor do seu bot a todos que virem a mensagem de boas-vindas.
• Seu bot é mencionado pela primeira vez em um grupo ou canal, em vez de ser adicionado pela primeira vez a uma equipe.
• Um grupo ou canal é renomeado.
• Um membro da equipe é adicionado a um grupo ou canal.

@ Menções

Uma vez que os bots num grupo ou canal só respondem quando são mencionados ("@botname") numa mensagem, todas as mensagens recebidas por um bot num canal de grupo contêm o seu próprio nome e tem de garantir que a análise de mensagens processa esse facto. Além disso, os bots podem analisar outros usuários mencionados e mencionar usuários como parte de suas mensagens.

Recuperando menções

As menções são retornadas no objeto entities conteúdo e contêm a ID exclusiva do usuário e, na maioria dos casos, o nome do usuário mencionado. Você pode recuperar todas as menções na mensagem chamando a função GetMentions no SDK do Bot Builder para .NET, que retorna uma matriz de Mentioned objetos.

Código de exemplo .NET: procurar e despojar @bot menção

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

Observação

Você também pode usar a função de extensão do Teams GetTextWithoutMentions, que remove todas as menções, incluindo o bot.

Node.js código de exemplo: procurar e despojar @bot menção

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();
}

Você também pode usar a função de extensão do Teams getTextWithoutMentions, que remove todas as menções, incluindo o bot.

Construindo menções

Seu bot pode mencionar outros usuários em mensagens postadas em canais. Para fazer isso, sua mensagem deve fazer o seguinte:

• Inclua <at>@username</at> no texto da mensagem.
• Inclua o objeto mention dentro da coleção de entidades.

Exemplo .NET

Este exemplo usa o pacote NuGet Microsoft.Bot.Connector.Teams.

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

Exemplo 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);

Exemplo: mensagem de saída com usuário 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"
}

Acessando o groupChat ou o escopo do canal

Seu bot pode fazer mais do que enviar e receber mensagens em grupos e equipes. Por exemplo, também pode obter a lista de membros, incluindo as respetivas informações de perfil, e a lista de canais. Para obter mais informações, consulte Obter contexto para seu bot do Microsoft Teams.

Confira também

Amostras do Bot Framework.