Reagieren auf die Aufgabe Modul Submit-AktionRespond to the task module submit action

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf 4,6 und höheren Versionen des bot Framework SDK.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Wenn Sie nach einer Dokumentation für frühere Versionen suchen, lesen Sie den Abschnitt Messaging Extensions-V3 SDK im Ordner Resources der Dokumentation.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Sobald ein Benutzer das Aufgabenmodul übermittelt hat, erhält der Webdienst eine composeExtension/submitAction Invoke-Meldung mit den festgelegten Befehls-ID-und Parameterwerten.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. Ihre APP hat fünf Sekunden Zeit, um auf den Aufruf zu reagieren, andernfalls erhält der Benutzer die Fehlermeldung "die APP kann nicht erreicht werden", und jede Antwort auf die Invoke wird vom Microsoft Teams-Client ignoriert.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.

Sie haben die folgenden Optionen für die Antwort.You have the following options for responding.

Die folgende Tabelle zeigt, welche Arten von Antworten basierend auf dem Aufruf Speicherort ( commandContext ) der Messaging Erweiterung zur Verfügung stehen.The table below shows which types of responses are available based on the invoke location (commandContext) of the messaging extension. Wenn der Benutzer den Fluss abgeschlossen hat, wird der ursprüngliche Aufruf für die Authentifizierung oder Konfiguration erneut an den Webdienst gesendet.For authentication or configuration, once the user completes the flow the original invoke will be re-sent to your web service.

AntworttypResponse Type Verfassencompose Befehlsleistecommand bar messagemessage
Karten AntwortCard response xx xx xx
Ein weiteres AufgabenmodulAnother task module xx xx xx
Bot mit adaptiver KarteBot with Adaptive Card xx xx
Keine AntwortNo response xx xx xx

Das Submit-AufrufereignisThe submitAction invoke event

Im folgenden finden Sie Beispiele für den Empfang der Invoke-Nachricht.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
}

Antworten mit einer im Nachrichtenbereich "Verfassen" eingefügten KarteRespond with a card inserted into the compose message area

Die häufigste Möglichkeit zur Reaktion auf die composeExtension/submitAction Anforderung ist eine Karte, die in den Bereich zum Verfassen von Nachrichten eingefügt wird.The most common way to respond to the composeExtension/submitAction request is with a card inserted into the compose message area. Der Benutzer kann dann beschließen, die Karte an die Unterhaltung zu senden.The user can then choose to submit the card to the conversation. Weitere Informationen zur Verwendung von Karten finden Sie unter Cards and Card Actions.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;

}

Antworten mit einem anderen AufgabenmodulRespond with another task module

Sie können beschließen, auf das submitAction Ereignis mit einem zusätzlichen Aufgabenmodul zu reagieren.You can choose to respond to the submitAction event with an additional task module. Dies kann hilfreich sein, wenn:This can be useful when:

  • Sie müssen große Mengen an Informationen sammeln.You need to collect large amounts of information.
  • Wenn Sie die gesammelten Informationen dynamisch basierend auf der Benutzereingabe ändern müssenIf you need to dynamically change what information you're collecting based on user input
  • Wenn Sie die vom Benutzer übermittelten Informationen validieren und das Formular möglicherweise mit einer Fehlermeldung erneut senden müssen, wenn etwas nicht stimmt.If you need to validate the information submitted by the user and potentially resend the form with an error message if something is wrong.

Die Methode für die Antwort ist identisch mit der Reaktion auf das anfängliche fetchTask Ereignis.The method for response is the same as responding to the initial fetchTask event. Wenn Sie das bot Framework SDK verwenden, wird für beide Submit-Aktionen dasselbe Ereignis ausgelöst.If you're using the Bot Framework SDK the same event will trigger for both submit actions. Dies bedeutet, dass Sie unbedingt Logik hinzufügen müssen, die die richtige Antwort bestimmt.This mean you need to be sure to add logic which determines the correct response.

Bot-Antwort mit adaptiver KarteBot response with Adaptive Card

Hinweis

Für diesen Fluss ist es erforderlich, dass Sie das bot Objekt Ihrem App-Manifest hinzufügen und dass Sie den erforderlichen Bereich für den bot definiert haben.This flow requires that you add the bot object to your app manifest, and that you have the necessary scope defined for the bot. Verwenden Sie dieselbe ID wie Ihre Messaging Erweiterung für Ihren bot.Use the same Id as your messaging extension for your bot.

Sie können auch auf die Submit-Aktion reagieren, indem Sie eine Nachricht mit einer adaptiven Karte in den Kanal mit einem bot einfügen.You can also respond to the submit action by inserting a message with an Adaptive Card into the channel with a bot. Der Benutzer kann die Nachricht in einer Vorschau anzeigen, bevor er ihn sendet, und möglicherweise auch mit ihm bearbeiten/interagieren.Your user will be able to preview the message before submitting it, and potentially edit/interact with it as well. Dies kann in Szenarien hilfreich sein, in denen Sie Informationen von Ihren Benutzern sammeln müssen, bevor Sie eine Adaptive Karten Antwort erstellen, oder wenn Sie die Karte aktualisieren müssen, nachdem eine Person mit ihr interagiert.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. Das folgende Szenario zeigt, wie die APP Polly diesen Fluss verwendet, um eine Umfrage zu konfigurieren, ohne die Konfigurationsschritte in der Kanal Unterhaltung zu unterbinden.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. Der Benutzer klickt auf die Messaging Erweiterung, um den Aufgabenmodul auszulösen.The user clicks the messaging extension to trigger the task module.
  2. Der Benutzer konfiguriert die Umfrage mit dem Aufgabenmodul.The user configures the poll with the task module.
  3. Nach dem Senden des Aufgabenmoduls verwendet die APP die bereitgestellten Informationen, um die Umfrage als Adaptive Karte zu erstellen und sendet sie als botMessagePreview Antwort an den Client.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. Der Benutzer kann dann eine Vorschau der adaptiven Karten Nachricht anzeigen, bevor der bot ihn in den Kanal einfügt.The user can then preview the adaptive card message before the bot inserts it into the channel. Wenn die APP noch kein Mitglied des Kanals ist, Send wird Sie durch Klicken hinzugefügt.If the app is not already a member of the channel, clicking Send will add the it.
    1. Der Benutzer kann auch Edit die Nachricht auswählen, die Sie an das ursprüngliche Aufgabenmodul zurückgibt.The user can also chose to Edit the message, which returns them to the original task module.
  5. Bei der Interaktion mit der adaptiven Karte wird die Nachricht vor dem Senden geändert.Interacting with the adaptive card changes the message before sending it.
  6. Nachdem der Benutzer Send auf den bot geklickt hat, sendet er die Nachricht an den Kanal.Once the user clicks Send the bot posts the message to the channel.

