Teams ボットの会話イベント

重要

このセクションのコード サンプルは、バージョン 4.6 以降のバージョンの Bot Framework SDK に基づいています。 以前のバージョンのドキュメントをお探しの場合は、ドキュメントのレガシ SDK フォルダーの ボット - v3 SDK セクションを参照してください。

Microsoft Teams 用の会話ボットを構築する場合は、会話イベントを操作できます。 Teams はボットがアクティブな範囲で発生する会話イベントの通知をボットに送ります。 コードでこれらのイベントをキャプチャして、以下のアクションを行うことができます。

  • ボットがチームに追加されたときに、ウェルカム メッセージをトリガーする。
  • 新しいチーム メンバーが追加または削除されたときにウェルカム メッセージをトリガーする。
  • チャネルが作成、名前変更、削除されたときに通知をトリガーする。
  • ボット メッセージがユーザーによって「いいね!」されたときに通知をトリガーする。
  • インストール中にユーザー入力 (選択) からボットの既定のチャネルを特定します。

会話の更新イベント

会話更新イベントを使用して、より良い通知と効果的なボット アクションを提供できます。

重要

  • 新しいイベントはいつでも追加でき、ボットはその受信を開始します。
  • 予期しないイベントを受け取るようにボットを設計する必要があります。
  • Bot Framework SDK を使用している場合、ボットは、処理しないことを選択したイベントに対して 200 - OK で自動的に応答します。
  • Azure Communication Services (ACS) クライアントが Teams 会議に参加または退出すると、会話更新イベントはトリガーされません。

ボットは、次のいずれかの場合に conversationUpdate イベントを受け取ります。

  • ボットが会話に追加されたとき。
  • 会話に他のメンバーが追加または削除されます。
  • 会話メタデータが変更されました。

conversationUpdate イベントは、ボットが追加されているチームのメンバーシップの更新に関する情報を受信したときにボットに送信されます。 また、ボットが個人の会話に初めて追加されたときにも更新を受け取ります。

次の表は、Teams 会話更新イベントの一覧と詳細を示しています。

実行されたアクション EventType 呼び出されたメソッド 説明 範囲
チャネルを作成しました channelCreated OnTeamsChannelCreatedAsync チャネルが作成される チーム
チャネルの名前が変更されました channelRenamed OnTeamsChannelRenamedAsync チャネルの名前が変更されます チーム
チャネルが削除されました channelDeleted OnTeamsChannelDeletedAsync チャネルが削除されます チーム
復元されたチャネル channelRestored OnTeamsChannelRestoredAsync チャネルが復元されます チーム
メンバーが追加されました membersAdded OnTeamsMembersAddedAsync メンバーが追加されます すべて
削除されたメンバー membersRemoved OnTeamsMembersRemovedAsync メンバーが削除されます すべて
チャットの名前が変更されました teamRenamed OnTeamsTeamRenamedAsync チームの名前が変更されます チーム
チームが削除されました teamDeleted OnTeamsTeamDeletedAsync チームが削除されます チーム
チームがアーカイブされました teamArchived OnTeamsTeamArchivedAsync チームはアーカイブされます チーム
チームのアーカイブが解除されました teamUnarchived OnTeamsTeamUnarchivedAsync チームのアーカイブが解除されます チーム
復元されたチーム teamRestored OnTeamsTeamRestoredAsync チームが復元される チーム

チャネルを作成しました

ボット channelCreated がインストールされているチームで新しいチャネルが作成されるたびに、イベントがボットに送信されます。

次のコードは、チャネル作成イベントの例を示しています。

protected override async Task OnTeamsChannelCreatedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel created");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

チャネルの名前が変更されました

イベントは channelRenamed 、ボットがインストールされているチームでチャネルの名前が変更されるたびにボットに送信されます。

次のコードは、チャネル名変更イベントの例を示しています。

protected override async Task OnTeamsChannelRenamedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the new Channel name");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

チャネルが削除されました

ボット channelDeleted がインストールされているチームでチャネルが削除されるたびに、イベントがボットに送信されます。

次のコードは、チャネル削除イベントの例を示しています。

protected override async Task OnTeamsChannelDeletedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel deleted");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

復元されたチャネル

イベントは channelRestored 、以前に削除されたチャネルがボットが既にインストールされているチームに復元されるたびに、ボットに送信されます。

次のコードは、チャネルが復元されたイベントの例を示しています。

protected override async Task OnTeamsChannelRestoredAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel restored.");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

メンバーが追加されました

メンバーが追加したイベントは、次のシナリオでボットに送信されます。

  1. ボット自体がインストールされ、会話に追加されたとき

    チーム コンテキストでは、アクティビティの conversation.id は、アプリのインストール中に id ユーザーが選択したチャネルまたはボットがインストールされたチャネルの に設定されます。

  2. ボットがインストールされている会話にユーザーが追加されたとき

    イベント ペイロードで受け取ったユーザー ID はボットに固有であり、ユーザーに直接メッセージを送信するなど、将来の使用のためにキャッシュできます。

メンバーが追加したアクティビティ eventType は、イベントがチーム コンテキストから送信されるときに に teamMemberAdded 設定されます。 追加された新しいメンバーがボット自体かユーザーかを判断するには、 の オブジェクトをActivityチェックしますturnContext。 リストに MembersAdded オブジェクトのフィールドRecipientid同じオブジェクトがid含まれている場合、追加されたメンバーはボットです。それ以外の場合はユーザーです。 ボットの id 形式は です 28:<MicrosoftAppId>

ヒント

イベントをInstallationUpdate使用して、ボットがいつ会話に追加または削除されるかを判断します。

次のコードは、チーム メンバー追加イベントの例を示しています。

protected override async Task OnTeamsMembersAddedAsync(IList<TeamsChannelAccount> teamsMembersAdded , TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in teamsMembersAdded)
    {
        if (member.Id == turnContext.Activity.Recipient.Id)
        {
            // Send a message to introduce the bot to the team.
            var heroCard = new HeroCard(text: $"The {member.Name} bot has joined {teamInfo.Name}");
            // Sends an activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
        else
        {
            var heroCard = new HeroCard(text: $"{member.Name} joined {teamInfo.Name}");
            // Sends an activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
    }
}

削除されたメンバー

メンバーが削除したイベントは、次のシナリオでボットに送信されます。

  1. ボット自体がアンインストールされ、会話から削除されます。
  2. ボットがインストールされている会話からユーザーが削除されたとき。

メンバーが削除したアクティビティ eventType は、イベントがチーム コンテキストから送信されるときに に teamMemberRemoved 設定されます。 新たに削除されたメンバーがボット自身なのかユーザーなのかを判断するには、turnContext のうちの Activity オブジェクトを確認します。 リストに MembersRemoved オブジェクトのフィールドRecipientid同じオブジェクトがid含まれている場合、追加されたメンバーはボットです。それ以外の場合はユーザーです。 ボットの ID は として 28:<MicrosoftAppId>書式設定されます。

注:

ユーザーがテナントから完全に削除されると、membersRemoved conversationUpdate イベントがトリガーされます。

次のコードは、チーム メンバー削除イベントの例を示しています。

protected override async Task OnTeamsMembersRemovedAsync(IList<ChannelAccount> membersRemoved, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in membersRemoved)
    {
        if (member.Id == turnContext.Activity.Recipient.Id)
        {
            // The bot was removed.
            // You should clear any cached data you have for this team.
        }
        else
        {
            var heroCard = new HeroCard(text: $"{member.Name} was removed from {teamInfo.Name}");
            // Sends an activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
    }
}

チャットの名前が変更されました

チームの名前が変更されると、そのボットは通知を受け取ります。 ボットは、channelData オブジェクト内に eventType.teamRenamed を含む conversationUpdate イベントを受信します。

次のコードは、チーム名変更イベントの例を示しています。

protected override async Task OnTeamsTeamRenamedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the new Team name");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

チームが削除されました

ボットは、チームが削除されたときに通知を受け取ります。 ボットは、channelData オブジェクト内に eventType.teamDeleted を含む conversationUpdate イベントを受信します。

次のコードは、チーム削除イベントの例を示しています。

protected override async Task OnTeamsTeamDeletedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    // Handle delete event.
}

