Gérer les événements de bot dans Microsoft Teams

Important

Cet article est basé sur le SDK Bot Framework v3. Si vous recherchez la version 4.6 ou ultérieure de la documentation actuelle du Kit de développement logiciel (SDK), consultez la section robots conversationnels .

Microsoft Teams envoie des notifications à votre bot pour les modifications ou les événements qui se produisent dans les étendues où votre bot est actif. La liste suivante fournit des événements pour déclencher la logique de service :

  • Déclencher un message de bienvenue lorsque votre bot est ajouté à une équipe.
  • Interroger et mettre en cache les informations de groupe lorsque le bot est ajouté à une conversation de groupe.
  • Mettre à jour les informations mises en cache sur l’appartenance à une équipe ou les informations de canal.
  • Supprimer les informations mises en cache pour une équipe si le bot est supprimé.
  • Lorsqu’un message de bot est aimé par un utilisateur.

Chaque événement de bot est envoyé en tant qu’objet Activity dans lequel messageType définit les informations contenues dans l’objet. Pour les messages de type message, voir Envoi et réception de messages.

Les équipes et les conversationUpdate événements de groupe, déclenchés en dehors du type, ont plus d’informations d’événements Teams transmises dans le cadre de l’objet, et donc votre gestionnaire d’événements doit interroger la channelData charge utile pour les équipes et d’autres métadonnées spécifiques à l’événement channelDataeventType.

Le tableau suivant répertorie les événements que votre bot peut recevoir et sur lesquels il peut agir.

Type (Type) Objet de charge utile Type d’événement Teams Description Portée
conversationUpdate membersAdded teamMemberAdded Membre ajouté à l’équipe all
conversationUpdate membersRemoved teamMemberRemoved Le membre a été supprimé de l’équipe groupChat & team
conversationUpdate teamRenamed L’équipe a été renommée team
conversationUpdate channelCreated Un canal a été créé team
conversationUpdate channelRenamed Un canal a été renommé team
conversationUpdate channelDeleted Un canal a été supprimé team
messageReaction reactionsAdded Réaction au message du bot all
messageReaction reactionsRemoved Réaction supprimée du message du bot all

Ajout d’un membre d’équipe ou d’un bot

L’événement conversationUpdate est envoyé à votre bot lorsqu’il reçoit des informations sur les mises à jour d’adhésion pour les équipes où il est ajouté. Il reçoit également une mise à jour lorsqu’il est ajouté pour la première fois spécifiquement pour des conversations personnelles. Les informations utilisateur (Id) sont uniques pour votre bot et peuvent être mises en cache pour une utilisation ultérieure par votre service, par exemple, l’envoi d’un message à un utilisateur spécifique.

Bot ou utilisateur ajouté à une équipe

L’événement conversationUpdate avec l’objet membersAdded dans la charge utile est envoyé lorsqu’un bot est ajouté à une équipe ou qu’un nouvel utilisateur est ajouté à une équipe dans laquelle un bot est ajouté. Teams ajoute eventType.teamMemberAdded également l’objet channelData .

Étant donné que cet événement est envoyé dans les deux cas, vous devez analyser l’objet membersAdded pour déterminer si l’ajout était un utilisateur ou le bot lui-même. Pour ce dernier, une bonne pratique consiste à envoyer un message de bienvenue au canal afin que les utilisateurs puissent comprendre les fonctionnalités fournies par votre bot.

Exemple de code : vérifier si le bot était le membre ajouté

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

Exemple de schéma : Bot ajouté à l’équipe

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

Utilisateur ajouté à une réunion

L’événement conversationUpdate avec l’objet membersAdded dans la charge utile est envoyé lorsqu’un utilisateur est ajouté à une réunion privée planifiée. Les détails de l’événement sont envoyés même lorsque des utilisateurs anonymes rejoignent la réunion.

Remarque

  • Lorsqu’un utilisateur anonyme est ajouté à une réunion, l’objet de charge utile membersAdded n’a aadObjectId pas de champ.
  • Lorsqu’un utilisateur anonyme est ajouté à une réunion, from l’objet dans la charge utile a toujours l’ID de l’organisateur de la réunion, même si l’utilisateur anonyme a été ajouté par un autre présentateur.

Exemple de schéma : utilisateur ajouté à la réunion

