Ответ на действие отправить модуль задачRespond to the task module submit action

Важно!

Примеры кода, приведенные в этом разделе, основаны на 4,6 и более поздних версиях пакета SDK Bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Если вы ищете документацию по более ранним версиям, ознакомьтесь с разделом Messaging Extensions – v3 SDK в папке resources этой документации.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

После того как пользователь отправит модуль задач, веб-служба получит composeExtension/submitAction сообщение Invoke с идентификатором команды и значением параметра.Once a user submits the task module, your web service will receive a composeExtension/submitAction invoke message with the command id and parameter values set. В течение пяти секунд приложение будет отвечать на вызов, в противном случае пользователь получит сообщение об ошибке "не удается получить доступ к приложению", а любой ответ на вызов будет игнорироваться клиентом Teams.Your app will have five seconds to respond to the invoke, otherwise the user will receive an "Unable to reach the app" error message, and any reply to the invoke will be ignored by the Teams client.

Вы можете отвечать следующим параметрам.You have the following options for responding.

В приведенной ниже таблице показано, какие типы ответов доступны в зависимости от расположения вызова ( commandContext ) расширения обмена сообщениями.The table below shows which types of responses are available based on the invoke location (commandContext) of the messaging extension. Для проверки подлинности или конфигурации после того, как пользователь завершит выполнение, исходный вызов будет повторно отправлен в веб-службу.For authentication or configuration, once the user completes the flow the original invoke will be re-sent to your web service.

Тип ответаResponse Type графическийcompose панель командcommand bar messagemessage
Ответ с картойCard response xx xx xx
Другой модуль задачAnother task module xx xx xx
Bot с адаптивной картойBot with Adaptive Card xx xx
Нет ответаNo response xx xx xx

Событие Invoke СубмитактионThe submitAction invoke event

Ниже приводятся примеры получения сообщения вызова.Below are examples of receiving the invoke message.

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

Ответ с картой, вставленной в область "Создание сообщения"Respond with a card inserted into the compose message area

Наиболее распространенным способом ответа на composeExtension/submitAction запрос является карта, вставленная в область сообщения создать.The most common way to respond to the composeExtension/submitAction request is with a card inserted into the compose message area. Затем пользователь может послать карточку в беседу.The user can then choose to submit the card to the conversation. Дополнительные сведения об использовании карт см.For more information on using cards see cards and card actions.

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
    dynamic Data = JObject.Parse(action.Data.ToString());
    var response = new MessagingExtensionActionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            AttachmentLayout = "list",
            Type = "result",
        },
    };
    var card = new HeroCard
    {
        Title = Data["formField1"] as string,
        Subtitle = Data["formField2"]  as string,
        Text = Data["formField3"]  as string,
    };

    var attachments = new List<MessagingExtensionAttachment>();
    attachments.Add(new MessagingExtensionAttachment
    {
        Content = card,
        ContentType = HeroCard.ContentType,
        Preview = card.ToAttachment(),
    });

    response.ComposeExtension.Attachments = attachments;

    return response;

}

Ответ с другим модулем задачRespond with another task module

Вы можете ответить на submitAction событие с помощью дополнительного модуля задачи.You can choose to respond to the submitAction event with an additional task module. Это может быть удобно, если:This can be useful when:

  • Необходимо собрать большой объем информации.You need to collect large amounts of information.
  • Динамическое изменение собираемых данных на основе вводимых пользователем данныхIf you need to dynamically change what information you're collecting based on user input
  • Если вам нужно проверить данные, отправленные пользователем, и потенциально отправить форму с сообщением об ошибке, если что-то не так.If you need to validate the information submitted by the user and potentially resend the form with an error message if something is wrong.

Метод для ответа такой же, как и в ответ на исходное fetchTask событие.The method for response is the same as responding to the initial fetchTask event. Если вы используете пакет SDK для ленты, то одно и то же событие будет запущено для обоих действий.If you're using the Bot Framework SDK the same event will trigger for both submit actions. Это означает, что необходимо добавить логику, определяющую правильный ответ.This mean you need to be sure to add logic which determines the correct response.

