Manipular eventos de bot no Microsoft Teams

Importante

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

O Microsoft Teams envia notificações ao bot sobre alterações ou eventos que ocorrem nos escopos em que o bot está ativo. A lista a seguir fornece eventos para disparar a lógica do serviço:

  • Dispare uma mensagem de boas-vindas quando o bot for adicionado a uma equipe.
  • Consulte e armazene em cache as informações do grupo quando o bot for adicionado a um chat em grupo.
  • Atualize informações armazenadas em cache na associação à equipe ou informações do canal.
  • Remova as informações armazenadas em cache de uma equipe se o bot for removido.
  • Quando uma mensagem de bot é curtida por um usuário.

Cada evento de bot é enviado como um Activity objeto no qual messageType define quais informações estão no objeto. Para mensagens do tipo message, consulte Envio e recebimento de mensagens.

Os eventos do Teams e do grupo, disparados fora do conversationUpdate tipo, têm mais informações de evento do Teams passadas como parte do objeto e, portanto, o channelData manipulador de eventos deve consultar a channelData carga para o Teams eventType e metadados mais específicos do evento.

A tabela a seguir lista os eventos que seu bot pode receber e nos quais pode agir.

Tipo Objeto de conteúdo Teams: eventType Descrição Escopo
conversationUpdate membersAdded teamMemberAdded Membro adicionado à equipe mesma
conversationUpdate membersRemoved teamMemberRemoved O membro foi removido da equipe groupChat & team
conversationUpdate teamRenamed A equipe foi renomeada team
conversationUpdate channelCreated Foi criado um canal team
conversationUpdate channelRenamed Um canal foi renomeado team
conversationUpdate channelDeleted Um canal foi excluído team
messageReaction reactionsAdded Reação à mensagem do bot mesma
messageReaction reactionsRemoved Reação removida da mensagem do bot mesma

Adição de bot ou membro da equipe

O conversationUpdate evento é enviado ao bot quando ele recebe informações sobre atualizações de associação para as equipes em que ele é adicionado. Ele também recebe uma atualização quando é adicionado pela primeira vez especificamente para conversas pessoais. As informações do usuário (Id) são exclusivas para o bot e podem ser armazenadas em cache para uso futuro pelo serviço, como enviar uma mensagem para um usuário específico.

Bot ou usuário adicionado a uma equipe

O conversationUpdate evento com o membersAdded objeto na carga é enviado quando um bot é adicionado a uma equipe ou um novo usuário é adicionado a uma equipe onde um bot é adicionado. O Teams também adiciona eventType.teamMemberAdded o channelData objeto.

Como esse evento é enviado em ambos os casos, você deve analisar o membersAdded objeto para determinar se a adição foi um usuário ou o próprio bot. Para o último, uma prática recomendada é enviar uma mensagem de boas-vindas ao canal para que os usuários possam entender os recursos que seu bot oferece.

Código de exemplo: Verificando se o bot era o membro adicionado

.NET
    for (int i = 0; i < sourceMessage.MembersAdded.Count; i++)
    {
        if (sourceMessage.MembersAdded[i].Id == sourceMessage.Recipient.Id)
        {
            addedBot = true;
            break;
        }
    }
Node.js
const builder = require('botbuilder');

var c = new builder.ChatConnector({appId: BOT_APP_ID, appPassword: .BOT_SECRET});
var bot = new builder.UniversalBot(c);

bot.on('conversationUpdate', (msg) => {
    var members = msg.membersAdded;
    // Loop through all members that were just added to the team
    for (var i = 0; i < members.length; i++) {

        // See if the member added was our bot
        if (members[i].id.includes(BOT_APP_ID)) {
            var botmessage = new builder.Message()
                .address(msg.address)
                .text('Hello World!');

            bot.send(botmessage, function(err) {});
        }
    }
});

Exemplo de esquema: Bot adicionado à equipe

