Ter uma conversa com um bot do Microsoft TeamsHave a conversation with a Microsoft Teams bot

Importante

Os artigos desta seção são baseados no SDK do v3 bot Framework.The articles in this section are 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 bots de conversa .If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

Uma conversa é uma série de mensagens enviadas entre o bot e um ou mais usuários.A conversation is a series of messages sent between your bot and one or more users. Há três tipos de conversas (também chamadas de escopos) no Teams:There are three kinds of conversations (also called scopes) in Teams:

  • teamsTambém chamado de conversações de canal, visíveis para todos os membros do canal.teams Also called channel conversations, visible to all members of the channel.
  • personalConversas entre bots e um único usuário.personal Conversations between bots and a single user.
  • groupChatConverse entre um bot e dois ou mais usuários.groupChat Chat between a bot and two or more users.

Um bot se comporta de forma ligeiramente diferente dependendo do tipo de conversa envolvido em:A bot behaves slightly differently depending on what kind of conversation it is involved in:

Para que o bot funcione em um escopo específico, ele deve ser listado como suporte a esse escopo no manifesto.In order for the bot to work in a particular scope it should be listed as supporting that scope in the manifest. Os escopos são definidos e abordados mais detalhadamente na referência do manifesto.Scopes are defined and discussed further in the Manifest Reference.

Mensagens proativasProactive messages

Os bots podem participar de uma conversa ou iniciar um.Bots can participate in a conversation or initiate one. A maior parte da comunicação é de resposta a outra mensagem.Most communication is in response to another message. Se um bot iniciar uma conversa, ele será chamado de uma mensagem proativa.If a bot initiates a conversation it is called a proactive message. Exemplos incluem:Examples include:

  • Mensagens de boas-vindasWelcome messages
  • Notificações de eventosEvent notifications
  • Mensagens de sondagemPolling messages

Noções básicas sobre conversasConversation basics

Cada mensagem é um Activity objeto do tipo messageType: message .Each message is an Activity object of type messageType: message. Quando um usuário envia uma mensagem, o Teams posta a mensagem no bot; especificamente, ele envia um objeto JSON para o ponto de extremidade de mensagem de seu bot.When a user sends a message, Teams posts the message to your bot; specifically, it sends a JSON object to your bot's messaging endpoint. O bot examina a mensagem para determinar seu tipo e responde de acordo.Your bot examines the message to determine its type and responds accordingly.

Os bots também suportam mensagens no estilo de eventos.Bots also support event-style messages. Consulte manipular eventos de bot no Microsoft Teams para obter mais detalhes.See Handle bot events in Microsoft Teams for more details. A fala não é suportada no momento.Speech is currently not supported.

As mensagens são para a maior parte do mesmo em todos os escopos, mas há diferenças em como o bot é acessado na interface do usuário e as diferenças por trás dos bastidores que você precisa saber.Messages are for the most part the same in across all scopes, but there are differences in how the bot is accessed in the UI and differences behind the scenes which you will need to know about.

A conversa básica é manipulada por meio do conector da estrutura de bot, uma única API REST para permitir que seu bot se comunique com o Teams e outros canais.Basic conversation is handled through the Bot Framework Connector, a single REST API to enable your bot to communicate with Teams and other channels. O SDK do bot Builder fornece acesso fácil a essa API, funcionalidade adicional para gerenciar o fluxo e o estado da conversa e maneiras simples de incorporar serviços cognitivas, como o processamento de idioma natural (NLP).The Bot Builder SDK provides easy access to this API, additional functionality to manage conversation flow and state, and simple ways to incorporate cognitive services such as natural language processing (NLP).

Conteúdo da mensagemMessage content

Seu bot pode enviar Rich Text, imagens e cartões.Your bot can send rich text, pictures, and cards. Os usuários podem enviar Rich Text e imagens para o bot.Users can send rich text and pictures to your bot. Você pode especificar o tipo de conteúdo que seu bot pode lidar na página de configurações do Microsoft Teams para seu bot.You can specify the type of content your bot can handle in the Microsoft Teams settings page for your bot.

FormatarFormat De usuário para botFrom user to bot De bot para usuárioFrom bot to user ObservaçõesNotes
Rich text Rich text
ImagensPictures Máximo de 1024 × 1024 e 1 MB no formato PNG, JPEG ou GIF; GIF animado não é suportadoMaximum 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF are not supported
CartõesCards Consulte a referência de cartões de equipe para cartões suportadosSee the Teams Card Reference for supported cards
EmojisEmojis No momento, o Microsoft Teams oferece suporte a emojis via UTF-16 (como U + 1F600 para Grinning face)Teams currently supports emojis via UTF-16 (such as U+1F600 for grinning face)

Para obter mais informações sobre os tipos de interação de bot suportados pela estrutura de bot (em que bots no Teams são baseados em), consulte a documentação da estrutura de bot sobre o fluxo de conversa e conceitos relacionados na documentação do SDK do bot Builder para .net e o sdk do bot Builder para Node.js.For more information on the types of bot interaction supported by the Bot Framework (which bots in teams are based on), see the Bot Framework documentation on conversation flow and related concepts in the documentation for the Bot Builder SDK for .NET and the Bot Builder SDK for Node.js.

Formatação de mensagemMessage formatting

Você pode definir a TextFormat propriedade opcional de um message para controlar como o conteúdo de texto da mensagem é renderizado.You can set the optional TextFormat property of a message to control how your message's text content is rendered. Veja formatação da mensagem para obter uma descrição detalhada da formatação suportada nas mensagens de bot.See Message formatting for a detailed description of supported formatting in bot messages. Você pode definir a TextFormat propriedade opcional para controlar como o conteúdo de texto da mensagem é renderizado.You can set the optional TextFormat property to control how your message's text content is rendered.

Para obter informações detalhadas sobre como o Microsoft Teams dá suporte à formatação de texto no Teams, consulte Text Formatting in bot messages.For detailed information on how Teams supports text formatting in teams see Text formatting in bot messages.

Para obter informações sobre como formatar cartões em mensagens, consulte formatação de cartão.For information on formatting cards in messages, see Card formatting.

Mensagens de imagemPicture messages

As imagens são enviadas adicionando anexos a uma mensagem.Pictures are sent by adding attachments to a message. Você pode encontrar mais informações sobre anexos na documentação da estrutura do bot.You can find more information on attachments in the Bot Framework documentation.

As imagens podem ser no máximo 1024 × 1024 e 1 MB no formato PNG, JPEG ou GIF; GIF animado não é suportado.Pictures can be at most 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF is not supported.