Ответ Bot со адаптивной картойBot response with Adaptive Card

Примечание

Для этого процесса необходимо добавить bot объект в манифест приложения, и у вас есть необходимая область, определенная для Bot.This flow requires that you add the bot object to your app manifest, and that you have the necessary scope defined for the bot. Используйте тот же идентификатор, что и для своего расширения обмена сообщениями для ленты.Use the same Id as your messaging extension for your bot.

Вы также можете ответить на действие Отправить, вставив сообщение с адаптивной картой в канал с помощью ленты.You can also respond to the submit action by inserting a message with an Adaptive Card into the channel with a bot. Пользователь сможет просмотреть сообщение перед его отправкой и потенциально редактировать/взаимодействовать с ним.Your user will be able to preview the message before submitting it, and potentially edit/interact with it as well. Это может быть очень удобно в тех случаях, когда необходимо собрать информацию от пользователей перед созданием ответа на адаптивную карту или при необходимости обновления карточки после того, как пользователь взаимодействует с ней.This can be very useful in scenarios where you need to gather information from your users before creating an adaptive card response, or when you're going to need to update the card after someone interacts with it. В приведенном ниже сценарии показано, как приложение Полли использует этот процесс для настройки опроса без включения действий по настройке в беседе канала.The following scenario shows how the app Polly uses this flow to configure a poll without including the configuration steps in the channel conversation.

  1. Пользователь выбирает расширение системы обмена сообщениями для запуска модуля задачи.The user clicks the messaging extension to trigger the task module.
  2. Пользователь настраивает опрос с помощью модуля задач.The user configures the poll with the task module.
  3. После отправки модуля задачи приложение использует сведения, предоставленные для создания опроса в качестве адаптивной карты, и отправляет его в качестве botMessagePreview ответа клиенту.After submitting the task module the app uses the information provided to build the poll as an Adaptive Card and sends it as a botMessagePreview response to the client.
  4. После этого пользователь может просмотреть сообщение адаптивной карточки перед вставкой ленты в канал.The user can then preview the adaptive card message before the bot inserts it into the channel. Если приложение еще не является участником канала, его Нажатие Send будет добавлено.If the app is not already a member of the channel, clicking Send will add the it.
    1. Пользователь также может выбрать Edit сообщение, которое возвращает их в исходный модуль задач.The user can also chose to Edit the message, which returns them to the original task module.
  5. При взаимодействии с адаптивной картой изменяется сообщение перед его отправкой.Interacting with the adaptive card changes the message before sending it.
  6. После того как пользователь нажмет Send сообщение в канале, вы отправляете его в канал.Once the user clicks Send the bot posts the message to the channel.

Ответ на начальное действие по отправкуRespond to initial submit action

Чтобы включить этот рабочий процесс, модуль задачи должен отвечать исходному composeExtension/submitAction сообщению с предварительным просмотром карты, отправляемой с канала в канале Bot.To enable this flow your task module should respond to the initial composeExtension/submitAction message with a preview of the card that the bot will send to the channel. Это дает пользователю возможность проверить карточку перед отправкой, а также попытаться установить Bot в беседе, если она еще не установлена.This gives the user the opportunity to verify the card before sending, and also will attempt to install your bot in the conversation if it is not already installed.

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  dynamic Data = JObject.Parse(action.Data.ToString());
  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;
}

События отправки и редактирования БотмессажепревиевThe botMessagePreview send and edit events

Теперь ваше расширение сообщения должно реагировать на два новых вида composeExtension/submitAction вызова, где value.botMessagePreviewAction = "send" и value.botMessagePreviewAction = "edit" .Your message extension will now need to respond to two new varieties of the composeExtension/submitAction invoke, where value.botMessagePreviewAction = "send"and 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
}

