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

[アーティクル]
12/28/2023

重要

このセクションのコードサンプルは、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
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
  constructor() {
  handleTeamsMessagingExtensionSubmitAction(context, action) {
  
  //code to handle the submit action
    }
  }
}

次の例は、受け取る JSON オブジェクトです。この commandContext パラメーターは、メッセージ拡張機能がトリガーされた場所を示します。 data オブジェクトには、パラメーターとしてフォーム上のフィールドと、ユーザーが送信した値が含まれます。 JSON オブジェクトでは、最も関連性の高いフィールドが強調表示されます。

{
  "name": "composeExtension/submitAction",
  "imdisplayname": "Bob Smith",
  "serviceUrl": "https://smba.trafficmanager.net/amer/",
  "value": {
    "commandId": "giveKudos",
    "commandContext": "compose",
    "context": {
      "theme": "default"
    },
    "data": {
      "id": "submitButton",
      "formField1": "formField1_value",
      "formField2": "formField2_value",
      "formField3": "formField3_value"
    }
  },
  "conversation": {
    "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
  }
}

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

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;
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
  handleTeamsMessagingExtensionSubmitAction(context, action) {
    const data = action.data;
    const heroCard = CardFactory.heroCard(data.title, data.text);
    heroCard.content.subtitle = data.subTitle;
    const attachment = { contentType: heroCard.contentType, content: heroCard.content, preview: heroCard };

    return {
      composeExtension: {
        type: 'result',
        attachmentLayout: 'list',
        attachments: [
          attachment
        ]
      }
    }
  }
}

{
  "composeExtension": {
    "attachmentLayout": "list",
    "type": "result",
    "attachments": [
      {
        "preview": {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "formField1_value",
            "subtitle": "formField2_value",
            "text": "formField3_value"
          }
        },
        "contentType": "application/vnd.microsoft.card.hero",
        "content": {
          "title": "formField1_value",
          "subtitle": "formField2_value",
          "text": "formField3_value"
        }
      }
    ]
  }
}

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

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

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

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

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

注:

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

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

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

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

ユーザーがメッセージ拡張機能を選択してダイアログを呼び出します。
ユーザーは、ダイアログを使用してポーリングを構成します。
ユーザーがダイアログを送信すると、アプリは提供された情報を使用してアダプティブカードとしてポーリングを作成し、クライアントに応答として botMessagePreview 送信します。
その後、ユーザーは、ボットがチャネルに挿入する前に、アダプティブカードメッセージをプレビューできます。アプリがチャネルのメンバーでない場合は、を選択 Send して追加します。
注:
- ユーザーはメッセージを Edit 選択して、元のダイアログに返すこともできます。
- アダプティブカードとの対話では、メッセージの送信前に変更されます。
ユーザーがを選択 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;
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
  handleTeamsMessagingExtensionSubmitAction(context, action) {
    const submittedData = action.data;
    const adaptiveCard = CardFactory.adaptiveCard({
      actions: [
        { type: 'Action.Submit', title: 'Submit', data: { submitLocation: 'messagingExtensionSubmit' } }
      ],
      body: [
          { text: 'Adaptive Card from Task Module', type: 'TextBlock', weight: 'bolder' },
          { text: `${ submittedData.Question }`, type: 'TextBlock', id: 'Question' },
          { id: 'Answer', placeholder: 'Answer here...', type: 'Input.Text' },
        {
          choices: [
            { title: submittedData.Option1, value: submittedData.Option1 },
            { title: submittedData.Option2, value: submittedData.Option2 },
            { title: submittedData.Option3, value: submittedData.Option3 }
          ],
          id: 'Choices',
          isMultiSelect: submittedData.MultiSelect,
          style: 'expanded',
          type: 'Input.ChoiceSet'
        }
      ],
      type: 'AdaptiveCard',
      version: '1.0'
    });
    return {
      composeExtension: {
        activityPreview: MessageFactory.attachment(adaptiveCard, null, null, InputHints.ExpectingInput),
        type: 'botMessagePreview'
      }
    };
  }
}

注:

activityPreview には、1 つのアダプティブカード添付ファイルを含む message アクティビティが含まれている必要があります。 << Card Payload >> の値は、送信するカードのプレースホルダーです。

{
  "composeExtension": {
    "type": "botMessagePreview",
    "activityPreview": {
      "type": "message",
      "attachments":  [
        {
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": << Card Payload >>
        }
      ]
    }
  }
}

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
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
  handleTeamsMessagingExtensionBotMessagePreviewEdit(context, action) {

    //handle the event
  }
  
  handleTeamsMessagingExtensionBotMessagePreviewSend(context, action) {

    //handle the event
  }
}

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
  "conversation": { "id": "19:c366b75791784100b6e8b515fd55b063@thread.skype" },
  "imdisplayname": "Pranav Smith",
  ...
  "value": {
    "botMessagePreviewAction": "edit | send",
    "botActivityPreview": [
      {
        "type": "message/card",
        "attachments": [
          {
            "content":
              {
                "type": "AdaptiveCard",
                "body": [{<<card payload>>}]
              },
            "contentType" : "application/vnd.microsoft.card.adaptive"
          }
        ],
        "context": { "theme": "default" }
      }
    ],
  }
}

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();
}

class TeamsMessagingExtensionsActionPreview extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionBotMessagePreviewSend(context, action) {
      // The data has been returned to the bot in the action structure.
      const activityPreview = action.botActivityPreview[0];
      const attachmentContent = activityPreview.attachments[0].content;
      const userText = attachmentContent.body[1].text;
      const choiceSet = attachmentContent.body[3];

      const submitData = {
        MultiSelect: choiceSet.isMultiSelect ? 'true' : 'false',
        Option1: choiceSet.choices[0].title,
        Option2: choiceSet.choices[1].title,
        Option3: choiceSet.choices[2].title,
        Question: userText
      };

      const adaptiveCard = CardFactory.adaptiveCard({
        actions: [
          { type: 'Action.Submit', title: 'Submit', data: { submitLocation: 'messagingExtensionSubmit' } }
        ],
        body: [
          { text: 'Adaptive Card from Task Module', type: 'TextBlock', weight: 'bolder' },
          { text: `${ submitData.Question }`, type: 'TextBlock', id: 'Question' },
          { id: 'Answer', placeholder: 'Answer here...', type: 'Input.Text' },
          {
            choices: [
                { title: submitData.Option1, value: submitData.Option1 },
                { title: submitData.Option2, value: submitData.Option2 },
                { title: submitData.Option3, value: submitData.Option3 }
            ],
            id: 'Choices',
            isMultiSelect: submitData.MultiSelect,
            style: 'expanded',
            type: 'Input.ChoiceSet'
          }
        ],
        type: 'AdaptiveCard',
        version: '1.0'
      });
      const responseActivity = { type: 'message', attachments: [adaptiveCard], channelData: {
          onBehalfOf: [
              { itemId: 0, mentionType: 'person', mri: context.activity.from.id, displayname: context.activity.from.name }
          ]
      }};

      await context.sendActivity(responseActivity);
    }
}

次の json のような新しい composeExtensions/submitAction メッセージが表示されます。

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
  "conversation": { "id": "19:c366b75791784100b6e8b515fd55b063@thread.skype" },
  "imdisplayname": "Pranav Smith",
  ...
  "value": {
    "botMessagePreviewAction": "send",
    "botActivityPreview": [
      {
        "type": "message/card",
        "attachments": [
          {
            "content":
              {
                "type": "AdaptiveCard",
                "body": [{<<card payload>>}]
              },
            "contentType" : "application/vnd.microsoft.card.adaptive"
          }
        ],
        "context": { "theme": "default" }
      }
    ],
  }
}

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

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

次の画像には、ボットから送信されたアダプティブカードメッセージが表示されます。左側の画像にはユーザー属性がなく、右側の画像はユーザー属性を使用します。ユーザー属性を持つ画像には、アダプティブカードヘッダーの 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
      }  
    }
  };

    const responseActivity = { type: 'message', attachments: [adaptiveCard], channelData: {
        onBehalfOf: [ { 
            itemId: 0, 
            mentionType: 'person', 
            mri: context.activity.from.id, 
            displayname: context.activity.from.name 
            }
        ]
    }};

{
    "text": "Hello World!",
    "ChannelData": {
        "OnBehalfOf": [{
            "itemid": 0,
            "mentionType": "person",
            "mri": "29:orgid:89e6508d-6c0f-4ffe-9f6a-b58416d965ae",
            "displayName": "Sowrabh N R S"
        }]
    }
}

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

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

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

コードサンプル

サンプルの名前	説明	.NET	Node.js	マニフェスト
Teams メッセージ拡張機能アクション	このサンプルでは、アクションコマンドを定義し、ダイアログを作成し、ダイアログ送信アクションに応答する方法を示します。	表示	表示	表示
メッセージ拡張機能アクションプレビュー	このサンプルでは、Bot Framework v4 を使用してメッセージング拡張機能でアクションプレビューを使用する方法を示します。	表示	表示	表示
Teams メッセージ拡張機能検索	このサンプルでは、Search ベースのメッセージ拡張機能を構築する方法を示します。 NuGet パッケージを検索し、検索ベースのメッセージング拡張機能で結果を表示します。	表示	表示	表示

次のステップ

検索コマンドを定義する

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

submitAction 呼び出しイベント

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

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

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

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

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

botMessagePreview の編集に応答する

botMessagePreview 送信に応答する

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

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

コードサンプル

次のステップ

関連項目

フィードバック

その他のリソース

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

submitAction 呼び出しイベント

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

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

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

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

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

botMessagePreview の編集に応答する

botMessagePreview 送信に応答する

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

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

コード サンプル

次のステップ

関連項目

フィードバック

その他のリソース

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

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

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

コードサンプル