{
   "membersAdded":[
      {
         "id":"28:f5d48856-5b42-41a0-8c3a-c5f944b679b0"
      }
   ],
   "type":"conversationUpdate",
   "timestamp":"2017-02-23T19:38:35.312Z",
   "localTimestamp":"2017-02-23T12:38:35.312-07:00",
   "id":"f:5f85c2ad",
   "channelId":"msteams",
   "serviceUrl":"https://smba.trafficmanager.net/amer-client-ss.msg/",
   "from":{
      "id":"29:1I9Is_Sx0OIy2rQ7Xz1lcaPKlO9eqmBRTBuW6XzkFtcjqxTjPaCMij8BVMdBcL9L_RwWNJyAHFQb0TRzXgyQvA"
   },
   "conversation":{
      "isGroup":true,
      "conversationType":"channel",
      "id":"19:efa9296d959346209fea44151c742e73@thread.skype"
   },
   "recipient":{
      "id":"28:f5d48856-5b42-41a0-8c3a-c5f944b679b0",
      "name":"SongsuggesterBot"
   },
   "channelData":{
      "team":{
         "id":"19:efa9296d959346209fea44151c742e73@thread.skype"
      },
      "eventType":"teamMemberAdded",
      "tenant":{
         "id":"72f988bf-86f1-41af-91ab-2d7cd011db47"
      }
   }
}

Usuário adicionado a uma reunião

O conversationUpdate evento com o membersAdded objeto na carga é enviado quando um usuário é adicionado a uma reunião agendada privada. Os detalhes do evento são enviados mesmo quando usuários anônimos ingressam na reunião.

Observação

  • Quando um usuário anônimo é adicionado a uma reunião, o objeto de carga membersAdded não tem aadObjectId campo.
  • Quando um usuário anônimo é adicionado a uma reunião, from o objeto no conteúdo sempre tem a ID do organizador da reunião, mesmo que o usuário anônimo tenha sido adicionado por outro apresentador.

Exemplo de esquema: Usuário adicionado à reunião

{
   "membersAdded":[
      {
         "id":"229:1Z_XHWBMhDuehhDBYoPQD6Y1DSFsTtqOZx-SA5Jh9Y4zHKm4VbFGRn7-rK7SWiW1JECwxkMdrWpHoBut2sSyQPA"
      }
   ],
   "type":"conversationUpdate",
   "timestamp":"2017-02-23T19:38:35.312Z",
   "localTimestamp":"2020-09-29T21:11:38.6542339Z",
   "id":"f:a8cd1b51-9ddb-bd35-624b-7f7474165df8",
   "channelId":"msteams",
   "serviceUrl":"https://canary.botapi.skype.com/amer/",
   "from":{
      "id":"29:1siKxZhSoTapsXvI0gyf7Gywm_HM-4kEQW4BJnWuFYVIVu87xCNP99nidgQRCcwD3L3p_schiMShzx8IDRzf8mw",
      "aadObjectId":"f30ba569-abef-4e97-8762-35f85cbae706"
   },
   "conversation":{
      "isGroup":true,
      "tenantId":"e15762ef-a8d8-416b-871c-25516354f1fe",
      "id":"19:meeting_MWJlNGViOTgtMGExYi00NDA3LWExODgtOTZhMWNlYjM4ZTRj@thread.v2"
   },
   "recipient":{
      "id":"28:3af3604a-d4fc-486b-911e-86fab41aa91c",
      "name":"EchoBot1_Rename"
   },
   "channelData":{
      "tenant":{
         "id":"e15762ef-a8d8-416b-871c-25516354f1fe"
      },
      "source":null,
      "meeting":{
         "id":"MCMxOTptZWV0aW5nX01XSmxOR1ZpT1RndE1HRXhZaTAwTkRBM0xXRXhPRGd0T1RaaE1XTmxZak00WlRSakB0aHJlYWQudjIjMA=="
      }
   }
}

Bot adicionado apenas para contexto pessoal

