次の方法で共有

ダイアログ送信アクションに応答する

重要

このセクションのコード サンプルは、v4.6 以降のバージョンの Bot Framework SDK に基づいています。 以前のバージョンのドキュメントをお探しの場合は、ドキュメントの Resources フォルダーにある メッセージ拡張機能 - v3 SDK セクションを参照してください。

このドキュメントでは、ユーザーのダイアログ (TeamsJS v1.x のタスク モジュールと呼ばれる) 送信アクションなど、アプリがアクション コマンドにどのように応答するかについて説明します。 ユーザーがダイアログを送信すると、Web サービスはコマンド ID とパラメーター値を含む composeExtensions/submitAction 呼び出しメッセージを受け取ります。 アプリには、呼び出しに応答する 5 秒があります。

対応には、以下のオプションがあります。

アプリが 5 秒以内に応答しない場合、Teams クライアントは要求を 2 回再試行してから、 アプリに到達できませんというエラー メッセージを送信します。 タイムアウト後にボットが応答した場合、応答は無視されます。

注:

  • ボットが呼び出し要求に応答した後、アプリは実行時間の長いアクションを延期する必要があります。 実行時間の長いアクションの結果は、メッセージとして配信できます。
  • アプリには、呼び出しメッセージに応答する 5 秒があります。

認証または構成の場合、ユーザーがプロセスを完了すると、元の呼び出しが Web サービスに再送信されます。 次の表は、メッセージ拡張機能の呼び出し場所 commandContext に基づいて、使用可能な応答の種類を示しています。

応答の種類 作成 コマンド バー メッセージ
カードの応答 ✔️ ✔️ ✔️
別のダイアログ ✔️ ✔️ ✔️
アダプティブ カードを使用したボット ✔️ ❌ ✔️
応答なし ✔️ ✔️ ✔️

注:

  • [Action.Submit through ME card] を選択すると、composeExtensions という名前の呼び出しアクティビティが送信されます。値は通常のペイロードと等しくなります。
  • 会話を通して Action.Submit を選択すると、値は通常のペイロードと等しくなる onCardButtonClicked という名前のメッセージ アクティビティを受け取ります。

アプリに会話ボットが含まれている場合は、会話にボットをインストールし、ダイアログを読み込みます。 ボットは、ダイアログのコンテキストを増やすために役立ちます。 会話型ボットをインストールするには、「会話型ボットのインストールを要求する」を参照してください。

submitAction 呼び出しイベント

呼び出しメッセージを受信する例を次に示します。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken) {
  //code to handle the submit action
}

メッセージ作成領域にカードを挿入して応答する

composeExtensions/submitAction の要求に応答する最も一般的な方法は、作成メッセージ領域にカードを挿入することです。 ユーザーは、カードを会話に送信します。 カードの使用に関する詳細については、「カードとカード アクション」を参照してください。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
    var response = new MessagingExtensionActionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            AttachmentLayout = "list",
            Type = "result",
        },
    };
    var createCardData = ((JObject)action.Data).ToObject<CreateCardData>();
var card = new HeroCard
{
     Title = createCardData.Title,
     Subtitle = createCardData.Subtitle,
     Text = createCardData.Text,
};
    var attachments = new List<MessagingExtensionAttachment>();
    attachments.Add(new MessagingExtensionAttachment
    {
        Content = card,
        ContentType = HeroCard.ContentType,
        Preview = card.ToAttachment(),
    });
    response.ComposeExtension.Attachments = attachments;
    return response;
}

別のダイアログで応答する

追加のダイアログを使用して、 submitAction イベントに応答するように選択できます。 これは、次のシナリオで役立ちます。

  • 大量の情報を収集する。
  • ユーザー入力に基づいて情報コレクションを動的に変更する。
  • ユーザーが送信した情報を検証し、問題が発生した場合は、エラー メッセージでフォームを再送信します。

