Ответ на действие отправки модуля задач

Важно!

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

В этом документе описывается, как ваше приложение реагирует на команды действий, такие как действие отправки модуля задач пользователя. После того как пользователь отправляет модуль задач, веб-служба получает сообщение о вызове composeExtension/submitAction с идентификатором команды и значениями параметров. У приложения есть пять секунд для ответа на вызов, иначе пользователь получит сообщение об ошибке Не удается получить доступ к приложению, а любой ответ на вызов будет игнорироваться клиентом Teams.

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

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

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

Примечание

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

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

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

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

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

Ответ с помощью карточки, вставленной в область создания сообщения

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

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

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

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

  1. Пользователь выбирает расширение для сообщений для вызова модуля задач.

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

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

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

    Примечание

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

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

Модуль задач должен отвечать на исходное сообщение composeExtension/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

Расширение для сообщений должно отвечать на два новых типа вызовов composeExtension/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

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

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

После того как пользователь нажмет кнопку Отправить, вы получите вызов composeExtension/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();
}

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

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

На следующем рисунке слева изображено сообщение в виде карточки, отправленное ботом без атрибуции пользователя, а справа — карточка, отправленная ботом с атрибуцией пользователя.

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

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

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

Пример кода

Название примера Описание .NET Node.js
Действие расширения для сообщений Teams Описывает, как определить команды действий, создать модуль задач и ответить на действие отправки модуля задач. Просмотр Просмотр
Поиск в расширении для сообщений Teams Описывает, как определить команды поиска и отвечать на поисковые запросы. Просмотр Просмотр

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

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

Ответ на команду поиска