Freigeben über

Behandeln von Botereignissen in Microsoft Teams

  • Artikel

Wichtig

Dieser Artikel basiert auf dem Bot Framework SDK v3. Wenn Sie nach der aktuellen Dokumentationsversion 4.6 oder höher des SDK suchen, lesen Sie den Abschnitt Konversationsbots .

Microsoft Teams sendet Benachrichtigungen an Ihren Bot für Änderungen oder Ereignisse, die in Bereichen stattfinden, in denen Ihr Bot aktiv ist. Die folgende Liste enthält Ereignisse zum Auslösen der Dienstlogik:

  • Auslösen einer Willkommensnachricht, wenn Ihr Bot einem Team hinzugefügt ist.
  • Abfragen und Zwischenspeichern von Gruppeninformationen, wenn der Bot einem Gruppenchat hinzugefügt ist.
  • Aktualisieren zwischengespeicherte Informationen zur Teammitgliedschaft oder zu Kanalinformationen.
  • Entfernen zwischengespeicherter Informationen für ein Team, wenn der Bot entfernt wird.
  • Wenn eine Botnachricht von einem Benutzer mit „Gefällt mir“ markiert wird.

Jedes Botereignis wird als ein Activity-Objekt gesendet, in dem messageType definiert, welche Informationen sich im Objekt befinden. Für Nachrichten vom Typ message lesen Sie Nachrichten senden und empfangen.

Teams- und Gruppenereignisse, die conversationUpdate vom Typ ausgelöst werden, verfügen über mehr Teams-Ereignisinformationen, die als Teil des channelData Objekts übergeben werden. Daher muss Ihr Ereignishandler die channelData Nutzlast für die Teams eventType und ereignisspezifischere Metadaten abfragen.

In der folgenden Tabelle sind die Ereignisse aufgeführt, die Ihr Bot empfangen und für die er entsprechende Maßnahmen ergreifen kann.

Typ Nutzdatenobjekt Teams-eventType Beschreibung Bereich
conversationUpdate membersAdded teamMemberAdded Mitglied zum Team hinzugefügt alle
conversationUpdate membersRemoved teamMemberRemoved Mitglied wurde aus dem Team entfernt groupChat & team
conversationUpdate teamRenamed Team wurde umbenannt team
conversationUpdate channelCreated Ein Kanal wurde erstellt team
conversationUpdate channelRenamed Ein Kanal wurde umbenannt team
conversationUpdate channelDeleted Ein Kanal wurde gelöscht team
messageReaction reactionsAdded Reaktion auf Botnachricht alle
messageReaction reactionsRemoved Reaktion aus Botnachricht entfernt alle

Hinzufügen von Teammitglied oder Bot

Das conversationUpdate-Ereignis wird an Ihren Bot gesendet, wenn er Informationen zu Mitgliedschaftsaktualisierungen für Teams empfängt, denen er hinzugefügt wurde. Er empfängt außerdem eine Aktualisierung, wenn er zum ersten Mal hinzugefügt wurde, speziell für persönliche Unterhaltungen. Die Benutzerinformationen (Id) sind für Ihren Bot eindeutig und können für die zukünftige Verwendung durch Ihren Dienst zwischengespeichert werden, z. B. zum Senden einer Nachricht an einen bestimmten Benutzer.

Bot oder Benutzer zu einem Team hinzugefügt

Das conversationUpdate-Ereignis mit dem membersAdded-Objekt in den Nutzdaten wird gesendet, wenn entweder einem Team ein Bot hinzugefügt wird, oder wenn ein neuer Benutzer zu einem Team hinzugefügt wird, in dem ein Bot hinzugefügt wurde. Teams fügt auch dem -Objekt hinzu eventType.teamMemberAddedchannelData .

Da dieses Ereignis in beiden Fällen gesendet wird, sollten Sie das membersAdded-Objekt parsen, um zu bestimmen, ob das hinzugefügte Objekt ein Benutzer oder der Bot selbst war. Für Letzteres empfiehlt es sich, eine Willkommensnachricht an den Kanal zu senden, damit Benutzer die Features verstehen können, die Ihr Bot bereitstellt.

Beispielcode: Überprüfen, ob der Bot das hinzugefügte Mitglied war

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

Schemabeispiel: Bot zum Team hinzugefügt

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

Benutzer zu einer Besprechung hinzugefügt

Das conversationUpdate-Ereignis mit dem membersAdded-Objekt in den Nutzdaten wird gesendet, wenn ein Benutzer zu einer privaten geplanten Besprechung hinzugefügt wird. Die Ereignisdetails werden auch dann gesendet, wenn anonyme Benutzer an der Besprechung teilnehmen.

Hinweis

  • Wenn ein anonymer Benutzer zu einer Besprechung hinzugefügt wird, verfügt das membersAdded-Nutzdatenobjekt nicht über das aadObjectId-Feld.
  • Wenn ein anonymer Benutzer zu einer Besprechung hinzugefügt wird, weist das from-Objekt in den Nutzdaten immer die ID des Besprechungsorganisators auf, auch wenn der anonyme Benutzer von einem anderen Referenten hinzugefügt wurde.