復元されたチーム

ボットは、チームが削除された後に復元されると通知を受け取ります。 ボットは、channelData オブジェクト内に eventType.teamrestored を含む conversationUpdate イベントを受信します。

次のコードは、チーム復元イベントの例を示しています。

protected override async Task OnTeamsTeamrestoredAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

チームがアーカイブされました

チームがインストールされてアーカイブされると、ボットは通知を受け取ります。 ボットは、channelData オブジェクト内に eventType.teamarchived を含む conversationUpdate イベントを受信します。

次のコードは、チーム アーカイブ イベントの例を示しています。

protected override async Task OnTeamsTeamArchivedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
     // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

チームのアーカイブが解除されました

チームがインストールされてアーカイブが解除されると、ボットは通知を受け取ります。 ボットは、channelData オブジェクト内に eventType.teamUnarchived を含む conversationUpdate イベントを受信します。

次のコードは、チーム アーカイブ解除イベントの例を示しています。

protected override async Task OnTeamsTeamUnarchivedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

会話更新イベントを操作したので、メッセージに対するさまざまなリアクションに対して発生するメッセージリアクション イベントを理解できます。

メッセージ リアクション イベント

このイベントは messageReaction 、ユーザーがボットによって送信されたメッセージに対するリアクションを追加または削除したときに送信されます。 replyToId にはメッセージの ID が、Type にはテキスト形式のリアクションの種類が含まれます。 リアクションの種類には、怒り、ハート、笑い、いいね!、悲しい、驚きなどがあります。 このイベントには、元のメッセージの内容は含まれません。 メッセージに対する処理のリアクションがボットにとって重要な場合は、メッセージを送信するときにメッセージを格納する必要があります。 次の表に、イベントの種類とペイロード オブジェクトの詳細を示します。

EventType ペイロード オブジェクト 説明 範囲
messageReaction reactionsAdded ボット メッセージに追加されたリアクション すべて
messageReaction reactionsRemoved ボット メッセージからのリアクションの削除 すべて

ボット メッセージに追加されたリアクション

次のコードは、ボット メッセージに対するリアクションの例を示しています。

protected override async Task OnReactionsAddedAsync(IList<MessageReaction> messageReactions, ITurnContext<IMessageReactionActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var reaction in messageReactions)
    {
      var newReaction = $"You reacted with '{reaction.Type}' to the following message: '{turnContext.Activity.ReplyToId}'";
      var replyActivity = MessageFactory.Text(newReaction);
      // Sends an activity to the sender of the incoming activity.
      var resourceResponse = await turnContext.SendActivityAsync(replyActivity, cancellationToken);
    }
}

ボット メッセージからのリアクションの削除

次のコードは、ボット メッセージから削除されたリアクションの例を示しています。

protected override async Task OnReactionsRemovedAsync(IList<MessageReaction> messageReactions, ITurnContext<IMessageReactionActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var reaction in messageReactions)
    {
      var newReaction = $"You removed the reaction '{reaction.Type}' from the following message: '{turnContext.Activity.ReplyToId}'";

      var replyActivity = MessageFactory.Text(newReaction);
      // Sends an activity to the sender of the incoming activity.
      var resourceResponse = await turnContext.SendActivityAsync(replyActivity, cancellationToken);
    }
}

インストール更新イベント

ボットを会話スレッドにインストールすると、ボットは installationUpdate イベントを受け取ります。 スレッドからボットをアンインストールすると、イベントもトリガーされます。 ボットをインストールすると、イベント内のアクション フィールドが追加に設定され、ボットがアンインストールされると、アクション フィールドが削除されるように設定されます。

注:

アプリケーションをアップグレードすると、ボットはマニフェストにボットを installationUpdate 追加または削除するためにのみイベントを受け取ります。 それ以外の場合、 installationUpdate イベントはトリガーされません。 アクション フィールドは、ボットを追加する場合は追加してアップグレードに設定され、ボットを削除する場合は削除してアップグレードに設定されます。

