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

Article
07/16/2024

Importante

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

Microsoft Teams envoie des notifications à votre bot pour les modifications ou é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éclenchez un message de bienvenue lorsque votre bot est ajouté à une équipe.
Interrogez et mettez en cache les informations de groupe lorsque le bot est ajouté à une conversation de groupe.
Mettez à jour les informations mises en cache sur l’appartenance à l’équipe ou les informations de canal.
Supprimez 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, consultez Envoi et réception de messages.

Les événements Teams et de groupe, déclenchés hors du conversationUpdate type, ont plus d’informations d’événement Teams passées dans le cadre de l’objet channelData . Par conséquent, votre gestionnaire d’événements doit interroger la channelData charge utile pour les métadonnées Teams eventType et plus spécifiques à l’événement.

Le tableau suivant répertorie les événements sur lequel votre bot peut recevoir et prendre des mesures.

Type	Objet de charge utile	EventType Teams	Description	Portée
`conversationUpdate`	`membersAdded`	`teamMemberAdded`	membre ajouté à l'équipe	tout
`conversationUpdate`	`membersRemoved`	`teamMemberRemoved`	membre a été supprimé de l’équipe	`groupChat` & `team`
`conversationUpdate`		`teamRenamed`	Team a été renommé	`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	tout
`messageReaction`	`reactionsRemoved`		Réaction supprimée du message du bot	tout

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

L’événement conversationUpdate est envoyé à votre robot lorsqu’il reçoit des informations sur les mises à jour d’appartenance pour les équipes dans lesquelles il a été ajouté. Il reçoit également une mise à jour lorsqu’il a été ajouté pour la première fois, spécifiquement pour les conversations personnelles. Les informations utilisateur () sontId uniques pour votre bot et peuvent être mises en cache pour une utilisation ultérieure par votre service, comme 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 où un bot a été ajouté. Teams ajoute eventType.teamMemberAdded également dans 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 cette dernière, il est recommandé d’envoyer un message de bienvenue au canal afin que les utilisateurs puissent comprendre les fonctionnalités fournies par votre bot.

Exemple de code : vérification 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 planifiée privée. Les détails de l’événement sont envoyés même lorsque des utilisateurs anonymes rejoignent la réunion.

Notes

Lorsqu’un utilisateur anonyme est ajouté à une réunion, l’objet de charge utile membersAdded n’a pas de champ aadObjectId.
Lorsqu’un utilisateur anonyme est ajouté à une réunion, from 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 une conversation personnelle. Dans ce cas, la charge utile reçue par votre bot ne contient pas l’objet channelData.team. Vous devez l’utiliser comme filtre si vous souhaitez que votre bot propose un autre message de bienvenue en fonction de l’étendue.

Notes

Pour les bots à étendue personnelle, votre bot recevra l’événement conversationUpdate plusieurs fois, même si le bot est supprimé et ajouté à nouveau. Pour le développement et les tests, vous pouvez trouver utile d’ajouter une fonction d’assistance qui vous permettra de réinitialiser complètement votre bot. Pour plus d’informations, consultez Node.js exemple ou Exemple C# pour plus d’informations sur l’implémentation de ceci.

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 de l’é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 a été ajouté. Teams ajoute eventType.teamMemberRemoved également dans l’objet channelData . Comme avec l’objet membersAdded, vous devez analyser l’objet membersRemoved de l’ID d’application de votre bot pour déterminer qui a été supprimé.

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

Utilisateur supprimé 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 planifiée privée. Les détails de l’événement sont envoyés même lorsque des utilisateurs anonymes rejoignent la réunion.

Notes

Lorsqu’un utilisateur anonyme est supprimé d’une réunion, l’objet de charge utile membersRemoved n’a pas aadObjectId champ.
Lorsqu’un utilisateur anonyme est supprimé d’une réunion, from objet dans 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 : utilisateur supprimé 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 des noms d’équipe

Notes

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

Votre bot est averti lorsque l’équipe dans laquelle il se trouve a été renommée. Il reçoit un événement de conversationUpdate avec eventType.teamRenamed dans l’objet channelData . Il n’existe aucune notification de création ou de suppression d’équipe, car les bots existent uniquement dans le cadre des é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 de canal

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 a été initialement 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 est différent d’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"
}

Partager via

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

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

Bot ou utilisateur ajouté à une équipe

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

.NET

Node.js

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

Utilisateur ajouté à une réunion

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

Bot ajouté pour le contexte personnel uniquement

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

Membre de l’équipe ou bot supprimé

Exemple de schéma : membre de l’équipe supprimé

Utilisateur supprimé d’une réunion

Exemple de schéma : utilisateur supprimé de la réunion

Mises à jour des noms d’équipe

Exemple de schéma : équipe renommée

Mises à jour de canal

Exemple de schéma complet : channelCreated

Extrait de schéma : channelData pour channelRenamed

Extrait de schéma : channelData pour channelDeleted

Réactions

Exemple de schéma : un utilisateur aime un message

Exemple de schéma : un utilisateur est différent d’un message

Commentaires

Ressources supplémentaires