Canais e conversas de chat em grupo com um bot do Microsoft TeamsChannel and Group chat conversations with a Microsoft Teams bot

Importante

Este artigo é baseado no SDK da Estrutura de Bot v3.This article is based on the v3 Bot Framework SDK. Se você estiver procurando a documentação atual versão 4.6 ou posterior do SDK, consulte a seção de bots de conversação.If you are looking for current documentation version 4.6 or later of the SDK, see the conversational bots section.

O Microsoft Teams permite que os usuários tragam bots para seus canais ou conversas de chat em grupo.Microsoft Teams allows users to bring bots into their channel or group chat conversations. Ao adicionar um bot a uma equipe ou chat, todos os usuários da conversa podem tirar proveito da funcionalidade do bot logo na conversa.By adding a bot to a team or chat, all users of the conversation can take advantage of the bot functionality right in the conversation. Você também pode acessar a funcionalidade específica do Teams em seu bot, como consultar informações da equipe e @mentioning usuários.You can also access Teams-specific functionality within your bot like querying team information and @mentioning users.

O chat em canais e chats de grupo difere do chat pessoal, já que o usuário precisa @mention o bot.Chat in channels and group chats differ from personal chat in that the user needs to @mention the bot. Se um bot for usado em vários escopos (pessoal, groupchat ou canal), você precisará detectar de que escopo as mensagens bot vieram e processá-las de acordo.If a bot is used in multiple scopes (personal, groupchat or channel) you will need to detect what scope the bot messages came from, and process them accordingly.

Criar um ótimo bot para canais ou gruposDesigning a great bot for channels or groups

Os bots adicionados a uma equipe se tornam outro membro da equipe e podem ser @mentioned como parte da conversa.Bots added to a team become another team member and can be @mentioned as part of the conversation. Na verdade, os bots só recebem mensagens quando @mentioned, portanto, outras conversas no canal não são enviadas para o bot.In fact, bots only receive messages when they are @mentioned, so other conversations on the channel are not sent to the bot.

Um bot em um grupo ou canal deve fornecer informações relevantes e apropriadas para todos os membros.A bot in a group or channel should provide information relevant and appropriate for all members. Embora o bot certamente possa fornecer informações relevantes para a experiência, tenha em mente que as conversas com ele são visíveis para todos.While your bot can certainly provide any information relevant to the experience, keep in mind conversations with it are visible to everyone. Portanto, um ótimo bot em um grupo ou canal deve adicionar valor a todos os usuários e, certamente, não compartilhar inadvertidamente informações mais apropriadas a uma conversa um para um.Therefore, a great bot in a group or channel should add value to all users, and certainly not inadvertently share information more appropriate to a one-to-one conversation.

Seu bot, assim como está, pode ser totalmente relevante em todos os escopos sem exigir trabalho adicional.Your bot, just as it is, may be entirely relevant in all scopes without requiring additional work. No Microsoft Teams, não há expectativa de que seu bot funcione em todos os escopos, mas você deve garantir que o bot fornece valor ao usuário em qualquer escopo que você escolher dar suporte.In Microsoft Teams there is no expectation that your bot function in all scopes, but you should ensure that your bot provides user value in whichever scope(s) you choose to support. Para obter mais informações sobre escopos, consulte Apps in Microsoft Teams.For more information on scopes, see Apps in Microsoft Teams.

O desenvolvimento de um bot que funciona em grupos ou canais usa grande parte da mesma funcionalidade que conversas pessoais.Developing a bot that works in groups or channels uses much of the same functionality as personal conversations. Eventos e dados adicionais na carga fornecem informações de grupo e canal do Teams.Additional events and data in the payload provide Teams group and channel information. Essas diferenças, bem como as principais diferenças na funcionalidade comum são descritas nas seções a seguir.Those differences, as well as key differences in common functionality are described in the following sections.

Criando mensagensCreating messages