対応方法は、 としての最初のfetchTaskイベントへの対応と同じです。 Bot Framework SDK を使用している場合は、両方の送信アクションに対して同じイベント トリガーが発生します。 これを機能させるには、正しい応答を決定するロジックを追加する必要があります。

アダプティブ カードを使用したボットの応答

注:

  • アダプティブ カードを使用してボットの応答を取得するための前提条件は、 bot オブジェクトをアプリ マニフェストに追加し、ボットに必要なスコープを定義する必要があるということです。 ボットのメッセージ拡張機能と同じ ID を使用します。

  • Outlook では、アダプティブ カードを使用したボットの応答はサポートされていません。

また、ボットを使用してアダプティブ カードを含むメッセージをチャネルに挿入することで、submitAction に応答することもできます。 ユーザーは、メッセージを送信する前にプレビューできます。 これは、アダプティブ カード応答を作成する前にユーザーから情報を収集するシナリオや、他のユーザーが応答した後にカードを更新する場合に便利です。

次のシナリオは、アプリ Polly がチャネル会話に構成手順を含めずに投票を構成する方法を示しています。

投票を構成するには、以下の操作を行います。

  1. ユーザーがメッセージ拡張機能を選択してダイアログを呼び出します。

  2. ユーザーは、ダイアログを使用してポーリングを構成します。

  3. ユーザーがダイアログを送信すると、アプリは提供された情報を使用してアダプティブ カードとしてポーリングを作成し、クライアントに botMessagePreview 応答として送信します。

  4. その後、ユーザーは、ボットがチャネルに挿入する前に、アダプティブ カード メッセージをプレビューできます。 アプリがチャネルのメンバーでない場合は、[ Send ] を選択して追加します。

    注:

    • また、ユーザーはメッセージを Edit することを選択して、元のダイアログに返すこともできます。
    • アダプティブ カードとの対話では、メッセージの送信前に変更されます。

  5. ユーザーが Sendを選択すると、ボットはチャネルにメッセージを投稿します。

最初の送信アクションに応答する

ダイアログは、ボットがチャネルに送信するカードのプレビューを含む初期composeExtensions/submitAction メッセージに応答する必要があります。 ユーザーは送信前にカードを確認し、ボットが既にインストールされている場合は会話にボットをインストールしてみてください。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  dynamic createCardData = ((JObject) action.Data).ToObject(typeof(JObject));
  var response = new MessagingExtensionActionResponse
  {
    ComposeExtension = new MessagingExtensionResult
    {
      Type = "botMessagePreview",
      ActivityPreview = MessageFactory.Attachment(new Attachment
      {
        Content = new AdaptiveCard("1.0")
        {
          Body = new List<AdaptiveElement>()
          {
            new AdaptiveTextBlock() { Text = "FormField1 value was:", Size = AdaptiveTextSize.Large },
            new AdaptiveTextBlock() { Text = Data["FormField1"] as string }
          },
          Height = AdaptiveHeight.Auto,
          Actions = new List<AdaptiveAction>()
          {
            new AdaptiveSubmitAction
            {
              Type = AdaptiveSubmitAction.TypeName,
              Title = "Submit",
              Data = new JObject { { "submitLocation", "messagingExtensionFetchTask" } },
            },
          }
        },
        ContentType = AdaptiveCard.ContentType
      }) as Activity
    }
  };

  return response;
}

botMessagePreview によるイベントの送信と編集

メッセージ拡張機能は、composeExtensions/submitAction 呼び出しの 2 つの新しい種類である value.botMessagePreviewAction = "send" と value.botMessagePreviewAction = "edit" に応答する必要があります。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewEditAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  //handle the event
}

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewSendAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  //handle the event
}

botMessagePreview の編集に応答する

[編集] を選択してユーザーが送信する前にカードを編集した場合は、value.botMessagePreviewAction = edit を含む composeExtensions/submitAction の呼び出しを受信します。 対話を開始した最初の composeExtensions/fetchTask 呼び出しに応答して、送信したダイアログを返して応答します。 ユーザーは、元の情報を再入力してプロセスを開始できます。 使用可能な情報を使用してダイアログを更新し、ユーザーが最初からすべての情報を入力する必要がないようにします。 最初の fetchTask イベントへの応答に関する詳細については、「最初の fetchTask イベントに応答する」を参照してください。

