Freigeben über

Reagieren auf die Aktion zum Senden des Dialogfelds

  • Artikel

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höheren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation zu früheren Versionen suchen, lesen Sie den Abschnitt Nachrichtenerweiterungen – v3 SDK im Ordner Ressourcen der Dokumentation.

In diesem Dokument erfahren Sie, wie Ihre App auf die Aktionsbefehle reagiert, z. B. das Dialogfeld des Benutzers (in TeamsJS v1.x als Aufgabenmodul bezeichnet), die Aktion übermitteln. Nachdem ein Benutzer das Dialogfeld übermittelt hat, empfängt Ihr Webdienst eine composeExtensions/submitAction Aufrufnachricht mit der Befehls-ID und den Parameterwerten. Ihre App hat fünf Sekunden Zeit, um auf den Aufruf zu reagieren.

Sie haben die folgenden Möglichkeiten zu antworten:

Wenn die App nicht innerhalb von fünf Sekunden antwortet, wiederholt der Teams-Client die Anforderung zweimal, bevor die Fehlermeldung Unable to reach the app gesendet wird. Wenn der Bot nach dem Timeout antwortet, wird die Antwort ignoriert.

Hinweis

  • Die App muss alle Aktionen mit langer Ausführungszeit zurückstellen, nachdem der Bot auf die Aufrufanforderung antwortet. Die Ergebnisse der aktion mit langer Ausführungsdauer können als Nachricht übermittelt werden.
  • Ihre App hat fünf Sekunden Zeit, um auf die Aufrufnachricht zu antworten.

Für die Authentifizierung oder Konfiguration wird der ursprüngliche Aufruf an Ihren Webdienst zurückgesendet, nachdem der Benutzer den Vorgang abgeschlossen hat. Die folgende Tabelle zeigt, welche Arten von Antworten verfügbar sind, basierend auf dem Aufrufspeicherort commandContext der Nachrichtenerweiterung:

Antworttyp Verfassen Befehlsleiste Message
Kartenantwort ✔️ ✔️ ✔️
Weiteres Dialogfeld ✔️ ✔️ ✔️
Bot mit adaptiver Karte ✔️ ❌ ✔️
Keine Antwort ✔️ ✔️ ✔️

Hinweis

  • Wenn Sie Action.Submit über ME-Karten auswählen, sendet er eine Aufrufaktivität mit dem Namen composeExtensions, wobei der Wert gleich der üblichen Nutzlast ist.
  • Wenn Sie Action.Submit über ME-Karten auswählen, wird eine Aufrufaktivität mit dem Namen composeExtension gesendet, wobei der Wert der üblichen Nutzlast entspricht.

Wenn die App einen Konversationsbot enthält, installieren Sie den Bot in der Unterhaltung, und laden Sie dann den Dialog. Der Bot ist nützlich, um mehr Kontext für den Dialog zu erhalten. Informationen zum Installieren eines Konversationsbots finden Sie unter Anfordern der Installation Ihres Konversationsbots.

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 Nachrichtenbereich zum Verfassen eingefügt wurde

Die gängigste Möglichkeit, auf die composeExtensions/submitAction Anforderung zu reagieren, besteht darin, dass eine Karte in den Nachrichtenbereich zum Verfassen eingefügt wird. Der Benutzer übergibt die Karte an das Gespräch. Weitere Informationen zur Verwendung 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 Dialogfeld

Sie können auswählen, um auf das submitAction Ereignis mit einem zusätzlichen Dialogfeld zu antworten. Dies ist in den folgenden Szenarien nützlich:

  • Sammeln Sie große Mengen an Informationen.
  • Ändern Sie die Informationssammlung dynamisch auf der Grundlage von Benutzereingaben.
  • Validieren Sie die vom Benutzer eingegebenen Informationen und senden Sie das Formular mit einer Fehlermeldung erneut ab, wenn etwas nicht stimmt.

Die Antwortmethode ist identisch mit der Reaktion auf das ursprüngliche fetchTask Ereignis. Wenn Sie das Bot Framework SDK verwenden, wird das gleiche Ereignis für beide Übermittlungsaktionen ausgelöst. 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 Botantwort mit einer adaptiven Karte ist, dass Sie das bot -Objekt ihrem App-Manifest hinzufügen und den erforderlichen Bereich für den Bot definieren müssen. Verwenden Sie dieselbe ID wie Ihre Nachrichtenerweiterung für Ihren Bot.

  • Outlook unterstützt keine Botantwort mit adaptiver Karte.

Sie können auch auf die submitAction reagieren, indem Sie 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 Umfrage konfiguriert, ohne die Konfigurationsschritte in die Kanalunterhaltung einzubeziehen:

So konfigurieren Sie die Umfrage:

  1. Der Benutzer wählt die Nachrichtenerweiterung aus, um das Dialogfeld aufzurufen.

  2. Der Benutzer konfiguriert die Abfrage mit dem Dialogfeld.

  3. Wenn der Benutzer das Dialogfeld übermittelt, verwendet die App die bereitgestellten Informationen, um die Umfrage 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, wählen Sie aus Send , um sie hinzuzufügen.

    Hinweis

    • Die Benutzer können auch die Edit Nachricht auswählen, wodurch sie zum ursprünglichen Dialogfeld zurück gelangen.
    • Durch die Interaktion mit der adaptiven Karte wird die Nachricht vor dem Senden geändert.

  5. Nachdem der Benutzer ausgewählt hat Send, sendet der Bot die Nachricht an den Kanal.

Reagieren auf erste Übermittlungsaktion

Ihr Dialog muss auf die anfängliche composeExtensions/submitAction Nachricht mit einer Vorschau der Karte reagieren, 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 bereits 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;
}

Die BotMessagePreview-Sende- und -Bearbeitungsereignisse

Die Nachrichtenerweiterung muss auf zwei neue Typen des composeExtensions/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
}

Reagieren auf botMessagePreview-Bearbeitung

Wenn der Benutzer die Karte vor dem Versenden bearbeitet, indem er Bearbeiten wählt, erhalten Sie einecomposeExtensions/submitAction Aufforderung mit value.botMessagePreviewAction = edit. Antworten Sie, indem Sie den von Ihnen gesendeten Dialog als Reaktion auf den ersten composeExtensions/fetchTask Aufruf zurückgeben, der die Interaktion gestartet hat. Der Benutzer kann den Prozess starten, indem er die ursprünglichen Informationen erneut eingibt. Verwenden Sie die verfügbaren Informationen, um das Dialogfeld zu aktualisieren, damit der Benutzer nicht alle Informationen von Grund auf neu ausfüllen muss. Weitere Informationen zum Reagieren auf das erste fetchTask Ereignis finden Sie unter Reagieren auf das erste fetchTask Ereignis.

Auf botMessagePreview-Sendevorgang antworten

Nachdem der Benutzer " Senden" ausgewählt hat, erhalten Sie einen composeExtensions/submitAction Aufruf mit value.botMessagePreviewAction = send. Ihr Webdienst muss eine Nachricht mit der adaptiven Karte erstellen und an die Konversation senden und auch 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 das Zuweisen der Nachricht an diesen Benutzer bei der Interaktion und zeigt einen natürlicheren Interaktionsablauf an. Mit diesem Feature kann der Bot Nachrichten im Namen eines Benutzers anzeigen, wobei der Name des Benutzers im Antwortheader der adaptiven Karte angezeigt wird.

Die folgenden Abbildungen zeigen eine Adaptive Card-Nachricht, die von einem Bot gesendet wird. Das Bild auf der linken Seite ist ohne Benutzerzuordnung und das rechte Bild mit Benutzerzuordnung. Das Bild mit der Benutzerzuordnung zeigt den Namen des Benutzers im Format benutzername via bot (Megan Bowen via Poll) in der Adaptive Card-Kopfzeile an.

Benutzerzuordnungsbots

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

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

Details zum Entitätsschema OnBehalfOf

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

Feld Typ Beschreibung
itemId Ganzzahl Beschreibt die Identifizierung des Elements. Der Wert muss 0sein.
mentionType Zeichenfolge Beschreibt die Erwähnung einer "Person".
mri Zeichenfolge Message Resource Identifier (MRI) der Person, in deren Auftrag die Nachricht gesendet wird. Der Absendername der Nachricht wird als "<Benutzer> durch <Botname>" angezeigt.
displayName Zeichenfolge Name der Person. Wird als Fallback für den Fall verwendet, dass die Namensauflösung nicht verfügbar ist.

Codebeispiel

Beispielname Beschreibung .NET Node.js Manifest
Teams-Nachrichtenerweiterungen – Aktion In diesem Beispiel wird gezeigt, wie Sie Aktionsbefehle definieren, einen Dialog erstellen und auf die Aktion "Dialog übermitteln" reagieren. View View View
Vorschau der Aktion "Nachrichtenerweiterung" In diesem Beispiel wird gezeigt, wie Sie die Aktionsvorschau in Messagingerweiterungen mit Bot Framework v4 verwenden. View View View
Teams Nachrichtenerweiterungen – Suche In diesem Beispiel wird gezeigt, wie Sie eine suchbasierte Nachrichtenerweiterung erstellen. Es durchsucht NuGet-Pakete und zeigt die Ergebnisse in der suchbasierten Messagingerweiterung an. View View View

Nächster Schritt

Definition von Suchbefehlen

Siehe auch