Seu bot recebe um conversationUpdate with membersAdded quando um usuário o adiciona diretamente para chat pessoal. Nesse caso, a carga que o bot recebe não contém o channelData.team objeto. Você deve usá-lo como um filtro caso queira que seu bot ofereça uma mensagem de boas-vindas diferente, dependendo do escopo.

Observação

Para bots com escopo pessoal, seu bot recebe o conversationUpdate evento várias vezes, mesmo que o bot seja removido e adicionado novamente. Para desenvolvimento e teste, você pode achar útil adicionar uma função auxiliar que permita redefinir o bot completamente. Para obter mais informações, consulte Node.js exemplo ou exemplo do C# para obter mais detalhes sobre a implementação.

Exemplo de esquema: bot adicionado ao contexto pessoal

{
  "membersAdded": [{
      "id": "28:f5d48856-5b42-41a0-8c3a-c5f944b679b0"
    },
    {
      "id": "29:<userID>",
      "aadObjectId": "***"
    }
  ],
  "type": "conversationUpdate",
  "timestamp": "2019-04-23T10:17:44.349Z",
  "id": "f:5f85c2ad",
  "channelId": "msteams",
  "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
  "from": {
    "id": "29:<USERID>",
    "aadObjectId": "***"
  },
  "conversation": {
    "conversationType": "personal",
    "id": "***"
  },
  "recipient": {
    "id": "28:<BOT ID>",
    "name": "<BOT NAME>"
  },
  "channelData": {
    "tenant": {
      "id": "<TENANT ID>"
    }
  }
}

Membro da equipe ou bot removido

O conversationUpdate evento com o objeto na carga é enviado quando o membersRemoved bot é removido de uma equipe ou um usuário é removido de uma equipe onde um bot é adicionado. O Teams também adiciona eventType.teamMemberRemoved o channelData objeto. Assim como acontece com o membersAdded objeto, você deve analisar o membersRemoved objeto para a ID do aplicativo do bot para determinar quem foi removido.

Observação

Se um bot for adicionado a uma equipe e posteriormente bloqueado para o proprietário da equipe pelo administrador do locatário, ele não receberá conversationUpdate evento quando o proprietário remover um usuário da equipe.

Exemplo de esquema: Membro da equipe removido

{
    "membersRemoved": [
        {
            "id": "29:1_LCi5Up14pAy65yZuaJzG1uIT7ujYhjjSTsUNqjORsZHjLHKiQIBJa4cX2XsAsRoaY7va2w6ZymA9-1VtSY_g"
        }
    ],
    "type": "conversationUpdate",
    "timestamp": "2017-02-23T19:37:06.96Z",
    "localTimestamp": "2017-02-23T12:37:06.96-07:00",
    "id": "f:d8a6a4aa",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
    "from": {
        "id": "29:1I9Is_Sx0OIy2rQ7Xz1lcaPKlO9eqmBRTBuW6XzkFtcjqxTjPaCMij8BVMdBcL9L_RwWNJyAHFQb0TRzXgyQvA"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "channel",
        "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
    },
    "recipient":
    {
        "id": "28:f5d48856-5b42-41a0-8c3a-c5f944b679b0",
        "name": "SongsuggesterBot"
    },
    "channelData": {
        "team": {
            "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
        },
        "eventType": "teamMemberRemoved",
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    }
}

Usuário removido de uma reunião

O conversationUpdate evento com o membersRemoved objeto na carga é enviado quando um usuário é removido de uma reunião agendada particular. Os detalhes do evento são enviados mesmo quando usuários anônimos ingressam na reunião.

Observação

  • Quando um usuário anônimo é removido de uma reunião, o objeto de carga membersRemoved não tem aadObjectId campo.
  • Quando um usuário anônimo é removido de uma reunião, from o objeto na carga sempre tem a ID do organizador da reunião, mesmo que o usuário anônimo tenha sido removido por outro apresentador.

Exemplo de esquema: Usuário removido da reunião

