Auf die Aktion zum Absenden des Aufgabenmoduls reagieren

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höher des Bot Framework SDK. Wenn Sie nach Dokumentation für frühere Versionen suchen, lesen Sie den Abschnitt "Messaging-Erweiterungen – v3 SDK" im Ordner "Ressourcen" der Dokumentation.

In diesem Dokument erfahren Sie, wie Ihre App auf die Aktionsbefehle reagiert, z. B. das Aufgabenmodul des Benutzers, um eine Aktion zu übermitteln. Nachdem ein Benutzer das Aufgabenmodul übermittelt hat, empfängt Ihr Webdienst eine composeExtension/submitAction Aufrufnachricht mit der Befehls-ID und den Parameterwerten. Ihre App hat fünf Sekunden Zeit, um auf den Aufruf zu reagieren. Andernfalls erhält der Benutzer eine Fehlermeldung, dass die App nicht erreicht werden kann, und jede Aufforderung wird vom Teams Client ignoriert.

Sie haben die folgenden Optionen, um zu antworten:

Bei der Authentifizierung oder Konfiguration wird der ursprüngliche Aufruf nach Abschluss des Prozesses erneut an Ihren Webdienst senden. Die folgende Tabelle zeigt, welche Arten von Antworten basierend auf dem Aufrufspeicherort commandContext der Messaging-Erweiterung verfügbar sind:

Antworttyp Verfassen Befehlsleiste Message
Kartenantwort
Ein weiteres Aufgabenmodul
Bot mit adaptiver Karte x
Keine Antwort

Hinweis

  • Wenn Sie Action.Submit über ME-Karten auswählen, sendet sie Aufrufaktivitäten mit dem Namen composeExtension, wobei der Wert der üblichen Nutzlast entspricht.
  • Wenn Sie "Action.Submit through conversation" auswählen, erhalten Sie eine Nachrichtenaktivität mit dem Namen "onCardButtonClicked", wobei der Wert der üblichen Nutzlast entspricht.

Wenn die App einen Unterhaltungs-Bot enthält, installieren Sie den Bot in der Unterhaltung, und laden Sie dann das Aufgabenmodul. Der Bot ist hilfreich, um zusätzlichen Kontext für das Aufgabenmodul abzurufen. Informationen zum Installieren eines Unterhaltungs-Bots finden Sie unter "Anfordern der Installation Ihres Unterhaltungs-Bots".

Das submitAction-Aufrufereignis

Beispiele für den Empfang der Aufrufnachricht sind:

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

Antworten mit einer Karte, die in den Bereich zum Verfassen von Nachrichten eingefügt wurde

Die gängigste Möglichkeit, auf die Anforderung zu composeExtension/submitAction antworten, ist eine Karte, die in den Bereich zum Verfassen von Nachrichten eingefügt wird. Der Benutzer sendet die Karte an die Unterhaltung. Weitere Informationen zum Verwenden von Karten finden Sie unter Karten und Kartenaktionen.

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

Antworten mit einem anderen Aufgabenmodul

Sie können auswählen, um auf das submitAction Ereignis mit einem zusätzlichen Aufgabenmodul zu reagieren. Dies ist nützlich, wenn Sie Folgendes benötigen:

  • Erfassen Sie große Mengen von Informationen.
  • Dynamisches Ändern der Informationssammlung basierend auf benutzereingaben.
  • Überprüfen Sie die vom Benutzer übermittelten Informationen, und senden Sie das Formular erneut mit einer Fehlermeldung, wenn etwas nicht stimmt.

Die Antwortmethode ist identisch mit der Antwort auf das ursprüngliche fetchTask Ereignis. Wenn Sie das Bot Framework SDK verwenden, löst dasselbe Ereignis für beide Sendeaktionen aus. Damit dies funktioniert, müssen Sie Logik hinzufügen, die die richtige Antwort bestimmt.

Bot-Antwort mit adaptiver Karte

Hinweis

Die Voraussetzung für das Abrufen der Bot-Antwort mit einer adaptiven Karte besteht darin, dass Sie das bot Objekt Ihrem App-Manifest hinzufügen und den erforderlichen Bereich für den Bot definieren müssen. Verwenden Sie die gleiche ID wie Ihre Messaging-Erweiterung für Ihren Bot.

Sie können auch darauf reagieren, indem Sie submitAction eine Nachricht mit einer adaptiven Karte mit einem Bot in den Kanal einfügen. Der Benutzer kann eine Vorschau der Nachricht anzeigen, bevor er sie übermittelt. Dies ist nützlich in Szenarien, in denen Sie Informationen von den Benutzern sammeln, bevor Sie eine Antwort für adaptive Karten erstellen, oder wenn Sie die Karte aktualisieren, nachdem jemand damit interagiert hat.

Das folgende Szenario zeigt, wie die App Polly eine Abfrage konfiguriert, ohne die Konfigurationsschritte in die Kanalunterhaltung aufzunehmen:

