Lidar com eventos de bot no Microsoft Teams

Artigo
06/14/2023

Importante

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

Microsoft Teams envia notificações ao seu bot para eventos que acontecem em escopos onde o seu bot está ativo. A lista a seguir fornece eventos para disparar a lógica de serviço:

Disparar uma mensagem de boas-vindas quando seu bot for adicionado a uma equipe.
Consultar e armazenar em cache as informações do grupo quando o bot for adicionado a um chat em grupo.
Atualizar informações armazenadas em cache sobre a associação à equipe ou informações de canal.
Remover as informações armazenadas em cache para uma equipe se o bot for removido.
Quando uma mensagem de bot é curtida por um usuário.

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

Equipes e eventos de grupo, disparados do conversationUpdate tipo, têm mais informações de evento do Teams passadas como parte do channelData objeto e, portanto, seu 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 executar ações.

Tipo	Objeto payload	EventType do Teams	Descrição	Escopo
`conversationUpdate`	`membersAdded`	`teamMemberAdded`	Membro adicionado à equipe	tudo
`conversationUpdate`	`membersRemoved`	`teamMemberRemoved`	Um membro foi removido da equipe	`groupChat` & `team`
`conversationUpdate`		`teamRenamed`	A sala foi renomeada	`team`
`conversationUpdate`		`channelCreated`	Um canal foi criado	`team`
`conversationUpdate`		`channelRenamed`	Um canal foi renomeado	`team`
`conversationUpdate`		`channelDeleted`	Um canal foi excluído	`team`
`messageReaction`	`reactionsAdded`		Reação à mensagem do bot	tudo
`messageReaction`	`reactionsRemoved`		Reação removida da mensagem do bot	tudo

Adição de bot ou membro da equipe

O evento conversationUpdate é enviado ao seu bot quando ele recebe informações sobre atualizações de membros para as equipes onde foi 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 a um usuário específico.

Bot ou usuário adicionado a uma equipe

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

Como esse evento é enviado em ambos os casos, você deve analisar o objeto membersAdded 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 v indas para o canal para que os usuários possam entender os recursos que seu bot fornece.

Código de exemplo: verificando se o bot foi 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 evento conversationUpdate com o objeto membersAdded 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 participam da reunião.

Observação

Quando um usuário anônimo é adicionado a uma reunião, o objeto de carga membersAdded não tem o campo aadObjectId.
Quando um usuário anônimo é adicionado a uma reunião, o objeto from na carga 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 com membersAdded quando um usuário o adiciona diretamente para chat pessoal. Nesse caso, a carga recebida pelo bot não contém o objeto channelData.team. Você deve usar isso como um filtro caso queira que seu bot ofereça uma mensagem de boas-vindas dependendo do escopo.

Observação

Para bots com escopo pessoal, o bot receberá 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 permitirá que você redefina o bot completamente. Para obter mais informações, consulte Node.js exemplo ou C# para obter mais detalhes sobre como implementar isso.

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 evento conversationUpdate com o objeto membersRemoved na carga é enviado quando o bot é removido de uma equipe ou um usuário é removido de uma equipe em que um bot foi adicionado. O Teams também adiciona eventType.teamMemberRemoved no channelData objeto. Assim como com o objeto membersAdded, você deve analisar o objeto membersRemoved para a ID do Aplicativo do bot para determinar quem foi removido.

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 evento conversationUpdate com o objeto membersRemoved na carga é enviado quando um usuário é removido de uma reunião agendada privada. Os detalhes do evento são enviados mesmo quando usuários anônimos participam da reunião.

Observação

Quando um usuário anônimo é removido de uma reunião, o objeto da carga membersRemoved não tem um campo aadObjectId.
Quando um usuário anônimo é removido de uma reunião, o objeto from no conteúdo 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 da equipe

Observação

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

Seu bot é notificado quando a equipe em que ele está foi renomeada. Ele recebe um evento conversationUpdate com eventType.teamRenamed no objeto channelData. Não há notificações para criação ou exclusão de equipe, pois 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 ele foi adicionado. Novamente, o conversationUpdate evento é recebido e um identificador de evento específico do Teams é enviado como parte do channelData.eventType objeto, onde os dados do channel.id canal são o GUID do canal e channel.name contém o próprio nome do canal.

Os eventos de 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 de 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 de 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 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 diferente de 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"
}

Lidar com eventos de bot no Microsoft Teams

Adição de bot ou membro da equipe

Bot ou usuário adicionado a uma equipe

Código de exemplo: verificando se o bot foi o membro adicionado

.NET

Node.js

Exemplo de esquema: bot adicionado à equipe

Usuário adicionado a uma reunião

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

Bot adicionado apenas para contexto pessoal

Exemplo de esquema: bot adicionado ao contexto pessoal

Membro da equipe ou bot removido

Exemplo de esquema: membro da equipe removido

Usuário removido de uma reunião

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

Atualizações de nome da equipe

Exemplo de esquema: equipe renomeada

Atualizações de canal

Exemplo de esquema completo: channelCreated

Trecho de esquema: channelData para channelRenamed

Trecho de esquema: channelData para channelDeleted

Reações

Exemplo de esquema: um usuário curte uma mensagem

Exemplo de esquema: um usuário diferente de uma mensagem

Comentários

Recursos adicionais