Para obter mais informações sobre bots que criam mensagens em canais, consulte Mensagens proativaspara bots e, especificamente, Criando uma conversa de canal.For more information on bots creating messages in channels see Proactive messaging for bots, and specifically Creating a channel conversation.

Recebimento de mensagensReceiving messages

Para um bot em um grupo ou canal, além do esquema de mensagens regular,o bot também recebe as seguintes propriedades:For a bot in a group or channel, in addition to the regular message schema, your bot also receives the following properties:

  • channelData Consulte Dados do canal do Teams.channelData See Teams channel data. Em um chat em grupo, contém informações específicas para esse chat.In a group chat, contains information specific to that chat.
  • conversation.id A ID da cadeia de resposta, que consiste na ID do canal mais a ID da primeira mensagem na cadeia de respostaconversation.id The reply chain ID, consisting of channel ID plus the ID of the first message in the reply chain
  • conversation.isGroup É true para mensagens bot em canais ou chats de grupoconversation.isGroup Is true for bot messages in channels or group chats
  • conversation.conversationTypeOu groupChat``channelconversation.conversationType Either groupChat or channel
  • entities Pode conter uma ou mais menções (consulte Menções)entities Can contain one or more mentions (see Mentions)

Responder a mensagensReplying to messages

Para responder a uma mensagem existente, chame ReplyToActivity o .NET ou session.send Node.js.To reply to an existing message, call ReplyToActivity in .NET or session.send in Node.js. O SDK do Construtor de Bots lida com todos os detalhes.The Bot Builder SDK handles all the details.

Se você optar por usar a API REST, também poderá chamar o /conversations/{conversationId}/activities/{activityId} ponto de extremidade.If you choose to use the REST API, you can also call the /conversations/{conversationId}/activities/{activityId} endpoint.

Em um canal, responder a uma mensagem mostra como uma resposta à cadeia de resposta de inicialização.In a channel, replying to a message shows as a reply to the initiating reply chain. O conversation.id contém o canal e a ID da mensagem de nível superior.The conversation.id contains the channel and the top level message ID. Embora a Estrutura de Bots cuide dos detalhes, você pode armazenar em cache isso para respostas futuras a conversation.id esse thread de conversa, conforme necessário.Although the Bot Framework takes care of the details, you can cache that conversation.id for future replies to that conversation thread as needed.

Prática prática: mensagens de boas-vindas no TeamsBest practice: Welcome messages in Teams

Quando o bot é adicionado pela primeira vez ao grupo ou à equipe, geralmente é útil enviar uma mensagem de boas-vindas apresentando o bot para todos os usuários.When your bot is first added to the group or team, it is generally useful to send a welcome message introducing the bot to all users. A mensagem de boas-vindas deve fornecer uma descrição da funcionalidade e dos benefícios do usuário do bot.The welcome message should provide a description of the bot’s functionality and user benefits. O ideal é que a mensagem também inclua comandos para o usuário interagir com o aplicativo.Ideally the message should also include commands for the user to interact with the app. Para fazer isso, verifique se o bot responde à conversationUpdate mensagem, com teamsAddMembers o eventType no channelData objeto.To do this, ensure that your bot responds to the conversationUpdate message, with the teamsAddMembers eventType in the channelData object. Certifique-se de que a ID seja a própria ID do aplicativo do bot, pois o mesmo evento é enviado quando um usuário é memberAdded adicionado a uma equipe.Be sure that the memberAdded ID is the bot's App ID itself, because the same event is sent when a user is added to a team. Consulte Membro da equipe ou adição de bot para obter mais detalhes.See Team member or bot addition for more details.

Você também pode querer enviar uma mensagem pessoal para cada membro da equipe quando o bot for adicionado.You might also want to send a personal message to each member of the team when the bot is added. Para fazer isso, você pode buscar a lista de equipe e enviar a cada usuário uma mensagem direta.To do this, you could fetch the team roster and send each user a direct message.

