Microsoft Teams でボット イベントを処理する

重要

この記事は、v3 Bot Framework SDK に基づいています。 SDK バージョン 4.6 以降の最新のドキュメントをお探しの場合は、「 会話型ボット」 セクションを参照してください。

Microsoft Teams は、ボットがアクティブなスコープで発生した変更またはイベントに関する通知をボットに送信します。 次の一覧には、サービス ロジックをトリガーするイベントが用意されています。

  • ボットがチームに追加されたときに、ウェルカム メッセージをトリガーします。
  • ボットがグループ チャットに追加されたときにグループ情報を照会してキャッシュします。
  • チーム メンバーシップまたはチャネル情報に関するキャッシュ情報を更新します。
  • ボットが削除された場合は、チームのキャッシュされた情報を削除します。
  • ボット メッセージがユーザーに「いいね!」された場合。

各ボット イベントは、messageType がオブジェクト内の情報を定義するActivity オブジェクトとして送信されます。 タイプ message のメッセージについては、「 メッセージの送受信」を参照してください。

conversationUpdate の種類からトリガーされる Teams イベントとグループ イベントには、channelData オブジェクトの一部として渡される Teams イベント情報が多いため、イベント ハンドラーは Teams eventTypeやその他のイベント固有のメタデータのchannelData ペイロードを照会する必要があります。

次の表に、ボットが受信してアクションを実行できるイベントを示します。

Type ペイロード オブジェクト Teams eventType 説明 スコープ
conversationUpdate membersAdded teamMemberAdded メンバーがチームに追加されました all
conversationUpdate membersRemoved teamMemberRemoved メンバーがチームから削除されました groupChat & team
conversationUpdate teamRenamed チームの名前が変更されました team
conversationUpdate channelCreated チャネルが作成されました team
conversationUpdate channelRenamed チャネルの名前が変更されました team
conversationUpdate channelDeleted チャネルが削除されました team
messageReaction reactionsAdded ボット メッセージへの反応 all
messageReaction reactionsRemoved ボット メッセージから削除されたリアクション all

チーム メンバーまたはボットの追加

conversationUpdate イベントは、追加されたチームのメンバーシップの更新に関する情報を受信するとボットに送信されます。 また、個人的な会話専用に、初めて追加されたときにも更新プログラムが送信されます。 ユーザー情報 (Id) はボットに固有のものであり、特定のユーザーにメッセージを送信するなど、サービスで将来使用するためにキャッシュできます。

チームに追加されたボットまたはユーザー

ペイロード内の membersAdded オブジェクトを含む conversationUpdate イベントは、ボットがチームに追加されるか、ボットが追加されたチームに新しいユーザーが追加されたときに送信されます。 Teams は、channelData オブジェクトにeventType.teamMemberAddedも追加します。

このイベントは両方の場合に送信されるため、 membersAdded オブジェクトを解析して、追加がユーザーによるものかボット自体によるものかを判断する必要があります。 後者の場合は、ユーザーがボットが提供する機能を理解できるように、チャネルに ウェルカム メッセージを 送信することをお勧めします。

コード例: ボットが追加されたメンバーであるかどうかを確認する

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

スキーマの例: チームに追加されたボット

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

ユーザーが会議に追加されました

ユーザーがプライベートのスケジュールされた会議に追加されると、ペイロードに membersAdded オブジェクトを含む conversationUpdate イベントが送信されます。 匿名ユーザーが会議に参加した場合でも、イベントの詳細が送信されます。

注

  • 匿名ユーザーが会議に追加されると、membersAdded ペイロード オブジェクトには aadObjectId フィールドがありません。
  • 匿名ユーザーが会議に追加されると、別の発表者によって匿名ユーザーが追加された場合でも、ペイロード内の from オブジェクトは常に会議開催者の ID を持ちます。

スキーマの例: ユーザーが会議に追加されました

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

個人的なコンテキストでのみ追加されたボット

ボットは、ユーザーが個人用チャット用に直接追加すると、membersAddedのconversationUpdateを受け取ります。 この場合、ボットが受け取るペイロードには channelData.team オブジェクトは含まれません。 スコープに応じてボットに異なる 歓迎メッセージ を提供する場合に備えて、フィルターとして使用する必要があります。

