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

  • Статья

Важно!

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

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

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

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

Примечание.

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

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

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

Примечание.

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

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

Примечание.

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

  • 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: 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

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

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

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

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

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

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

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

Боты атрибуции пользователей

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

// 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) пользователя, от имени которого отправляется сообщение. Имя отправителя сообщения будет отображаться как "<имя> пользователя> через <бота".
displayName String Имя пользователя. Используется в качестве резервного варианта в случае, если разрешение имен недоступно.

Пример кода

Название примера Описание .NET Node.js Манифест
Действие расширения для сообщений Teams В этом примере показано, как определить команды действий, создать диалоговое окно и ответить на действие отправки диалога. Просмотр Просмотр Просмотр
Предварительный просмотр действия расширения сообщений В этом примере показано, как использовать предварительную версию действий в расширениях обмена сообщениями с помощью Bot Framework версии 4. Просмотр Просмотр Просмотр
Поиск в расширении для сообщений Teams В этом примере показано, как создать расширение сообщений на основе Поиск. Он выполняет поиск пакетов NuGet и отображает результаты в расширении обмена сообщениями на основе поиска. Просмотр Просмотр Просмотр

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

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

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