Recomendamos que seu bot não envie uma mensagem de boas-vindas nas seguintes situações:We recommend that your bot not send a welcome message in the following situations:

  • A equipe é grande (obviamente subjetivo, mas, por exemplo, maior do que 100 membros).The team is large (obviously subjective, but for example larger than 100 members). Seu bot pode ser visto como "spammy" e a pessoa que o adicionou pode receber reclamações, a menos que você comunique claramente a proposta de valor do bot para todos que veem a mensagem de boas-vindas.Your bot may be seen as 'spammy' and the person who added it may get complaints unless you clearly communicate your bot's value proposition to everyone who sees the welcome message.
  • Seu bot é mencionado pela primeira vez em um grupo ou canal (em vez de ser adicionado pela primeira vez a uma equipe)Your bot is first mentioned in a group or channel (versus being first added to a team)
  • Um grupo ou canal é renomeadoA group or channel is renamed
  • Um membro da equipe é adicionado a um grupo ou canalA team member is added to a group or channel

@ Menções@ Mentions

Como os bots em um grupo ou canal respondem somente quando eles são mencionados ("@botname") em uma mensagem, cada mensagem recebida por um bot em um canal de grupo contém seu próprio nome e você deve garantir que a análise da mensagem lida com isso.Because bots in a group or channel respond only when they are mentioned ("@botname") in a message, every message received by a bot in a group channel contains its own name, and you must ensure your message parsing handles that. Além disso, os bots podem analisar outros usuários mencionados e mencionar usuários como parte de suas mensagens.In addition, bots can parse out other users mentioned and mention users as part of their messages.

Recuperando mençõesRetrieving mentions

As menções são retornadas no objeto em carga e contêm a ID exclusiva do usuário e, na maioria dos casos, o entities nome do usuário mencionado.Mentions are returned in the entities object in payload and contain both the unique ID of the user and, in most cases, the name of user mentioned. Você pode recuperar todas as menções na mensagem chamando a função no SDK do Construtor de Bots para .NET, que retorna uma GetMentions matriz de Mentioned objetos.You can retrieve all mentions in the message by calling the GetMentions function in the Bot Builder SDK for .NET, which returns an array of Mentioned objects.

Código de exemplo do .NET: verifique e @bot menção.NET example code: Check for and strip @bot mention

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 , que retira todas GetTextWithoutMentions as menções, incluindo o bot.You can also use the Teams extension function GetTextWithoutMentions, which strips out all mentions, including the bot.

Node.js código de exemplo: verifique e @bot mençãoNode.js example code: Check for and strip @bot mention

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 , que retira todas getTextWithoutMentions as menções, incluindo o bot.You can also use the Teams extension function getTextWithoutMentions, which strips out all mentions, including the bot.

Criar mençõesConstructing mentions

Seu bot pode mencionar outros usuários em mensagens postadas em canais.Your bot can mention other users in messages posted into channels. Para fazer isso, sua mensagem deve fazer o seguinte:To do this, your message must do the following:

  • Incluir <at>@username</at> no texto da mensagemInclude <at>@username</at> in the message text
  • Incluir o mention objeto dentro da coleção entitiesInclude the mention object inside the entities collection

Exemplo do .NET.NET example

Este exemplo usa o pacote NuGet Microsoft.Bot.Connector.Teams.This example uses the Microsoft.Bot.Connector.Teams NuGet package.

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

Node.js exemploNode.js example

// 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 o usuário mencionadoExample: Outgoing message with user mentioned

{
    "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 groupChat ou escopo de canalAccessing groupChat or channel scope

Seu bot pode fazer mais do que enviar e receber mensagens em grupos e equipes.Your bot can do more than send and receive messages in groups and teams. Por exemplo, ele também pode buscar a lista de membros, incluindo suas informações de perfil, bem como a lista de canais.For instance, it can also fetch the list of members, including their profile information, as well as the list of channels. Confira Obter contexto para que seu bot do Microsoft Teams saiba mais.See Get context for your Microsoft Teams bot to learn more.

Consulte também Exemplos da Estrutura de Bot.See also Bot Framework samples.