Schemabeispiel: Benutzer zu Besprechung hinzugefügt

{
   "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 nur für privaten Kontext hinzugefügt

Ihr Bot erhält eine conversationUpdate mit membersAdded, wenn ein Benutzer ihn direkt für den privaten Chat hinzufügt. In diesem Fall enthalten die Nutzdaten, die Ihr Bot empfängt, nicht das channelData.team-Objekt. Sie sollten dies als Filter verwenden, falls Ihr Bot abhängig vom Bereich eine unterschiedliche Willkommensnachricht anbieten soll.

Hinweis

Bei persönlichen Bots empfängt Ihr Bot das conversationUpdate Ereignis mehrmals, auch wenn der Bot entfernt und erneut hinzugefügt wird. Für Entwicklungs- und Testzwecke kann es hilfreich sein, eine Hilfsfunktion hinzuzufügen, die Ihnen erlaubt, Ihren Bot vollständig zurückzusetzen. Weitere Informationen zur Implementierung finden Sie unter Node.js Beispiel oder C#-Beispiel .

Schemabeispiel: Bot zum privaten Kontext hinzugefügt

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

Teammitglied oder Bot entfernt

Das conversationUpdate-Ereignis mit dem membersRemoved-Objekt in den Nutzdaten wird gesendet, wenn entweder Ihr Bot aus einem Team entfernt wird, oder wenn ein Benutzer aus einem Team entfernt wird, in dem ein Bot hinzugefügt wurde. Teams fügt auch dem -Objekt hinzu eventType.teamMemberRemovedchannelData . Wie beim membersAdded-Objekt sollten Sie das membersRemoved-Objekt für die App-ID Ihres Bots parsen, um zu bestimmen, wer entfernt wurde.

Schemabeispiel: Teammitglied entfernt

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

Benutzer aus einer Besprechung entfernt

Das conversationUpdate-Ereignis mit dem membersRemoved-Objekt in den Nutzdaten wird gesendet, wenn ein Benutzer aus einer privaten geplanten Besprechung entfernt wird. Die Ereignisdetails werden auch dann gesendet, wenn anonyme Benutzer an der Besprechung teilnehmen.

Hinweis

  • Wenn ein anonymer Benutzer aus einer Besprechung entfernt wird, verfügt das membersRemoved-Nutzdatenobjekt nicht über das aadObjectId-Feld.
  • Wenn ein anonymer Benutzer aus einer Besprechung entfernt wird, weist das from-Objekt in den Nutzdaten immer die ID des Besprechungsorganisators auf, auch wenn der anonyme Benutzer von einem anderen Referenten entfernt wurde.

Schemabeispiel: Benutzer aus Besprechung entfernt

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

Aktualisierungen des Teamnamens

Hinweis

Es gibt keine Funktionalität zum Abfragen aller Teamnamen, und der Teamname wird nicht in Nutzdaten von anderen Ereignissen zurückgegeben.

Ihr Bot wird benachrichtigt, wenn das Team, in dem er sich befindet, umbenannt wurde. Er empfängt ein conversationUpdate-Ereignis mit eventType.teamRenamed im channelData-Objekt. Es gibt keine Benachrichtigungen zur Teamerstellung oder -löschung, da Bots nur als Teil von Teams vorhanden sind und außerhalb des Bereichs, in dem sie hinzugefügt wurden, keine Sichtbarkeit haben.

Schemabeispiel: Team umbenannt

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

Kanalupdates

Ihr Bot wird benachrichtigt, wenn ein Kanal in einem Team erstellt, umbenannt oder gelöscht wird, in dem er hinzugefügt wurde. Auch hier wird das conversationUpdate Ereignis empfangen, und ein Teams-spezifischer Ereignisbezeichner wird als Teil des channelData.eventType -Objekts gesendet, wobei die Kanaldaten channel.id die GUID für den Kanal sind und channel.name den Kanalnamen selbst enthalten.

Die Kanalereignisse sind wie folgt:

  • channelCreated Ein Benutzer fügt dem Team einen neuen Kanal hinzu.
  • channelRenamed Ein Benutzer benennt einen vorhandenen Kanal um.
  • channelDeleted Ein Benutzer entfernt einen Kanal.

Vollständiges Schemabeispiel: 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"
        }
    }
}

Schemaauszug: channelData für 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"
    }
}
⋮

Schemaauszug: channelData für 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"
    }
}
⋮

Reaktionen

Das messageReaction Ereignis wird gesendet, wenn ein Benutzer seine Reaktion auf eine Nachricht hinzufügt oder entfernt, die ursprünglich von Ihrem Bot gesendet wurde. replyToId enthält die ID der spezifischen Nachricht.

Schemabeispiel: Einem Benutzer markiert eine Nachricht mit „Gefällt mir“

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

Schemabeispiel: Ein Benutzer unterscheidet sich von einer Nachricht.

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