更新イベントのインストール

installationUpdate イベントを使用して、インストールでボットから入門メッセージを送信します。 このイベントは、プライバシーとデータ保持の要件を満たすのに役立ちます。 ボットがアンインストールされたときに、ユーザーまたはスレッド データをクリーンアップして削除することもできます。

ボットが conversationUpdate チームに追加されたときに送信されるイベントと同様に、イベントの conversation.id は、アプリの installationUpdate インストール中にユーザーが選択したチャネルの ID またはインストールが発生したチャネルに設定されます。 ID は、ユーザーがボットを操作する予定のチャネルを表し、ウェルカム メッセージを送信するときにボットが使用する必要があります。 General チャネルの ID が明示的に必要なシナリオの場合は、 からteam.idchannelData取得できます。

この例では、 conversation.idinstallationUpdate アクティビティの conversationUpdate は、Daves Demo チームの応答チャネルの ID に設定されます。

選択したチャネルを作成する

注:

選択したチャネル ID は、アプリがチームにinstallationUpdateインストールされたときに送信される追加イベントでのみ設定されます。

protected override async Task OnInstallationUpdateActivityAsync(ITurnContext<IInstallationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var activity = turnContext.Activity;
    if (string.Equals(activity.Action, "Add", StringComparison.InvariantCultureIgnoreCase))
    {
        // TO:DO Installation workflow.
    }
    else
    {
        // TO:DO Uninstallation workflow.
    }
    return;
}

イベントをキャプチャするための代替方法として、シナリオを追加または削除するための専用ハンドラーを使用することもできます。

protected override async Task OnInstallationUpdateAddAsync(ITurnContext<IInstallationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    // TO:DO Installation workflow return;
}

ボットを使用した個人用アプリのアンインストール動作

アプリをアンインストールすると、ボットもアンインストールされます。 ユーザーがアプリにメッセージを送信すると、403 応答コードが表示されます。 ボットによって投稿された新しいメッセージには、403 応答コードが表示されます。 個人用スコープ内のボットのアンインストール後の動作と、Teams スコープと groupChat スコープが揃いました。 アプリがアンインストールされた後は、メッセージを送受信できません。

応答コードをアンインストールする

インストールおよびアンインストール イベント向けのイベント ハンドリング

これらのインストールイベントとアンインストール イベントを使用すると、ボットが Teams からの予期しないイベントの受信に例外を与える場合があります。これは、次の場合に発生します。

  • Microsoft Bot Framework SDK を使用せずにボットをビルドした結果、ボットが予期しないイベントを受信した場合に例外が発生します。
  • Microsoft Bot Framework SDK を使用してボットをビルドし、基本イベント ハンドルをオーバーライドして既定のイベント動作を変更することを選択します。

新しいイベントは将来いつでも追加でき、ボットが受信を開始することを知っておくべきことが重要です。 そのため、予期しないイベントを受け取る可能性があることを想定して設計する必要があります。 Bot Framework SDK を使用している場合、ボットは 200 で自動的に応答します。処理を選択しないイベントに対して [OK] になります。

会話イベントでのエラーの処理

ボットがさまざまなイベントまたはアクティビティの処理中にエラーを検出した場合は、次のスクリーンショットに示すように、意味のあるコンテキストを持たないメッセージを会話に送信しないでください。

ボット会話のエラー メッセージ応答を示すスクリーンショット。

開発フェーズでは、メッセージ交換で意味のあるメッセージを送信すると常に役立ちます。これにより、デバッグを改善するために特定のエラーに関する詳細が提供されます。 ただし、運用環境では、エラーまたはイベントを Azure アプリケーション Insights にログに記録する必要があります。 詳細については、「 ボットにテレメトリを追加する」を参照してください。

コード サンプル

サンプルの名前 説明 .NET Node.js Python マニフェスト
会話ボット このサンプルでは、Bot Framework v4 で使用できるさまざまなボット会話イベントを個人とチームのスコープで使用する方法を示します。 表示 表示 表示 表示

次の手順

関連項目