Reagieren auf die anfängliche Submit-AktionRespond to initial submit action

Um diesen Fluss zu aktivieren, sollte Ihr Aufgabenmodul auf die anfängliche composeExtension/submitAction Nachricht mit einer Vorschau der Karte Antworten, die der bot an den Kanal senden wird.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. Dies gibt dem Benutzer die Möglichkeit, die Karte vor dem senden zu überprüfen, und versucht außerdem, den bot in der Unterhaltung zu installieren, falls er noch nicht installiert ist.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;
}

Das botMessagePreview-Ereignis zum Senden und bearbeitenThe botMessagePreview send and edit events

Die Nachrichten Erweiterung muss nun auf zwei neue Varianten des Invoke-Objektes reagieren composeExtension/submitAction , wobei value.botMessagePreviewAction = "send" und ist 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
}

Reagieren auf botMessagePreview EditRespond to botMessagePreview edit

Wenn der Benutzer entscheidet, die Karte vor dem senden zu bearbeiten, indem er auf die Schaltfläche Bearbeiten klickt, wird ein composeExtension/submitAction Invoke mit angezeigt 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. Sie sollten in der Regel durch Zurückgeben des Aufgabenmoduls Antworten, das Sie als Antwort auf die anfängliche Invoke gesendet haben composeExtension/fetchTask , die die Interaktion begann.You should typically respond by returning the task module you sent in response to the initial composeExtension/fetchTask invoke that began the interaction. Dadurch kann der Benutzer den Prozess über die erneute Eingabe der ursprünglichen Informationen starten.This allows the user to start the process over by re-entering the original information. Sie sollten auch die Informationen verwenden, die Sie jetzt zur Verfügung haben, um den Aufgabenmodul vorab aufzufüllen, damit der Benutzer nicht alle Informationen aus dem nichts ausfüllt.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.

Siehe Antworten auf das anfängliche fetchTask Ereignis.See responding to the initial fetchTask event.

Auf botMessagePreview senden AntwortenRespond to botMessagePreview send

Nachdem der Benutzer auf die Schaltfläche senden geklickt hat, wird ein composeExtension/submitAction Aufruf mit angezeigt value.botMessagePreviewAction = send .Once the user clicks the Send button, you will receive a composeExtension/submitAction invoke with value.botMessagePreviewAction = send. Ihr Webdienst muss eine proaktive Nachricht mit der adaptiven Karte an die Unterhaltung erstellen und senden und auch auf die Invoke Antworten.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();
}

Benutzerzuordnung für Bots-NachrichtenUser attribution for bots messages

In Szenarien, in denen ein bot Nachrichten im Auftrag eines Benutzers sendet, kann die Nachricht dem Benutzer mit Engagement helfen und einen natürlichen Interaktions Fluss präsentieren.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. Mit dieser Funktion können Sie eine Nachricht von Ihrem bot einem Benutzer zuordnen, in dessen Auftrag er gesendet wurde.This feature allows you to attribute a message from your bot to a user on whose behalf it was sent.

Im Bild unten links sehen Sie eine Karten Nachricht, die von einem bot ohne Benutzerzuordnung gesendet wurde, und auf der rechten Seite ist eine Karte, die von einem bot mit Benutzerzuordnung gesendet wird.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.

Screenshot

Um die Benutzerzuordnung in Microsoft Teams zu verwenden, müssen Sie die OnBehalfOf mention-Entität ChannelData in ihrer Nutzlast hinzufügen, die Activity an Teams gesendet wird.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
      }  
    }

Im folgenden finden Sie eine Beschreibung der Entitäten in der OnBehalfOf von-Array:Below is a description of the entities in the OnBehalfOf of Array:

Details des OnBehalfOf EntitätsschemasDetails of OnBehalfOf entity schema

FeldField TypType BeschreibungDescription
itemId Ganze ZahlInteger Sollte 0 sein.Should be 0
mentionType ZeichenfolgeString Sollte "Person" seinShould be "person"
mri ZeichenfolgeString Nachrichten Ressourcenbezeichner (MRI) der Person, in deren Auftrag die Nachricht gesendet wird.Message resource identifier (MRI) of the person on whose behalf the message is sent. Der Name des Nachrichtenabsenders wird als " <user> via <bot name> " angezeigt.Message sender name would appear as "<user> via <bot name>".
displayName ZeichenfolgeString Der Name der Person.Name of the person. Wird als Fallback verwendet, falls die Namensauflösung nicht verfügbar ist.Used as fallback in case name resolution is unavailable.

Nächste SchritteNext Steps

Hinzufügen eines SuchbefehlsAdd a search command

Weitere InformationenLearn more

Testen Sie es in einem Schnellstart:Try it out in a quickstart: