Ответ на действие отправки в диалоговом окне

Важно!

Примеры кода в этом разделе основаны на версии 4.6 и более поздних версиях пакета SDK Bot Framework. Если вы ищете документацию по более ранним версиям, см. раздел Расширения сообщений — пакет SDK версии 3 в папке Resources документации.

В этом документе описывается, как приложение реагирует на команды действий, такие как диалоговое окно пользователя (называемое модулем задач в TeamsJS версии 1.x) отправки. После отправки пользователем диалогового окна веб-служба получает сообщение вызова с идентификатором composeExtensions/submitAction команды и значениями параметров. У вашего приложения есть пять секунд, чтобы ответить на вызов.

Возможны следующие варианты ответа:

• Без ответа: используйте действие отправки, чтобы активировать процесс во внешней системе, и не предоставляйте пользователю никакого отзыва. Он полезен для длительных процессов и для предоставления обратной связи поочередно. Например, вы можете оставить отзыв с упреждающим сообщением.
• Другое диалоговое окно. Вы можете ответить дополнительным диалогом в рамках многоэтапного взаимодействия.
• Ответ карточкой: вы можете ответить карточкой, с которой пользователь может взаимодействовать или вставлять в сообщение
• Адаптивная карточка из бота: вставьте адаптивную карточку непосредственно в беседу.
• Запросите у пользователя данные для проверки подлинности.
• Запросите у пользователя дополнительную настройку.

Если приложение не отвечает в течение пяти секунд, клиент Teams дважды повторяет запрос, прежде чем отправит сообщение об ошибке Не удается связаться с приложением. Если бот отвечает после истечения времени ожидания, ответ игнорируется.

Примечание.

• Приложение должно отложить любые длительные действия после того, как бот ответит на запрос вызова. Результаты длительных действий могут быть доставлены в виде сообщения.
• У вашего приложения есть пять секунд, чтобы ответить на сообщение вызова.

Для проверки подлинности или настройки после того, как пользователь завершит процесс, исходный вызов будет повторно отправлен в веб-службу. В следующей таблице показано, какие типы ответов доступны в зависимости от расположения commandContext вызова расширения сообщения:

Тип ответа	Создание	Панель команд	Сообщение
Ответ карточкой	✔️	✔️	✔️
Другое диалоговое окно	✔️	✔️	✔️
Бот с адаптивной карточкой	✔️	❌	✔️
Без ответа	✔️	✔️	✔️

Примечание.

• При выборе пункта Action.Submit через карты ME отправляется действие вызова с именем composeExtensions, где значение равно обычной полезной нагрузке.
• При выборе Action.Submit через беседу вы получите сообщения с именем onCardButtonClicked, где значение равно обычным полезным данным.

Если приложение содержит бот для беседы, установите его в беседе, а затем загрузите диалоговое окно. Бот полезен для получения дополнительных контекстов для диалогового окна. Для установки чат-бота см. раздел Запрос на установку чат-бота.

Событие вызова submitAction

Ниже приведены примеры получения сообщения вызова.

C#/.NET

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

JavaScript/Node.js

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

JSON

В следующем примере показан полученный объект 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 — вставить карточку в область создания сообщения Пользователь отправляет карточку в беседу. Дополнительные сведения об использовании карточек см. в разделе Карточки и действия с карточками.

C#/.NET

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

JavaScript/Node.js

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

JSON