{
   "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 ajouté pour le contexte personnel uniquement

Votre bot reçoit un conversationUpdate avec membersAdded lorsqu’un utilisateur l’ajoute directement pour la conversation personnelle. Dans ce cas, la charge utile que votre bot reçoit ne contient pas l’objet channelData.team . Vous devez l’utiliser comme filtre au cas où vous souhaiteriez que votre bot propose un message de bienvenue différent en fonction de l’étendue.

Remarque

Pour les bots d’étendue personnelle, votre bot reçoit l’événement conversationUpdate plusieurs fois, même s’il est supprimé et ajouté à nouveau. Pour le développement et les tests, vous trouverez peut-être utile d’ajouter une fonction d’assistance qui vous permet de réinitialiser complètement votre bot. Pour plus d’informations, consultezNode.js exemple ou l’exemple C# pour plus de détails sur l’implémentation.

Exemple de schéma : bot ajouté au contexte personnel

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

Membre d’équipe ou bot supprimé

L’événement conversationUpdate avec l’objet membersRemoved dans la charge utile est envoyé lorsque votre bot est supprimé d’une équipe ou qu’un utilisateur est supprimé d’une équipe où un bot est ajouté. Teams ajoute eventType.teamMemberRemoved également l’objet channelData . Comme pour l’objet, vous devez analyser l’objet membersAddedmembersRemoved pour l’ID d’application de votre bot afin de déterminer qui a été supprimé.

Remarque

Si un bot est ajouté à une équipe et bloqué ultérieurement pour le propriétaire de l’équipe par l’administrateur du client, il ne reçoit conversationUpdate pas d’événement lorsque le propriétaire supprime un utilisateur de l’équipe.

Exemple de schéma : Membre d’équipe supprimé

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

L’utilisateur a été retiré d’une réunion

L’événement conversationUpdate avec l’objet membersRemoved dans la charge utile est envoyé lorsqu’un utilisateur est supprimé d’une réunion privée planifiée. Les détails de l’événement sont envoyés même lorsque des utilisateurs anonymes rejoignent la réunion.

Remarque

  • Lorsqu’un utilisateur anonyme est supprimé d’une réunion, l’objet de charge utile membersRemoved n’a aadObjectId pas de champ.
  • Lorsqu’un utilisateur anonyme est supprimé d’une réunion, from l’objet de la charge utile a toujours l’ID de l’organisateur de la réunion, même si l’utilisateur anonyme a été supprimé par un autre présentateur.

Exemple de schéma : l’utilisateur a été retiré de la réunion

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

Mises à jour du nom de l’équipe

Remarque

Il n’existe aucune fonctionnalité permettant d’interroger tous les noms d’équipe et le nom de l’équipe n’est pas renvoyé dans les charges utiles d’autres événements.

Votre bot est averti lorsque l’équipe dont il fait partie a été renommée. Il reçoit un conversationUpdate événement avec eventType.teamRenamed dans l’objet channelData . Il n’y a aucune notification pour la création ou la suppression d’équipe, car les bots existent uniquement en tant que membres d’équipes et n’ont aucune visibilité en dehors de l’étendue dans laquelle ils ont été ajoutés.

Exemple de schéma : Équipe renommée

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

Mises à jour des canaux

Votre bot est averti lorsqu’un canal est créé, renommé ou supprimé dans une équipe où il a été ajouté. Là encore, l’événement conversationUpdate est reçu et un identificateur d’événement spécifique à Teams est envoyé dans le cadre de l’objet channelData.eventType , où les données du channel.id canal sont le GUID du canal et channel.name contiennent le nom du canal lui-même.

Les événements de canal sont les suivants :

  • channelCreated Un utilisateur ajoute un nouveau canal à l’équipe.
  • channelRenamed Un utilisateur renomme un canal existant.
  • channelDeleted Un utilisateur supprime un canal.

Exemple de schéma complet : 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"
        }
    }
}

Extrait de schéma : channelData pour 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"
    }
}
⋮

Extrait de schéma : channelData pour 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"
    }
}
⋮

Réactions

L’événement messageReaction est envoyé lorsqu’un utilisateur ajoute ou supprime sa réaction à un message, qui était à l’origine envoyé par votre bot. replyToId Contient l’ID du message spécifique.

Exemple de schéma : un utilisateur aime un message

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

Exemple de schéma : un utilisateur n’aime pas un message

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