Lidar com eventos de bot no Microsoft Teams

Artigo
07/16/2024

Importante

Este artigo baseia-se no SDK v3 do Bot Framework. Se estiver à procura da versão atual da documentação 4.6 ou posterior do SDK, consulte a secçã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 seguinte fornece eventos para acionar a lógica do 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.

As equipas e os eventos de grupo, acionados fora do conversationUpdate tipo, têm mais informações de eventos do Teams transmitidas como parte do channelData objeto e, por conseguinte, o processador de eventos tem de consultar o channelData payload do Teams eventType e mais metadados específicos de eventos.

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 de utilizador (Id) são exclusivas para o bot e podem ser colocadas em cache para utilização futura pelo seu serviço, como enviar uma mensagem a um utilizador 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 o 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 os utilizadores anónimos entram na 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 de âmbito 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, veja Node.js exemplo ou exemplo de 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 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 o 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 os utilizadores anónimos entram na 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 existem notificações para a criação ou eliminação de equipas, porque os bots só existem como parte das equipas e não têm visibilidade fora do âmbito 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, em que 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 utilizador adiciona um novo canal à equipa.
channelRenamed Um utilizador muda o nome de um canal existente.
channelDeleted Um utilizador 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 utilizador adiciona ou remove a 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 utilizador ao contrário 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"
}

Partilhar via

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 utilizador ao contrário de uma mensagem

Recursos adicionais