{
  "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. Если вы используете пакет SDK Bot Framework, одно и то же событие запускает оба действия отправки. Для использования этой функции необходимо добавить логику, определяющую правильный ответ.

Ответ бота с адаптивной карточкой

Примечание.

• Чтобы получить ответ бота с помощью адаптивной карточки, необходимо добавить bot объект в манифест приложения и определить требуемую область для бота. Используйте для бота тот же идентификатор, что использует расширение для сообщений.

• Outlook не поддерживает ответ бота с адаптивной карточкой.

Вы также можете ответить на submitAction, вставив сообщение с адаптивной карточкой в канал с помощью бота. Пользователь может просмотреть сообщение перед его отправкой. Это полезно в сценариях, когда вы собираете информацию от пользователей перед созданием ответа адаптивной карточки или когда вы обновляете карточку после того, как кто-то взаимодействует с ней.

В следующем сценарии показано, как приложение Polly настраивает опрос, не включая этапы настройки в беседу канала:

Чтобы настроить опрос, выполните указанные ниже действия.

1. Пользователь выбирает расширение сообщения для вызова диалогового окна.

2. Пользователь настраивает опрос с помощью диалогового окна.

3. Когда пользователь отправляет диалоговое окно, приложение использует предоставленные сведения для создания опроса в виде адаптивной карточки и отправляет ее в ответ botMessagePreview клиенту.

4. Пользователь может просмотреть сообщение адаптивной карточки, прежде чем бот вставит его в канал. Если приложение не является участником канала, выберите Send его, чтобы добавить его.

   Примечание.

   • Пользователи также могут выбрать Edit сообщение, которое возвращает их в исходное диалоговое окно.
   • Взаимодействие с адаптивной карточкой изменяет сообщение перед отправкой.

5. После выбора Sendпользователем бот отправляет сообщение в канал.

Ответ на первоначальное действие отправки

Диалоговое окно должно отвечать на исходное composeExtensions/submitAction сообщение с помощью предварительного просмотра карточки, которую бот отправляет в канал. Пользователь может проверить карточку перед отправкой и попытаться установить бота в беседе, если бот уже установлен.

C#/.NET

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

JavaScript/Node.js

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

JSON

Примечание.

• activityPreview должен содержать действие message с ровно одним вложением адаптивной карточки. Значение << Card Payload >> является заполнителем для карточки, которую вы хотите отправить.

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

События отправки и изменения botMessagePreview

Расширение для сообщений должно отвечать на два новых типа вызовов composeExtensions/submitAction: value.botMessagePreviewAction = "send" и value.botMessagePreviewAction = "edit".

C#/.NET

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
}

JavaScript/Node.js

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

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

    //handle the event
  }
}

JSON

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

Если пользователь редактирует карточку перед отправкой, выбрав команду Изменить, вы получите вызов composeExtensions/submitAction с value.botMessagePreviewAction = edit. Ответьте, возвращая отправленное диалоговое окно в ответ на начальный composeExtensions/fetchTask вызов, который начал взаимодействие. Пользователь может запустить процесс, повторно введите исходные сведения. Используйте доступные сведения, чтобы обновить диалоговое окно, чтобы пользователю не нужно было заполнять все сведения с нуля. Дополнительные сведения об ответе на исходное событие fetchTask см. в разделе Ответ на исходное событиеfetchTask.

Ответ на отправку botMessagePreview

После того как пользователь нажмет кнопку Отправить, вы получите вызов composeExtensions/submitAction с value.botMessagePreviewAction = send. Веб-служба должна создать и отправить сообщение с адаптивной карточкой в беседу, а также ответить на вызов.

C#/.NET

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

JavaScript/Node.js

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 сообщение, аналогичное следующему коду JSON:

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

Атрибуция пользователей для сообщений ботов

В сценариях, когда бот отправляет сообщения от имени пользователя, приписывание сообщения этому пользователю помогает взаимодействовать и отображать более естественный поток взаимодействия. Эта функция позволяет боту отображать сообщения от имени пользователя с именем пользователя, отображаемым в заголовке ответа адаптивной карточки.

На следующих изображениях отображается сообщение адаптивной карточки, отправленное ботом. Левое изображение без атрибута пользователя, а правое изображение — с атрибутом пользователя. На изображении с атрибуцией пользователя в заголовке Адаптивной карточки отображается имя пользователя в формате : имя пользователя с помощью бота (Megan Bowen via Poll).

Чтобы использовать атрибуцию пользователей в командах, необходимо добавить сущность упоминания OnBehalfOf в ChannelData в полезные данные Activity, отправляемые Teams.

C#/.NET

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

JavaScript/Node.js

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

JSON

{
    "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 версии 4.	Просмотр	Просмотр	Просмотр
Поиск в расширении для сообщений Teams	В этом примере показано, как создать расширение сообщений на основе поиска. Он выполняет поиск пакетов NuGet и отображает результаты в расширении обмена сообщениями на основе поиска.	Просмотр	Просмотр	Просмотр

Дальнейшие действия

Определить команды поиска

Дополнительные ресурсы

• Схема манифеста для Teams
• Ответ на команду поиска
• Расширения для сообщений