{   
      "membersRemoved": 
        {  
          "id": "29:1Z_XHWBMhDuehhDBYoPQD6Y1DSFsTtqOZx-SA5Jh9Y4zHKm4VbFGRn7-rK7SWiW1JECwxkMdrWpHoBut2sSyQPA"   
        }   
      ],   
      "type": "conversationUpdate",   
      "timestamp": "2020-09-29T21:15:08.6391139Z",   
      "id": "f:ee8dfdf3-54ac-51de-05da-9d49514974bb",   
      "channelId": "msteams",   
      "serviceUrl": "https://canary.botapi.skype.com/amer/",   
      "from": {   
        "id": "29:1siKxZhSoTapsXvI0gyf7Gywm_HM-4kEQW4BJnWuFYVIVu87xCNP99nidgQRCcwD3L3p_schiMShzx8IDRzf8mw",   
        "aadObjectId": "f30ba569-abef-4e97-8762-35f85cbae706"   
      },   
      "conversation": {    
        "isGroup": true,   
        "tenantId": "e15762ef-a8d8-416b-871c-25516354f1fe",   
        "id": "19:meeting_MWJlNGViOTgtMGExYi00NDA3LWExODgtOTZhMWNlYjM4ZTRj@thread.v2"   
      },   
      "recipient": {   
        "id": "28:3af3604a-d4fc-486b-911e-86fab41aa91c",   
        "name": "EchoBot1_Rename"   
      },   
      "channelData": {   
        "tenant": {   
          "id": "e15762ef-a8d8-416b-871c-25516354f1fe"   
        },   
        "source": null,   
        "meeting": {   
          "id": "MCMxOTptZWV0aW5nX01XSmxOR1ZpT1RndE1HRXhZaTAwTkRBM0xXRXhPRGd0T1RaaE1XTmxZak00WlRSakB0aHJlYWQudjIjMA=="   
        }   
      }   
}

Atualizações de nome de equipe

Observação

Não há funcionalidade para consultar todos os nomes de equipe, e o nome da equipe não é retornado em cargas de outros eventos.

Seu bot será notificado quando a equipe em que ele está for renomeada. Ele recebe um conversationUpdate evento com eventType.teamRenamed no channelData objeto. Não há notificações para criação ou exclusão de equipe, porque os bots existem apenas como parte das equipes e não têm visibilidade fora do escopo em que foram adicionados.

Exemplo de esquema: Equipe renomeada

{ 
    "type": "conversationUpdate",
    "timestamp": "2017-02-23T19:35:56.825Z",
    "localTimestamp": "2017-02-23T12:35:56.825-07:00",
    "id": "f:1406033e",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/", 
    "from": { 
        "id": "29:1I9Is_Sx0O-Iy2rQ7Xz1lcaPKlO9eqmBRTBuW6XzkFtcjqxTjPaCMij8BVMdBcL9L_RwWNJyAHFQb0TRzXgyQvA"
    }, 
    "conversation": {
        "isGroup": true,
        "conversationType": "channel",
        "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
    },
    "recipient": { 
        "id": "28:f5d48856-5b42-41a0-8c3a-c5f944b679b0",
        "name": "SongsuggesterLocal"
    },
    "channelData": {
        "team": {
            "id": "19:efa9296d959346209fea44151c742e73@thread.skype",
            "name": "New Team Name"
        },
        "eventType": "teamRenamed",
        "tenant": { 
           "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    }
}

Atualizações de canal

Seu bot é notificado quando um canal é criado, renomeado ou excluído em uma equipe em que foi adicionado. Novamente, o conversationUpdate evento é recebido e um identificador de evento específico do Teams é enviado como parte do objeto, onde os dados channel.id do canal são o GUID do canal e channel.name contém o próprio nome do channelData.eventType canal.

Os eventos do canal são os seguintes:

  • channelCreated Um usuário adiciona um novo canal à equipe.
  • channelRenamed Um usuário renomeia um canal existente.
  • channelDeleted Um usuário remove um canal.

Exemplo de esquema completo: channelCreated

{
    "type": "conversationUpdate",
    "timestamp": "2017-02-23T19:34:07.478Z",
    "localTimestamp": "2017-02-23T12:34:07.478-07:00",
    "id": "f:dd6ec311",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
    "from": {
        "id": "29:1wR7IdIRIoerMIWbewMi75JA3scaMuxvFon9eRQW2Nix5loMDo0362st2IaRVRirPZBv1WdXT8TIFWWmlQCizZQ"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "channel",
        "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
    },
    "recipient": {
        "id": "28:f5d48856-5b42-41a0-8c3a-c5f944b679b0",
        "name": "SongsuggesterBot"
    },
    "channelData": {
        "channel": {
            "id": "19:6d97d816470f481dbcda38244b98689a@thread.skype",
            "name": "FunDiscussions"
        },
        "team": {
            "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
        },
        "eventType": "channelCreated",
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    }
}

Trecho do esquema: channelData para channelRenamed

⋮
"channelData": {
    "channel": {
        "id": "19:6d97d816470f481dbcda38244b98689a@thread.skype",
        "name": "PhotographyUpdates"
    },
    "team": {
        "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
    },
    "eventType": "channelRenamed",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    }
}
⋮

Trecho do esquema: channelData para channelDeleted

⋮
"channelData": {
    "channel": {
        "id": "19:6d97d816470f481dbcda38244b98689a@thread.skype",
        "name": "PhotographyUpdates"
    },
    "team": {
        "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
    },
    "eventType": "channelDeleted",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    }
}
⋮