botMessagePreview 送信に応答する

ユーザーが [送信] を選択すると、value.botMessagePreviewAction = send を含む composeExtensions/submitAction の呼び出しを受信します。 Web サービスは、アダプティブ カードを含むメッセージを作成してスレッドに送信し、呼び出しにも応答する必要があります。

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewSendAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  var activityPreview = action.BotActivityPreview[0];
  var attachmentContent = activityPreview.Attachments[0].Content;
  var previewedCard = JsonConvert.DeserializeObject<AdaptiveCard>(attachmentContent.ToString(),
          new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore });
  
  previewedCard.Version = "1.0";

  var responseActivity = Activity.CreateMessageActivity();
  Attachment attachment = new Attachment()
  {
    ContentType = AdaptiveCard.ContentType,
    Content = previewedCard
  };
  responseActivity.Attachments.Add(attachment);
  
  // Attribute the message to the user on whose behalf the bot is posting
  responseActivity.ChannelData = new {
    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }
  };
  
  await turnContext.SendActivityAsync(responseActivity);

  return new MessagingExtensionActionResponse();
}

ボット メッセージのユーザー属性

ボットがユーザーに代わってメッセージを送信するシナリオでは、そのユーザーにメッセージを帰属すると、エンゲージメントに役立ち、より自然な対話フローが表示されます。 この機能を使用すると、ユーザーの名前がアダプティブ カード応答ヘッダーに表示されたユーザーに代わって、ボットがメッセージを表示できます。

次の画像には、ボットから送信されたアダプティブ カード メッセージが表示されます。 左側の画像にはユーザー属性がなく、右側の画像はユーザー属性を使用します。 ユーザー属性を持つ画像には、アダプティブ カード ヘッダーの bot 経由の username (Megan Bowen via Poll) という形式のユーザー名が表示されます。

ユーザー属性ボット

チームでユーザー属性を使用するには、Teams に送信される Activity ペイロードで ChannelData に OnBehalfOf メンション エンティティを追加する必要があります。

// Attribute the message to the user on whose behalf the bot is posting
  responseActivity.ChannelData = new {
    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }
  };

エンティティ スキーマの詳細OnBehalfOf

次のセクションは、OnBehalfOf 配列内のエンティティの説明です。

フィールド 種類 説明
itemId 整数 アイテムの識別について説明します。 その値は 0 にする必要があります。
mentionType String "ユーザー" のメンションについて説明します。
mri String メッセージが送信されたユーザーのメッセージ リソース識別子 (MRI)。 メッセージの送信者名は、"<user><bot 名>" として表示されます。
displayName String ユーザーの名前。 ケース名の解決が利用できない場合にフォールバックとして使用されます。

コード サンプル

サンプルの名前 説明 .NET Node.js マニフェスト
Teams メッセージ拡張機能アクション このサンプルでは、ユーザーが対話形式でコンテンツを生成できるように、Microsoft Teamsのアクション ベースのメッセージ拡張機能を作成する方法を示します。 ボット、メッセージ拡張機能、ユーザー入力とのシームレスな統合を備え、機能を強化します。 表示 表示 表示
メッセージ拡張機能アクション プレビュー このサンプル アプリは、Teams メッセージ拡張機能でアクション プレビューを利用し、ユーザーがタスク モジュールの入力からカードを作成できるようにする方法を示しています。 ユーザーにメッセージを帰属させることで、ユーザーエンゲージメントを強化するボットの相互作用を紹介します。 表示 表示 表示
Teams メッセージ拡張機能検索 このサンプルでは、ユーザーが検索を実行して結果を取得できるようにするMicrosoft Teamsでメッセージ拡張機能を作成する方法を示します。 表示 表示 表示

次のステップ

検索コマンドを定義する

関連項目