So konfigurieren Sie die Abfrage

  1. Der Benutzer wählt die Messaging-Erweiterung aus, um das Aufgabenmodul aufzurufen.

  2. Der Benutzer konfiguriert die Abfrage mit dem Aufgabenmodul.

  3. Nach dem Übermitteln des Aufgabenmoduls verwendet die App die bereitgestellten Informationen, um die Abfrage als adaptive Karte zu erstellen, und sendet sie als botMessagePreview Antwort an den Client.

  4. Der Benutzer kann dann eine Vorschau der Adaptive Card-Nachricht anzeigen, bevor der Bot sie in den Kanal einfügt. Wenn die App kein Mitglied des Kanals ist, können Sie Send sie hinzufügen.

    Hinweis

    • Die Benutzer können auch die Edit Nachricht auswählen, die sie an das ursprüngliche Aufgabenmodul zurückgibt.
    • Die Interaktion mit der adaptiven Karte ändert die Nachricht vor dem Senden.
  5. Nachdem der Benutzer den Bot ausgewählt Send hat, wird die Nachricht an den Kanal veröffentlicht.

Reagieren auf anfängliche Übermittlungsaktion

Ihr Aufgabenmodul muss auf die anfängliche composeExtension/submitAction Nachricht mit einer Vorschau der Karte antworten, die der Bot an den Kanal sendet. Der Benutzer kann die Karte vor dem Senden überprüfen und versuchen, ihren Bot in der Unterhaltung zu installieren, wenn der Bot noch nicht installiert ist.

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

Das botMessagePreview-Sende- und Bearbeitungsereignis

Ihre Messaging-Erweiterung muss auf zwei neue Arten des composeExtension/submitAction Aufrufs reagieren, wobei value.botMessagePreviewAction = "send" und 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
}

Antworten auf botMessagePreview-Bearbeitung

Wenn der Benutzer die Karte vor dem Senden bearbeitet, erhalten Sie durch Auswählen von "Bearbeiten" einen composeExtension/submitAction Aufruf mit value.botMessagePreviewAction = edit . Antworten Sie, indem Sie das von Ihnen gesendete Aufgabenmodul als Reaktion auf den anfänglichen composeExtension/fetchTask Aufruf zurückgeben, der die Interaktion begonnen hat. Dadurch kann der Benutzer den Prozess starten, indem die ursprünglichen Informationen erneut angezeigt werden. Verwenden Sie die verfügbaren Informationen, um das Aufgabenmodul so zu aktualisieren, dass der Benutzer nicht alle Informationen von Grund auf ausfüllen muss. Weitere Informationen zum Reagieren auf das ursprüngliche fetchTask Ereignis finden Sie unter "Reagieren auf das ursprüngliche fetchTask Ereignis".

Antworten auf botMessagePreview-Senden

Nachdem der Benutzer "Senden" ausgewählt hat, erhalten Sie einen composeExtension/submitAction Aufruf mit value.botMessagePreviewAction = send . Ihr Webdienst muss eine proaktive Nachricht mit der adaptiven Karte erstellen und an die Unterhaltung senden sowie auf den Aufruf antworten.

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-Nachrichten

In Szenarien, in denen ein Bot Nachrichten im Namen eines Benutzers sendet, hilft die Zuweisung der Nachricht an diesen Benutzer bei der Interaktion und zeigt einen natürlicheren Interaktionsfluss. Mit diesem Feature können Sie einem Benutzer, in dessen Auftrag er gesendet wurde, eine Nachricht von Ihrem Bot zuordnen.

In der folgenden Abbildung befindet sich auf der linken Seite eine Kartennachricht, die von einem Bot ohne Benutzerzuschreibung gesendet wird, und auf der rechten Seite befindet sich eine Karte, die von einem Bot mit Benutzerzuschreibung gesendet wird.

Benutzerzuschreibungs-Bots

Um die Benutzerzuordnung in Teams zu verwenden, müssen Sie die OnBehalfOf Erwähnungsentität ChannelData in Ihrer Nutzlast Activity hinzufügen, die an Teams gesendet wird.

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

Details zum OnBehalfOf Entitätsschema

Der folgende Abschnitt enthält eine Beschreibung der Entitäten im OnBehalfOf Array:

Feld Typ Beschreibung
itemId Ganzzahl Beschreibt die Identifikation des Elements. Der Wert muss 0 .
mentionType Zeichenfolge Beschreibt die Erwähnung einer "Person".
mri Zeichenfolge Nachrichtenressourcenbezeichner (Message Resource Identifier, MRI) der Person, in deren Auftrag die Nachricht gesendet wird. Der Name des Absenders der Nachricht würde als " <user> bis <bot name> " angezeigt.
displayName Zeichenfolge Name der Person. Wird als Fallback verwendet, wenn die Namensauflösung nicht verfügbar ist.

Codebeispiel

Beispielname Beschreibung .NET Node.js
Teams Messaging-Erweiterungsaktion Beschreibt, wie Aktionsbefehle definiert, Aufgabenmodul erstellt und auf Aufgabenmodul-Sendeaktion reagiert wird. View View
Teams Suche nach Messaging-Erweiterungen Beschreibt, wie Suchbefehle definiert und auf Suchvorgänge reagiert wird. View View

Nächster Schritt

Weitere Informationen

Auf Suchbefehl antworten