Reações

O messageReaction evento é enviado quando um usuário adiciona ou remove sua reação a uma mensagem, que foi originalmente enviada pelo seu bot. replyToId contém a ID da mensagem específica.

Exemplo de esquema: um usuário curte uma mensagem

{
    "reactionsAdded": [
        {
            "type": "like"
        }
    ],
    "type": "messageReaction",
    "timestamp": "2017-10-16T18:45:41.943Z",
    "id": "f:9f78d1f3",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
    "from": {
        "id": "29:1I9Is_Sx0O-Iy2rQ7Xz1lcaPKlO9eqmBRTBuW6XzkFtcjqxTjPaCMij8BVMdBcL9L_RwWNJyAHFQb0TRzXgyQvA",
        "aadObjectId": "c33aafc4-646d-4543-9d4c-abd28e4d2110"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "channel",
        "id": "19:3629591d4b774aa08cb0887902eee7c1@thread.skype"
    },
    "recipient": {
        "id": "28:f5d48856-5b42-41a0-8c3a-c5f944b679b0",
        "name": "SongsuggesterLocal"
    },
    "channelData": {
        "channel": {
            "id": "19:3629591d4b774aa08cb0887902eee7c1@thread.skype"
        },
        "team": {
            "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
        },
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "replyToId": "1575667808184"
}

Exemplo de esquema: um usuário não curtiu uma mensagem

{
    "reactionsRemoved": [
        {
            "type": "like"
        }
    ],
    "type": "messageReaction",
    "timestamp": "2017-10-16T18:45:41.943Z",
    "id": "f:9f78d1f3",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
    "from": {
        "id": "29:1I9Is_Sx0O-Iy2rQ7Xz1lcaPKlO9eqmBRTBuW6XzkFtcjqxTjPaCMij8BVMdBcL9L_RwWNJyAHFQb0TRzXgyQvA",
        "aadObjectId": "c33aafc4-646d-4543-9d4c-abd28e4d2110"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "channel",
        "id": "19:3629591d4b774aa08cb0887902eee7c1@thread.skype"
    },
    "recipient": {
        "id": "28:f5d48856-5b42-41a0-8c3a-c5f944b679b0",
        "name": "SongsuggesterLocal"
    },
    "channelData": {
        "channel": {
            "id": "19:3629591d4b774aa08cb0887902eee7c1@thread.skype"
        },
        "team": {
            "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
        },
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "replyToId": "1575667808184"
}
  • Last updated on