Reagieren auf die Aktion zum Senden des Dialogfelds
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:
- Keine Antwort: Verwenden Sie die Submit-Aktion, um einen Prozess in einem externen System auszulösen und dem Benutzer keine Rückmeldung zu geben. Es ist nützlich für prozesse mit langer Ausführungsdauer und alternativ Feedback zu geben. Sie können z. B. Feedback mit einer proaktiven Nachricht geben.
- Weiteres Dialogfeld: Sie können mit einem zusätzlichen Dialog als Teil einer mehrstufigen Interaktion antworten.
- Kartenantwort: mit einer Karte antworten, mit der der Benutzer interagieren oder die er in eine Nachricht einfügen kann
- Adaptive Karte vom Bot: Fügen Sie eine adaptive Karte direkt in die Unterhaltung ein.
- Fordern Sie den Benutzer auf, sich zu authentifizieren.
- Fordern Sie den Benutzer auf, zusätzliche Konfigurationen bereitzustellen.
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:
Der Benutzer wählt die Nachrichtenerweiterung aus, um das Dialogfeld aufzurufen.
Der Benutzer konfiguriert die Abfrage mit dem Dialogfeld.
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.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.
- Die Benutzer können auch die
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.
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 0 sein. |
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
Siehe auch
Platform Docs
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter:Einreichen und Feedback anzeigen für