Отклик на редактирование БотмессажепревиевRespond to botMessagePreview edit

Если пользователь решил изменить карточку перед отправкой, нажав кнопку изменить , вы получите composeExtension/submitAction вызов с помощью value.botMessagePreviewAction = edit .If the user decides to edit the card before sending by clicking the Edit button, you will receive a composeExtension/submitAction invoke with value.botMessagePreviewAction = edit. Обычно необходимо ответить, выполнив возврат модуля задачи, отправленного в ответ на начальный composeExtension/fetchTask вызов, который начал взаимодействие.You should typically respond by returning the task module you sent in response to the initial composeExtension/fetchTask invoke that began the interaction. Это позволяет пользователю начать процесс, повторно вводя исходные данные.This allows the user to start the process over by re-entering the original information. Кроме того, следует рассмотреть возможность использования сведений, которые теперь доступны для предварительного заполнения модуля задач, чтобы пользователь не заполнил всю информацию с нуля.You should also consider using the information you now have available to pre-populate the task module so the user doesn't have fill out all of the information from scratch.

Узнайте, как реагировать на начальное fetchTask событие.See responding to the initial fetchTask event.

Ответ на отправку БотмессажепревиевRespond to botMessagePreview send

Когда пользователь нажимает кнопку Отправить , вы получите composeExtension/submitAction вызов с помощью команды value.botMessagePreviewAction = send .Once the user clicks the Send button, you will receive a composeExtension/submitAction invoke with value.botMessagePreviewAction = send. Веб-службе потребуется создать и отправить упреждающее сообщение с помощью адаптивной карточки в беседу, а также ответить на вызов.Your web service will need to create and send a proactive message with the Adaptive Card to the conversation, and also reply to the invoke.

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

Атрибуты пользователей для сообщений БотыUser attribution for bots messages

В сценариях, где Bot отправляет сообщения от имени пользователя, применяя к сообщению этого пользователя, вы можете помочь в задействовании и продемонстрировать более естественный процесс взаимодействия.In scenarios where a bot sends messages on behalf of a user, attributing the message to that user can help with engagement and showcase a more natural interaction flow. Эта функция позволяет присвоить сообщение от пользователя Bot пользователю, от имени которого оно было отправлено.This feature allows you to attribute a message from your bot to a user on whose behalf it was sent.

На изображении внизу слева отображается сообщение с картой, отправленное с помощью элемента "Bot без атрибутов пользователя", а справа — карта, отправленная с помощью атрибутов пользователя.In the image below, on the left is a card message sent by a bot without user attribution and on the right is a card sent by a bot with user attribution.

Снимок экрана

Чтобы использовать атрибуты пользователей в Teams, необходимо добавить OnBehalfOf сущность "упоминание" в ChannelData Activity полезные данные, отправляемые в Teams.To use user attribution in teams, you need to add the OnBehalfOf mention entity to ChannelData in your Activity payload that is sent to Teams.

    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }

Ниже приведено описание сущностей в OnBehalfOf массиве.Below is a description of the entities in the OnBehalfOf of Array:

Сведения о OnBehalfOf схеме объектаDetails of OnBehalfOf entity schema

ПолеField ТипType ОписаниеDescription
itemId IntegerInteger Должно быть равно 0Should be 0
mentionType StringString Должно быть "Person"Should be "person"
mri StringString Идентификатор ресурса сообщения (МРИ) пользователя, от имени которого отправляется сообщение.Message resource identifier (MRI) of the person on whose behalf the message is sent. В качестве имени отправителя сообщения будет использоваться " <user> Via <bot name> ".Message sender name would appear as "<user> via <bot name>".
displayName StringString Имя пользователя.Name of the person. Используется в качестве резервного при разрешении имени в случае недоступности.Used as fallback in case name resolution is unavailable.

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

Добавление команды поискаAdd a search command

Дополнительные сведенияLearn more

Попробуйте это в кратком руководстве:Try it out in a quickstart: