Conversar com um bot do Microsoft Teams

Uma conversa é uma série de mensagens enviadas entre o bot e um ou mais usuários. Existem três tipos de conversas (também chamadas de escopos) no Teams:

• teams Também chamadas de conversas de canal, visíveis para todos os membros do canal.
• personal Conversas entre bots e um único usuário.
• groupChatChat entre um bot e dois ou mais usuários.

Um bot se comporta de maneira ligeiramente diferente dependendo do tipo de conversa em que está envolvido:

• Os bots em conversas de canal e chat em grupo exigem que o usuário @mention do bot o invoque em um canal.
• Os bots em conversas de usuário único não exigem um @mention - o usuário pode simplesmente digitar.

Para que o bot funcione em um escopo específico, ele deve ser listado como compatível com esse escopo no manifesto. Os escopos são definidos e discutidos mais adiante na Referência de manifesto.

Mensagens proativas

Os bots podem participar de uma conversa ou iniciar uma. A maior parte da comunicação é em resposta a outra mensagem. Se um bot iniciar uma conversa, ela será chamada de mensagem proativa. Os exemplos são:

• Mensagens de boas-vindas
• Notificações de eventos
• Sondagem de mensagens

Noções básicas de conversas

Cada mensagem é um Activity objeto do tipo messageType: message. Quando um usuário envia uma mensagem, o Teams posta a mensagem no seu bot; especificamente, ele envia um objeto JSON para o ponto de extremidade de mensagens do bot. O bot examina a mensagem para determinar seu tipo e responde de acordo.

Os bots também dão suporte a mensagens no estilo de evento. Para obter mais informações, consulte Manipular eventos de bot no Microsoft Teams. Não há suporte para a fala.

As mensagens geralmente são as mesmas em todos os escopos, mas há diferenças em como o bot é acessado na interface do usuário e diferenças nos bastidores, que você precisa conhecer.

A conversa básica é tratada por meio do Bot Framework Connector, uma única API REST para permitir que seu bot se comunique com o Teams e outros canais. 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 cognitivos, como processamento de linguagem natural (NLP).

Conteúdo da mensagem

Seu bot pode enviar rich text, imagens e cartões. Os usuários podem enviar rich text e imagens para o bot. Você pode especificar o tipo de conteúdo que o bot pode manipular na página de configurações do Microsoft Teams.

Para obter mais informações sobre os tipos de interação de bot compatíveis com o Bot Framework, nos quais os bots do Teams se baseiam, consulte a documentação do Bot Framework sobre fluxo de conversa e conceitos relacionados na documentação do SDK do Bot Builder para .NET e do SDK do Bot Builder para Node.js.

Formatação da mensagem

Você pode definir a propriedade opcional TextFormat de a message para controlar como o conteúdo de texto da sua mensagem é renderizado. Consulte Formatação de mensagem para obter uma descrição detalhada da formatação com suporte em mensagens de bot. Você pode definir a propriedade optional TextFormat para controlar como o conteúdo de texto da mensagem é renderizado.

Para obter informações detalhadas sobre como o Teams dá suporte à formatação de texto no Teams, consulte Formatação de texto em mensagens de bot.

Para obter mais informações sobre a formatação de cartões em mensagens, consulte Formatação de cartões.

Mensagens com imagem

As imagens são enviadas adicionando anexos a uma mensagem. Você pode encontrar mais informações sobre anexos na documentação do Bot Framework.

As imagens podem ter no máximo 1024×1024 MB e 1 MB no formato PNG, JPEG ou GIF; Não há suporte para GIF animado.

Recomendamos que você especifique a altura e a largura de cada imagem usando XML. Se você usar Markdown, o tamanho da imagem será padrão para 256×256. Por exemplo:

• Utilização <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)

Recebendo mensagens

Dependendo de quais escopos são declarados, o bot pode receber mensagens nos seguintes contextos:

• Bate-papo pessoal Os usuários podem interagir em uma conversa privada com um bot selecionando o bot adicionado no histórico do chat ou digitando seu nome ou ID do aplicativo na caixa Para: em um novo chat.
• Canais Um bot pode ser mencionado ("@botname") em um canal se ele tiver sido adicionado à equipe. Observe que as respostas adicionais a um bot em um canal exigem mencionar o bot. Ele não responderá às respostas quando não for mencionado.

Para mensagens de entrada, seu bot recebe um objeto Activity do tipo messageType: message. Embora o Activity objeto possa conter outros tipos de informações, como atualizações de canal enviadas ao bot, o tipo representa a comunicação entre o bot e o message usuário.

Seu bot recebe uma carga que contém a mensagem Text do usuário e outras informações sobre o usuário, a origem da mensagem e as informações do Teams. Digno de nota:

• timestamp A data e a hora da mensagem em UTC (Tempo Universal Coordenado).
• localTimestamp A data e a hora da mensagem no fuso horário do remetente.
• channelId Sempre "msteams". Isso se refere a um canal do Bot Framework, não a um canal do Teams.
• from.id Uma ID exclusiva e criptografada para esse usuário para seu bot; adequado como uma chave se o aplicativo precisar armazenar dados do usuário. É exclusivo para seu bot e não pode ser usado diretamente fora da instância do bot de nenhuma maneira significativa para identificar esse usuário.
• channelData.tenant.id A ID de locatário do usuário.

Combinando interações de canal e privadas com seu bot

Ao interagir em um canal, o bot deve ser inteligente ao colocar certas conversas offline com um usuário. Por exemplo, suponha que um usuário esteja tentando coordenar uma tarefa complexa, como agendar com um conjunto de membros da equipe. 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. Seu bot deve ser capaz de fazer a transição facilmente do usuário entre conversas pessoais e de canal sem perder o estado.

Exemplo de esquema de entrada completa

{
    "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"
}

Dados do canal do Teams

O channelData objeto contém informações específicas do Teams e é a origem definitiva dos IDs de equipa e de canal. Deve colocar estes IDs em cache e utilizá-los como chaves para o armazenamento local.

Um objeto channelData típico em uma atividade enviada ao seu bot contém as seguintes informações:

• eventType Tipo de evento do Teams; Aprovado apenas em casos de eventos de modificação de canal.
• tenant.idMicrosoft Entra ID de inquilino; transmitido em todos os contextos.
• team Transmitido apenas em contextos de canal e não em chats pessoais.
  • id GUID do canal.
  • name Nome da equipa; aprovado apenas em casos de eventos de mudança de nome da equipe.
• channel Transmitido apenas em contextos de canal quando o bot é mencionado ou para eventos em canais em equipas onde o bot foi adicionado.
  • id GUID do canal.
  • name Nome do canal; Aprovado apenas em casos de eventos de modificação de canal.
• channelData.teamsTeamId Preterido. Esta propriedade só é incluída para retrocompatibilidade.
• channelData.teamsChannelId Preterido. Esta propriedade só é incluída para retrocompatibilidade.

Exemplo de objeto channelData (evento channelCreated)

"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 do .NET

O pacote NuGet Microsoft.Bot.Connector.Teams fornece um objeto especializado TeamsChannelData , que expõe propriedades para acessar informações específicas do Teams.

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

Enviar respostas a mensagens

Para responder a uma mensagem existente, ligue ReplyToActivity para o .NET ou session.send para o Node.js. O SDK do Construtor de Bot lida com todos os detalhes.

Se optar por utilizar a API REST, também pode chamar o /v3/conversations/{conversationId}/activities/{activityId} ponto final.

O conteúdo da mensagem em si pode conter texto simples ou alguns dos cartões fornecidos pelo Bot Framework e ações card.

Tenha em atenção que, no seu esquema de saída, deve utilizar sempre o mesmo serviceUrl esquema que recebeu. Esteja ciente de que o valor do tende serviceUrl a ser estável, mas pode mudar. Quando uma nova mensagem é recebida, seu bot deve verificar seu valor armazenado de serviceUrl.

Atualizar mensagens

Em vez de fazer com que suas mensagens sejam instantâneos estáticos de dados, seu bot pode atualizar dinamicamente mensagens em linha depois de enviá-las. Pode utilizar atualizações de mensagens dinâmicas para cenários como atualizações de sondagens, modificação de ações disponíveis após premir um botão ou qualquer outra alteração de estado assíncrona.

A nova mensagem não tem de corresponder ao tipo original. Por exemplo, se a mensagem original continha um anexo, a nova mensagem pode ser uma mensagem de texto.

REST API

Para emitir uma atualização de mensagem, execute uma solicitação PUT no /v3/conversations/<conversationId>/activities/<activityId>/ ponto de extremidade usando um determinado ID de atividade. Para concluir esse cenário, você deve armazenar em cache o ID de atividade retornado pela chamada POST original.

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

Exemplo do .NET

Você pode usar o UpdateActivityAsync método no SDK do Construtor de Bot para atualizar uma mensagem existente.

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

Node.js exemplo

Você pode usar o session.connector.update método no SDK do Construtor de Bot para atualizar uma mensagem existente.

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ção (mensagens proativas)

Pode criar uma conversação pessoal com um utilizador ou iniciar uma nova cadeia de respostas num canal para o bot da sua equipa. Isso permite que você envie mensagens para seu usuário ou usuários sem que eles iniciem primeiro contato com seu bot. Para saber mais, confira os seguintes artigos:

Para obter mais informações sobre conversas iniciadas por bots, consulte Mensagens proativas para bots.

Eliminar mensagens

As mensagens podem ser excluídas usando o connector.delete() método no SDK do BotBuilder.

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