Recomendamos que você especifique a altura e a largura de cada imagem usando XML.We recommend that you specify the height and width of each image by using XML. Se você usar redução, o tamanho da imagem padrão será 256 × 256.If you use Markdown, the image size defaults to 256×256. Por exemplo:For example:

  • Use<img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>Use <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
  • Não use![Duck on a rock](http://aka.ms/Fo983c)Don't use ![Duck on a rock](http://aka.ms/Fo983c)

Receber mensagensReceiving messages

Dependendo de quais escopos são declarados, seu bot pode receber mensagens nos seguintes contextos:Depending on which scopes are declared, your bot can receive messages in the following contexts:

  • chat pessoal Os usuários podem interagir em uma conversa privada com um bot simplesmente selecionando o bot adicionado no histórico do chat, ou digitando seu nome ou ID de aplicativo na caixa para: em um novo chat.personal chat Users can interact in a private conversation with a bot by simply selecting the added bot in the chat history, or typing its name or app ID in the To: box on a new chat.
  • Canais Um bot pode ser mencionado ("@botname") em um canal se ele tiver sido adicionado à equipe.Channels A bot can be mentioned ("@botname") in a channel if it has been added to the team. Observe que as respostas adicionais para um bot em um canal exigem que o bot seja mencionado.Note that additional replies to a bot in a channel require mentioning the bot. Ele não responderá às respostas onde não for mencionado.It will not respond to replies where it is not mentioned.

Para mensagens de entrada, seu bot recebe um Activity objeto do tipo messageType: message .For incoming messages, your bot receives an Activity object of type messageType: message. Embora o Activity objeto possa conter outros tipos de informações, como as atualizações de canal enviadas ao bot, o message tipo representa a comunicação entre o bot e o usuário.Although the Activity object can contain other types of information, like channel updates sent to your bot, the message type represents communication between bot and user.

O bot recebe uma carga que contém a mensagem do usuário, Text bem como outras informações sobre o usuário, a fonte da mensagem e as informações sobre o Teams.Your bot receives a payload that contains the user message Text as well as other information about the user, the source of the message, and Teams information. Observação:Of note:

  • timestampA data e a hora da mensagem no UTC (tempo Universal Coordenado)timestamp The date and time of the message in Coordinated Universal Time (UTC)
  • localTimestampA data e a hora da mensagem no fuso horário do remetentelocalTimestamp The date and time of the message in the time zone of the sender
  • channelIdSempre "msteams".channelId Always "msteams". Isso se refere a um canal de estrutura de bot, não a um canal de equipe.This refers to a bot framework channel, not a teams channel.
  • from.idUma ID exclusiva e criptografada para o usuário para o bot; adequado como uma chave se seu aplicativo precisa armazenar dados do usuário.from.id A unique and encrypted ID for that user for your bot; suitable as a key if your app needs to store user data. É exclusivo para o bot e não pode ser usado diretamente fora da instância de bot de forma significativa para identificar esse usuárioIt is unique for your bot and cannot be directly used outside your bot instance in any meaningful way to identify that user
  • channelData.tenant.idA ID do locatário do usuário.channelData.tenant.id The tenant ID for the user.

Observação

from.idé exclusivo para o bot e não pode ser usado diretamente fora da instância de bot de forma significativa para identificar o usuário.from.id is unique for your bot and cannot be directly used outside your bot instance in any meaningful way to identify that user.

Combinar interações privadas e de canal com seu botCombining channel and private interactions with your bot

Ao interagir em um canal, seu bot deve ser inteligente sobre como fazer determinadas conversas offline com um usuário.When interacting in a channel, your bot should be smart about taking certain conversations offline with a user. Por exemplo, suponha que um usuário esteja tentando coordenar uma tarefa complexa, como o agendamento com um conjunto de membros da equipe.For instance, suppose a user is trying to coordinate a complex task, such as scheduling with a set of team members. Em vez de ter toda a sequência de interações visíveis para o canal, considere enviar uma mensagem de chat pessoal para o usuário.Rather than have the entire sequence of interactions visible to the channel, consider sending a personal chat message to the user. O bot deve ser capaz de fazer a transição fácil do usuário entre conversas pessoais e de canal sem perder o estado.Your bot should be able to easily transition the user between personal and channel conversations without losing state.

Observação

Não se esqueça de atualizar o canal quando a interação estiver concluída para notificar os outros membros da equipe.Don’t forget to update the channel when the interaction is complete to notify the other team members.

Exemplo de esquema de entrada completoFull inbound schema example

{
    "type": "message",
    "id": "1485983408511",
    "timestamp": "2017-02-01T21:10:07.437Z",
    "localTimestamp": "2017-02-01T14:10:07.437-07:00",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "channelId": "msteams",
    "from": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB39ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen",
        "aadObjectId": "7faf8ab2-3d56-4244-b585-20c8a42ed2b8"
    },
    "conversation": {
        "conversationType": "personal",
        "id": "a:17I0kl9EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-"
    },
    "recipient": {
        "id": "28:c9e8c047-2a74-40a2-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "textFormat": "plain",
    "text": "Hello Teams TestBot",
    "entities": [
      { 
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo"
      }
    ],
    "channelData": {
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "locale": "en-US"
}

Observação

O campo de texto para mensagens de entrada às vezes contém menção.The text field for inbound messages sometimes contains mentions. Certifique-se de verificar corretamente e stripá-las.Be sure to properly check and strip those. Para obter mais informações, consulte menciona.For more information, see Mentions.

Dados de canal do teamsTeams channel data

O channelData objeto contém informações específicas de equipes e é a fonte definitiva para IDs de canal e equipe.The channelData object contains Teams-specific information and is the definitive source for team and channel IDs. Você deve armazenar em cache e usar essas IDs como chaves para armazenamento local.You should cache and use these ids as keys for local storage.

O channelData objeto não está incluído nas mensagens em conversas pessoais, pois elas ocorrem fora de qualquer canal.The channelData object is not included in messages in personal conversations since these take place outside of any channel.

Um objeto channelData típico em uma atividade enviada ao seu bot contém as seguintes informações:A typical channelData object in an activity sent to your bot contains the following information:

  • eventTypeTipo de evento Teams; aprovado apenas em casos de eventos de modificação de canaleventType Teams event type; passed only in cases of channel modification events
  • tenant.idID de locatário do Azure Active Directory; aprovado em todos os contextostenant.id Azure Active Directory tenant ID; passed in all contexts
  • teamAprovado apenas em contextos de canal, não no chat pessoal.team Passed only in channel contexts, not in personal chat.
  • channelÉ passado apenas em contextos de canal quando o bot é mencionado ou para eventos em canais no Teams onde o bot foi adicionadochannel Passed only in channel contexts when the bot is mentioned or for events in channels in teams where the bot has been added
  • channelData.teamsTeamIdPreterido.channelData.teamsTeamId Deprecated. Essa propriedade é incluída apenas para compatibilidade com versões anteriores.This property is included only for backwards compatibility.
  • channelData.teamsChannelIdPreterido.channelData.teamsChannelId Deprecated. Essa propriedade é incluída apenas para compatibilidade com versões anteriores.This property is included only for backwards compatibility.

Exemplo do objeto channelData (evento channelCreated)Example channelData object (channelCreated event)

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

Exemplo .NET.NET example

O pacote Microsoft. bot. Connector. Teams NuGet fornece um TeamsChannelData objeto especializado, que expõe as propriedades para acessar informações específicas do teams.The Microsoft.Bot.Connector.Teams NuGet package provides a specialized TeamsChannelData object, which exposes properties to access Teams-specific information.

TeamsChannelData channelData = activity.GetChannelData<TeamsChannelData>();
string tenantId = channelData.Tenant.Id;

Enviando respostas a mensagensSending replies to messages

Para responder a uma mensagem existente, chame ReplyToActivity no .net ou session.send em Node.js.To reply to an existing message, call ReplyToActivity in .NET or session.send in Node.js. O SDK do bot Builder trata de todos os detalhes.The Bot Builder SDK handles all the details.

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

O próprio conteúdo da mensagem pode conter texto simples ou alguns cartões e ações de cartãofornecidos pela estrutura de bot.The message content itself can contain simple text or some of the Bot Framework supplied cards and card actions.

Observe que, no seu esquema de saída, você sempre deve usar o mesmo serviceUrl que o recebido.Please note that in your outbound schema you should always use the same serviceUrl as the one you received. Lembre-se de que o valor de serviceUrl tende a ser estável, mas pode ser alterado.Be aware that the value of serviceUrl tends to be stable but can change. Quando uma nova mensagem chega, seu bot deve verificar seu valor armazenado de serviceUrl .When a new message arrives, your bot should verify its stored value of serviceUrl.

Atualizando mensagensUpdating messages

Em vez de as mensagens serem instantâneos de dados estáticos, seu bot pode atualizar dinamicamente as mensagens embutidas após enviá-las.Rather than have your messages be static snapshots of data, your bot can dynamically update messages inline after sending them. Você pode usar atualizações de mensagens dinâmicas para cenários como atualizações de pesquisa, modificação de ações disponíveis após um pressionamento de botão ou qualquer outra alteração de estado assíncrono.You can use dynamic message updates for scenarios such as poll updates, modifying available actions after a button press, or any other asynchronous state change.

A nova mensagem não precisa coincidir com o original no tipo.The new message need not match the original in type. Por exemplo, se a mensagem original contiver um anexo, a nova mensagem poderá ser uma mensagem de texto simples.For instance, if the original message contained an attachment, the new message can be a simple text message.

Observação

Você pode atualizar somente o conteúdo enviado em mensagens de anexo único e layouts de carrossel.You can update only content sent in single-attachment messages and carousel layouts. Não há suporte para o lançamento de atualizações em mensagens com vários anexos no layout de lista.Posting updates to messages with multiple attachments in list layout is not supported.

API RESTREST API

Para emitir uma atualização de mensagem, basta executar uma solicitação PUT no /v3/conversations/<conversationId>/activities/<activityId>/ ponto de extremidade usando uma determinada ID de atividade.To issue a message update, simply perform a PUT request against the /v3/conversations/<conversationId>/activities/<activityId>/ endpoint using a given activity ID. Para concluir esse cenário, você deve armazenar em cache a ID da atividade retornada pela chamada POST original.To complete this scenario, you should cache the activity ID returned by the original POST call.

PUT /v3/conversations/19%3Aja0cu120i1jod12j%40skype.net/activities/012ujdo0128
{
    "type": "message",
    "text": "This message has been updated"
}

Exemplo .NET.NET example

Você pode usar o UpdateActivityAsync método no SDK do bot Builder para atualizar uma mensagem existente.You can use the UpdateActivityAsync method in the Bot Builder SDK to update an existing message.

public async Task<HttpResponseMessage> Post([FromBody]Activity activity)
{
  if (activity.Type == ActivityTypes.Message)
  {
    ConnectorClient connector = new ConnectorClient(new Uri(activity.ServiceUrl));
    Activity reply = activity.CreateReply($"You sent {activity.Text} which was {activity.Text.Length} characters");
    var msgToUpdate = await connector.Conversations.ReplyToActivityAsync(reply);
    Activity updatedReply = activity.CreateReply($"This is an updated message");
    await connector.Conversations.UpdateActivityAsync(reply.Conversation.Id, msgToUpdate.Id, updatedReply);
  }
}

Exemplo de Node.jsNode.js example

Você pode usar o session.connector.update método no SDK do bot Builder para atualizar uma mensagem existente.You can use the session.connector.update method in the Bot Builder SDK to update an existing message.

function sendCardUpdate(bot, session, originalMessage, address) {

  var origAttachment = originalMessage.data.attachments[0];
  origAttachment.content.subtitle = 'Assigned to Larry Jin';

  var updatedMsg = new builder.Message()
    .address(address)
    .textFormat(builder.TextFormat.markdown)
    .addAttachment(origAttachment)
    .toMessage();

  session.connector.update(updatedMsg, function(err, addresses) {
    if (err) {
      console.log(`Could not update the message`);
    }
  });
}

Iniciar uma conversa (mensagens pró-ativas)Starting a conversation (proactive messaging)

Você pode criar uma conversa pessoal com um usuário ou iniciar uma nova cadeia de resposta em um canal para o bot da equipe.You can create a personal conversation with a user or start a new reply chain in a channel for your team bot. Isso permite que você envie mensagens para o usuário ou usuários sem que eles iniciem o contato pela primeira vez com o bot.This lets you to message your user or users without having them first initiate contact with your bot. Para mais informações, confira os seguintes tópicos:For more information, see the following topics:

Consulte Proactive Messaging for bots para obter informações mais gerais sobre conversas iniciadas por bots.See Proactive messaging for bots for more general information on conversations started by bots.

Excluir mensagensDeleting messages

As mensagens podem ser excluídas usando o método Connectors delete() no SDK do BotBuilder.Messages can be deleted using the connectors delete() method in the BotBuilder SDK.

bot.dialog('BotDeleteMessage', function (session: builder.Session) {
  var msg = new teams.TeamsMessage(session).text("Bot will delete this message in 5 sec.")
  bot.send(msg, function (err, response) {
    if (err) {
      console.log(err);
      session.endDialog();
    }

    console.log('Proactive message response:');
    console.log(response);
    console.log('---------------------------------------------------')
    setTimeout(function () {
      var activityId: string = null;
      var messageAddress: builder.IChatConnectorAddress = null;
      if (response[0]){
        messageAddress = response[0];
        activityId = messageAddress.id;
      }

      if (activityId == null)
      {
        console.log('Message failed to send.');
        session.endDialog();
        return;
      }

      // Bot delete message
      let address: builder.IChatConnectorAddress  = {
        channelId: 'msteams',
        user: messageAddress.user,
        bot: messageAddress.bot,
        id : activityId,
        serviceUrl : (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
        conversation: {
          id: session.message.address.conversation.id
        }
      };

      connector.delete(address, function (err) {
        if (err)
        {
          console.log(err);
        }
        else
        {
          console.log("Message: " + activityId + " deleted successfully.");
        }

        // Try editing deleted message would fail
        var newMsg = new builder.Message().address(address).text("To edit message.");
        connector.update(newMsg.toMessage(), function (err, address) {
          if (err)
          {
            console.log(err);
            console.log('Deleted message can not be edited.');
          }
          else
          {
            console.log("There is something wrong. Message: " + activityId + " edited successfully.");
            console.log(address);
          }

          session.endDialog();
        });
      });
    }, 5000);
  });
})