注

個人用スコープのボットの場合、ボットが削除されて再度追加された場合でも、ボットは conversationUpdate イベントを複数回受信します。 開発とテストの場合は、ボットを完全にリセットできるヘルパー関数を追加すると役立つ場合があります。 詳細については、 Node.js 例 または実装の詳細については C# の例 を参照してください。

スキーマの例: ボットが個人用コンテキストに追加されました

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

チーム メンバーまたはボットの削除

ペイロード内の membersRemoved オブジェクトを含む conversationUpdate イベントは、ボットがチームから削除された場合や、ボットが追加されたチームからユーザーが削除されたときに送信されます。 Teams は、channelData オブジェクトにeventType.teamMemberRemovedも追加します。 membersAdded オブジェクトと同様に、ボットのアプリ ID の membersRemoved オブジェクトを解析して、削除されたユーザーを特定する必要があります。

注

ボットがチームに追加され、後でテナント管理者によってチーム所有者に対してブロックされた場合、所有者がチームからユーザーを削除 conversationUpdate イベントは受信されません。

スキーマの例: チーム メンバーの削除

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

ユーザーが会議から削除されました

ユーザーがプライベートのスケジュールされた会議から削除されると、ペイロードに membersRemoved オブジェクトを含む conversationUpdate イベントが送信されます。 匿名ユーザーが会議に参加した場合でも、イベントの詳細が送信されます。

注

  • 匿名ユーザーが会議から削除されると、membersRemoved ペイロード オブジェクトには aadObjectId フィールドがありません。
  • 匿名ユーザーが会議から削除されると、匿名ユーザーが別の発表者によって削除された場合でも、ペイロード内のオブジェクト from 常に会議開催者の ID を持ちます。

スキーマの例: ユーザーが会議から削除されました

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

チーム名の更新

注

すべてのチーム名をクエリする機能はなく、チーム名は他のイベントからのペイロードでは返されません。

ボットが属するチームの名前が変更されたときにボットに通知されます。 channelData オブジェクトに eventType.teamRenamed を含む conversationUpdate イベントを受け取ります。 チームの作成または削除に関する通知はありません。これは、ボットはチームの一部としてのみ存在し、ボットが追加された範囲外では表示できないためです。

スキーマの例: チームの名前変更

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

チャネルの更新

ボットには、チャネルが追加されたチームでチャネルが作成、名前変更、または削除されると通知されます。 ここでも、 conversationUpdate イベントが受信され、Teams 固有のイベント識別子が channelData.eventType オブジェクトの一部として送信されます。ここで、チャネル データの channel.id はチャネルの GUID であり、 channel.name チャネル名自体が含まれています。

チャネル イベントは次のとおりです。

  • channelCreated ユーザーが新しいチャネルをチームに追加しました。
  • channelRenamed ユーザーが既存のチャネルの名前を変更しました。
  • channelDeleted ユーザーがチャネルを削除した場合。

完全なスキーマの例: 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"
        }
    }
}

スキーマの抜粋: channelRenamed の channelData

⋮
"channelData": {
    "channel": {
        "id": "19:6d97d816470f481dbcda38244b98689a@thread.skype",
        "name": "PhotographyUpdates"
    },
    "team": {
        "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
    },
    "eventType": "channelRenamed",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    }
}
⋮

スキーマの抜粋: channelDeleted の channelData

⋮
"channelData": {
    "channel": {
        "id": "19:6d97d816470f481dbcda38244b98689a@thread.skype",
        "name": "PhotographyUpdates"
    },
    "team": {
        "id": "19:efa9296d959346209fea44151c742e73@thread.skype"
    },
    "eventType": "channelDeleted",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    }
}
⋮

リアクション

messageReaction イベントは、ユーザーがボットによって最初に送信されたメッセージに対する反応を追加または削除したときに送信されます。 replyToId 特定のメッセージの ID が格納されます。

スキーマの例: ユーザーがメッセージにいいね! をしました

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

スキーマの例: ユーザーがメッセージを「いいね!」としない

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