Senden und Empfangen von Nachrichten
Konversationsbots kommunizieren mit Benutzern über Messaging und ermöglichen so nahtlose Interaktionen. Es kann reale Unterhaltungen mit Benutzern über Text- oder Sprachinteraktionen simulieren. Sie müssen sicherstellen, dass Botunterhaltungen interaktiv, dynamisch, adaptiv und benutzerfreundlich sind.
Nachrichteninhalt
Die Nachrichteninteraktion zwischen Ihrem Bot und dem Benutzer kann verschiedene Arten von Nachrichteninhalten umfassen, die:
| Inhaltstyp | Vom Benutzer zum Bot | Vom Bot zum Benutzer |
|---|---|---|
| Rich-Text und Emojis | ✔️ | ✔️ |
| Bilder | ✔️ | ✔️ |
| Adaptive Karten | ❌ | ✔️ |
Verwenden von Rich-Text-Nachrichten und Emojis
Ihr Teams-Bot kann Rich-Text und Emojis senden. Teams unterstützt Emojis über UTF-16, z. B. U+1F600 für ein grinsendes Gesicht.
Verwenden von Bildmeldungen
Damit bot-Nachrichten angezeigt werden, kann der Benutzer Bilder als Anlagen hinzufügen:
Bilder können bis zu 1024 × 1.024 Pixel und 1 MB im PNG-, JPEG- oder GIF-Format sein. Animierte GIFs werden nicht unterstützt.
Sie können die Höhe und Breite jedes Bilds mithilfe von XML angeben. In Markdown ist die Bildgröße standardmäßig 256×256. Zum Beispiel:
- ✔️ : .
<img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img> -
❌:
.
- ✔️ : .
Weitere Informationen zu Anlagen finden Sie unter Hinzufügen von Medienanlagen zu Nachrichten.
Verwenden adaptiver Karten
Ein Konversationsbot kann adaptive Karten enthalten, die Geschäftsworkflows vereinfachen. Adaptive Karten bieten umfangreiche anpassbare Text-, Sprach-, Bild-, Schaltflächen- und Eingabefelder. Sie können adaptive Karten in einem Bot erstellen und in mehreren Apps wie Teams, Ihrer Website usw. angezeigt werden.
Weitere Informationen finden Sie unter:
- Adaptive Karten für.
- Teams Karte Referenz für unterstützte Karten.
Der folgende Code zeigt ein Beispiel für das Senden einer einfachen adaptiven Karte:
Beispiel: Senden einer einfachen adaptiven Karte
{
"type": "AdaptiveCard",
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
{
"items": [
{
"size": "large",
"text": " Simple Adaptivecard Example with a Textbox",
"type": "TextBlock",
"weight": "bolder",
"wrap": true
},
],
"spacing": "extraLarge",
"type": "Container",
"verticalContentAlignment": "center"
}
]
}
Senden und Empfangen von Nachrichten
Das Senden und Empfangen von Nachrichten ist die Kernfunktion eines Bots. Es ermöglicht einem Bot Folgendes:
- Senden und Empfangen von Nachrichten
- Aktualisieren und löschen Sie Botnachrichten.
- Vorgeschlagene Aktionen senden.
- Senden von Nachrichten in Teams-Kanaldaten.
In einem Chat ist jede Nachricht ein Activity Objekt vom Typ messageType: message. Wenn jemand eine Nachricht sendet, wird diese von Microsoft Teams an Ihren Bot gesendet. Teams sendet ein JSON-Objekt an den Messagingendpunkt Ihres Bots und lässt nur einen Endpunkt für Messaging zu. Ihr Bot überprüft dann die Nachricht, um ihren Typ zu ermitteln, und antwortet entsprechend.
Grundlegende Unterhaltungen werden über den Bot Framework-Connector verwaltet, bei dem es sich um eine einzelne REST-API handelt. Diese API ermöglicht Es Ihrem Bot, mit Teams und anderen Kanälen zu kommunizieren. Das Bot Builder SDK bietet die folgenden Features:
- Einfacher Zugriff auf den Bot Framework-Connector.
- Tools zum Verwalten des Konversationsflusses und -zustands.
- Einfache Möglichkeiten zum Hinzufügen von Cognitive Services, z. B. Verarbeitung natürlicher Sprache (Natural Language Processing, NLP).
Ihr Bot ruft Mithilfe der Text -Eigenschaft Nachrichten von Teams ab und kann einzelne oder mehrere Antworten an Benutzer zurücksenden.
Weitere Informationen finden Sie unter Benutzerzuordnung für Botnachrichten.
In der folgenden Tabelle sind die Aktivitäten aufgeführt, die Ihr Bot empfangen und maßnahmen ergreifen kann:
| Nachrichtentyp | Nutzdatenobjekt | Bereich |
|---|---|---|
| Empfangen einer Nachrichtenaktivität | Nachrichtenaktivität | Alle |
| Aktivität "Nachricht bearbeiten empfangen" | Aktivität zum Bearbeiten von Nachrichten | Alle |
| Aktivität "Empfangen von Nachrichten wiederherstellen" | Nachrichtenlöschungsaktivität | Alle |
| Aktivität zum vorläufigen Löschen von Nachrichten empfangen | Aktivität für vorläufiges Löschen von Nachrichten | Alle |
Empfangen einer Nachrichtenaktivität
Verwenden Sie die Text -Eigenschaft eines Activity -Objekts, um eine SMS zu empfangen. Verwenden Sie im Aktivitäts-Handler des Bots die Activity des Turn-Kontextobjekts, um eine einzelne Nachrichtenanforderung zu lesen.
Der folgende Code zeigt ein Beispiel für den Empfang einer Nachrichtenaktivität:
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}
Empfangen einer Lesebestätigung
Mit der Einstellung Lesebestätigungen in Teams kann der Absender einer Chatnachricht benachrichtigt werden, wenn seine Nachricht vom Empfänger in Einzel- und Gruppenchats gelesen wurde. Nachdem der Empfänger die Nachricht gelesen hat, wird neben der Nachricht das Angezeigte
angezeigt. Sie haben auch die Möglichkeit, Ihren Bot für den Empfang von Lesebestätigungsereignissen über die Einstellung Lesebestätigungen zu konfigurieren. Das Lesebestätigungsereignis hilft Ihnen, die Benutzererfahrung auf folgende Weise zu verbessern:
Sie können Ihren Bot so konfigurieren, dass er eine Folgenachricht sendet, wenn Ihr App-Benutzer die Nachricht im persönlichen Chat nicht gelesen hat.
Sie können eine Feedbackschleife mithilfe von Lesebestätigungen erstellen, um die Benutzererfahrung Ihres Bots zu optimieren.
Hinweis
- Lesebestätigungen werden nur in Benutzer-zu-Bot-Chatszenarien unterstützt.
- Lesebestätigungen für Bots unterstützen keine Team-, Kanal- und Gruppenchatbereiche.
- Wenn ein Administrator oder Benutzer die Einstellung Lesebestätigungen deaktiviert, empfängt der Bot das Lesebestätigungsereignis nicht.
Stellen Sie Folgendes sicher, um Lesebestätigungsereignisse für Ihren Bot zu empfangen:
- Fügen Sie die RSC-Berechtigung
ChatMessageReadReceipt.Read.Chatwie folgt im App-Manifest hinzu:
"webApplicationInfo": {
"id": "38f0ca43-1c38-4c39-8097e-47f62c686500",
"resource": ""
},
"authorization": {
"permissions": {
"orgwide": [],
"resourceSpecific": [
{
"name": "ChatMessageReadReceipt.Read.Chat",
"type": "Application"
}
]
}
}
Sie können RSC-Berechtigungen auch über Graph-API hinzufügen. Weitere Informationen finden Sie unter consentedPermissionSet.
Überschreiben Sie die -Methode
OnTeamsReadReceiptAsyncmitIsMessageReaddem Handler.Die
IsMessageReadHilfsmethode ist nützlich, um zu bestimmen, ob die Nachricht von den Empfängern gelesen wird. Wenn kleinercompareMessageIdoder gleichLastReadMessageIdist, wurde die Nachricht gelesen. Überschreiben Sie dieOnTeamsReadReceiptAsync-Methode, um Lesebestätigungen mitIsMessageReadder Hilfsmethode zu empfangen:protected override async Task OnTeamsReadReceiptAsync(ReadReceiptInfo readReceiptInfo, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken) { var lastReadMessageId = readReceiptInfo.LastReadMessageId; if (IsMessageRead("{id of the message that you care}", LastReadMessageId)) { await turnContext.SendActivityAsync(MessageFactory.Text("User read the bot's message"), cancellationToken); } }Das folgende Beispiel zeigt eine Ereignisanforderung für Lesebestätigungen, die ein Bot empfängt:
{ "name": "application/vnd.microsoft.readReceipt", "type": "event", "timestamp": "2023-08-16T17:23:11.1366686Z", "id": "f:b4783e72-9d7b-2ed9-ccef-ab446c873007", "channelId": "msteams", "serviceUrl": "https://smba.trafficmanager.net/amer/", "from": { "id": "29:1-8Iuh70W9pRqV8tQK8o2nVjxz33RRGDKLf4Bh7gKnrzN8s7e4vCyrFwjkPbTCX_Co8c4aXwWvq3RBLr-WkkVMw", "aadObjectId": "5b649834-7412-4cce-9e69-176e95a394f5" }, "conversation": { "conversationType": "personal", "tenantId": "6babcaad-604b-40ac-a9d7-9fd97c0b779f", "id": "a:1xlimp68NSUxEqK0ap2rXuwC9ITauHgV2M4RaDPkeRhV8qMaFn-RyilMZ62YiVdqs8pp43yQaRKvv_U2S2gOS5nM-y_pOxVe4BW1qMGPtqD0Bv3pw-nJXF0zhDlZHMZ1Z" }, "recipient": { "id": "28:9901a8b6-4fef-428b-80b1-ddb59361adeb", "name": "Test Bot" }, "channelData": { "tenant": { "id": "6babcaad-604b-40ac-a9d7-9fd97c0b779f" } }, "value": { "lastReadMessageId": "1692206589131" } }Die Administratoreinstellung für Lesebestätigungen oder die Benutzereinstellung ist für den Mandanten aktiviert, damit der Bot die Lesebestätigungsereignisse empfängt. Der Administrator oder der Benutzer muss die Einstellung für Lesebestätigungen aktivieren oder deaktivieren.
Nachdem der Bot in einem Benutzer-zu-Bot-Chatszenario aktiviert wurde, empfängt der Bot sofort ein Lesebestätigungsereignis, wenn der Benutzer die Nachricht des Bots liest. Sie können die Benutzerbindung nachverfolgen, indem Sie die Anzahl der Ereignisse zählen, und Sie können auch eine kontextbezogene Nachricht senden.
Aktivität "Nachricht bearbeiten empfangen"
Wenn Sie eine Nachricht bearbeiten, erhält der Bot eine Benachrichtigung über die Nachrichtenbearbeitungsaktivität.
Um eine Benachrichtigung zur Nachrichtenaktivität in einem Bot zu erhalten, können Sie den Handler überschreiben OnTeamsMessageEditAsync .
Es folgt ein Beispiel für eine Benachrichtigung zur Nachrichtenaktivität bearbeiten mit, wenn eine gesendete Nachricht bearbeitet wird:The following is an example of a edit message activity notification using OnTeamsMessageEditAsync when a sent message is edited:
protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is updated");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Senden einer Nachricht
Um eine SMS zu senden, geben Sie die Zeichenfolge an, die Sie als Aktivität senden möchten. Verwenden Sie im Aktivitätshandler des Bots die Methode des Turn-Kontextobjekts SendActivityAsync , um eine einzelne Nachrichtenantwort zu senden. Verwenden Sie die -Methode des SendActivitiesAsync -Objekts, um mehrere Antworten zu senden.
Der folgende Code zeigt ein Beispiel für das Senden einer Nachricht, wenn ein Benutzer zu einer Unterhaltung hinzugefügt wird:
protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}
Hinweis
- Die Nachrichtenaufteilung erfolgt, wenn eine SMS und eine Anlage in derselben Aktivitätsnutzlast gesendet werden. Teams teilt diese Aktivität in zwei separate Aktivitäten auf, eine mit einer SMS und die andere mit einer Anlage. Da die Aktivität aufgeteilt wird, erhalten Sie nicht die Nachrichten-ID als Antwort, die verwendet wird, um die Nachricht proaktiv zu aktualisieren oder zu löschen . Es wird empfohlen, separate Aktivitäten zu senden, anstatt von der Nachrichtenaufteilung abhängig zu sein.
- Gesendete Nachrichten können lokalisiert werden, um eine Personalisierung bereitzustellen. Weitere Informationen finden Sie unter Lokalisieren Ihrer App.
Nachrichten, die zwischen Benutzern und Bots gesendet werden, enthalten interne Kanaldaten in der Nachricht. Diese Daten ermöglichen es dem Bot, auf diesem Kanal ordnungsgemäß zu kommunizieren. Mit dem Bot Builder SDK können Sie die Nachrichtenstruktur ändern.
Aktivität "Empfangen von Nachrichten wiederherstellen"
Wenn Sie eine Nachricht wiederherstellen, erhält der Bot eine Benachrichtigung über die Wiederherstellen der Nachrichtenaktivität.
Um eine Benachrichtigung zur Wiederherstellen der Nachrichtenaktivität in einem Bot zu erhalten, können Sie den Handler überschreiben OnTeamsMessageUndeleteAsync .
Es folgt ein Beispiel für eine Wiederherstellen einer Nachrichtenaktivitätsbenachrichtigung mit OnTeamsMessageUndeleteAsync , wenn eine gelöschte Nachricht wiederhergestellt wird:
protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is undeleted");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Aktivität zum vorläufigen Löschen von Nachrichten empfangen
Wenn Sie eine Nachricht vorläufig löschen, erhält der Bot eine Benachrichtigung über die Aktivität des vorläufigen Löschens von Nachrichten.
Um eine Meldungsaktivitätsbenachrichtigung für vorläufiges Löschen in einem Bot zu erhalten, können Sie den Handler überschreiben OnTeamsMessageSoftDeleteAsync .
Das folgende Beispiel zeigt eine Meldungsaktivitätsbenachrichtigung mit vorläufigem Löschen, wenn OnTeamsMessageSoftDeleteAsync eine Nachricht vorläufig gelöscht wird:
protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is soft deleted");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Vom Bot gesendete Nachrichten aktualisieren und löschen
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 bots – v3 SDK im Ordner Legacy SDKs der Dokumentation.
Ihr Bot kann Nachrichten nach dem Senden dynamisch aktualisieren, anstatt sie als statische Momentaufnahmen von Daten zu behalten. Nachrichten können auch mithilfe der Bot Framework-Methode DeleteActivity gelöscht werden.
Hinweis
Ein Bot kann keine Nachrichten aktualisieren oder löschen, die vom Benutzer in Microsoft Teams gesendet wurden.
Nachricht aktualisieren
Sie können dynamische Nachrichtenaktualisierungen für Szenarien wie Umfrageaktualisierungen, das Ändern verfügbarer Aktionen nach einem Tastendruck oder jede andere asynchrone Zustandsänderung verwenden.
Es ist nicht erforderlich, dass die neue Nachricht mit dem ursprünglichen Typ übereinstimmt. Wenn die ursprüngliche Nachricht beispielsweise einen Anhang enthielt, kann die neue Nachricht eine einfache Textnachricht sein.
Um eine vorhandene Nachricht zu aktualisieren, übergeben Sie ein neues Activity-Objekt mit der vorhandenen Aktivitäts-ID an die UpdateActivityAsync-Methode der TurnContext-Klasse.
// Send initial message
var response = await turnContext.SendActivityAsync(MessageFactory.Attachment(card.ToAttachment()), cancellationToken);
var activityId = response.Id; // Fetch activity id.
// MessageFactory.Text(): Specifies the type of text data in a message attachment.
var newActivity = MessageFactory.Text("The new text for the activity");
newActivity.Id = activityId;
// UpdateActivityAsync(): A method that can participate in update activity events for the current turn.
await turnContext.UpdateActivityAsync(newActivity, cancellationToken);
Nachdem Sie Nachrichten aktualisiert haben, aktualisieren Sie die vorhandene Karte bei der Schaltflächenauswahl für eingehende Aktivitäten.
Karten aktualisieren
Um die vorhandene Karte bei der Schaltflächenauswahl zu aktualisieren, können Sie ReplyToId von eingehenden Aktivitäten verwenden.
Um eine vorhandene Karte bei der Schaltflächenauswahl zu aktualisieren, übergeben Sie ein neues Activity-Objekt mit aktualisierter Karte und ReplyToId als Aktivitäts-ID an die UpdateActivityAsync-Methode der TurnContext-Klasse.
// Returns a message activity that contains an attachment.
var activity = MessageFactory.Attachment(card.ToAttachment());
activity.Id = turnContext.Activity.ReplyToId;
// A method that can participate in update activity events for the current turn.
await turnContext.UpdateActivityAsync(activity, cancellationToken);
Nachdem Sie Karten aktualisiert haben, können Sie Nachrichten mithilfe des Bot Framework löschen.
Löschen von Nachrichten
Im Bot Framework hat jede Nachricht ihren eindeutigen Aktivitätsbezeichner. Nachrichten können mithilfe der Bot Framework-Methode DeleteActivity gelöscht werden.
Um eine Nachricht zu löschen, übergeben Sie die ID dieser Aktivität an die DeleteActivityAsync-Methode der TurnContext-Klasse.
foreach (var activityId in _list)
{
// When overridden in a derived class, deletes an existing activity in the conversation.
await turnContext.DeleteActivityAsync(activityId, cancellationToken);
}
Vorgeschlagene Aktionen senden
Die vorgeschlagenen Aktionen ermöglichen es Ihrem Bot, Schaltflächen anzuzeigen, die der Benutzer auswählen kann, um Eingaben bereitzustellen. Vorgeschlagene Aktionen verbessern die Benutzerfreundlichkeit, indem sie es dem Benutzer ermöglichen, eine Frage zu beantworten oder eine Auswahl mit auswahl einer Schaltfläche zu treffen, anstatt eine Antwort mit einer Tastatur einzugeben. Wenn der Benutzer eine Schaltfläche auswählt, bleibt sie in den Rich Cards sichtbar und zugänglich, aber nicht für die vorgeschlagenen Aktionen. Dadurch wird verhindert, dass der Benutzer veraltete Schaltflächen innerhalb einer Unterhaltung auswählen kann.
Um einer Nachricht vorgeschlagene Aktionen hinzuzufügen, legen Sie die suggestedActions -Eigenschaft eines Aktivitätsobjekts fest, um die Liste der Karte Aktionsobjekte anzugeben, die die Schaltflächen darstellen, die dem Benutzer angezeigt werden sollen. Weitere Informationen finden Sie unter sugestedActions.
Im Folgenden finden Sie ein Beispiel für die Implementierung und Erfahrung von vorgeschlagenen Aktionen:
"suggestedActions": {
"actions": [
{
"type": "imBack",
"title": "Action 1",
"value": "Action 1"
},
{
"type": "imBack",
"title": "Action 2",
"value": "Action 2"
}
],
"to": [<list of recepientIds>]
}
Im Folgenden wird ein Beispiel für vorgeschlagene Aktionen veranschaulicht:
Hinweis
-
SuggestedActionswerden nur für 1:1-Chatbots mit textbasierten Nachrichten und adaptiven Karten unterstützt. -
SuggestedActionswerden für Chatbots mit Anlagen für jeden Konversationstyp nicht unterstützt. -
imBackist der einzige unterstützte Aktionstyp, und Teams zeigt bis zu sechs vorgeschlagene Aktionen an.
Senden von Nachrichten in Teams-Kanaldaten
Das channelData Objekt enthält Teams-spezifische Informationen und ist eine definitive Quelle für Team- und Kanal-IDs. Optional können Sie diese IDs zwischenspeichern und als Schlüssel für den lokalen Speicher verwenden. Der TeamsActivityHandler im SDK ruft wichtige Informationen aus dem channelData Objekt ab, um es zugänglich zu machen. Sie können jedoch immer über das -Objekt auf die turnContext ursprünglichen Daten zugreifen.
Das channelData -Objekt ist nicht in Nachrichten in persönlichen Unterhaltungen enthalten, da diese außerhalb eines Kanals stattfinden.
Ein typisches channelData Objekt in einer Aktivität, die an Ihren Bot gesendet wird, enthält die folgenden Informationen:
-
eventType: Der Teams-Ereignistyp wird nur in Fällen von Konversationsereignissen in Ihrem Teams-Bot übergeben. -
tenant.id: Microsoft Entra Mandanten-ID, die in allen Kontexten übergeben wird. -
team: Wird nur in Kanalkontexten übergeben, nicht im persönlichen Chat.-
id: GUID für den Kanal. -
name: Name des Teams wird nur in Fällen von Teambenennungsereignissen übergeben.
-
-
channel: Wird nur in Kanalkontexten übergeben, wenn der Bot erwähnt wird, oder für Ereignisse in Kanälen in Teams, in denen der Bot hinzugefügt wird.-
id: GUID für den Kanal. -
name: Kanalname wird nur in Fällen von Kanaländerungsereignissen übergeben.
-
-
channelData.teamsTeamId:Veraltet. Diese Eigenschaft ist nur aus Gründen der Abwärtskompatibilität enthalten. -
channelData.teamsChannelId:Veraltet. Diese Eigenschaft ist nur aus Gründen der Abwärtskompatibilität enthalten.
Der folgende Code zeigt ein Beispiel für ein channelData-Objekt (channelCreated-Ereignis):
"channelData": {
"eventType": "channelCreated",
"tenant": {
"id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
},
"channel": {
"id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
"name": "My New Channel"
},
"team": {
"id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
}
}
Teams-Kanaldaten
Das channelData Objekt enthält Teams-spezifische Informationen und ist eine definitive Quelle für Team- und Kanal-IDs. Optional können Sie diese IDs zwischenspeichern und als Schlüssel für den lokalen Speicher verwenden. Der TeamsActivityHandler im SDK ruft wichtige Informationen aus dem channelData Objekt ab, um es zugänglich zu machen. Sie können jedoch immer über das -Objekt auf die turnContext ursprünglichen Daten zugreifen.
Das channelData -Objekt ist nicht in Nachrichten in persönlichen Unterhaltungen enthalten, da diese außerhalb eines Kanals stattfinden.
Ein typisches channelData Objekt in einer Aktivität, die an Ihren Bot gesendet wird, enthält die folgenden Informationen:
-
eventType: Teams-Ereignistyp wird nur in Fällen von Kanaländerungsereignissen übergeben. -
tenant.id: Microsoft Entra Mandanten-ID, die in allen Kontexten übergeben wird. -
team: Wird nur in Kanalkontexten übergeben, nicht im persönlichen Chat.-
id: GUID für den Kanal. -
name: Name des Teams, das nur in Fällen von übergeben wird (how-to/conversations/subscribe-to-conversation-events.md#team-renamed).
-
-
channel: Wird nur in Kanalkontexten übergeben, wenn der Bot erwähnt wird, oder für Ereignisse in Kanälen in Teams, in denen der Bot hinzugefügt wird.-
id: GUID für den Kanal. -
name: Kanalname wird nur in Fällen von Kanaländerungsereignissen übergeben.
-
-
channelData.teamsTeamId:Veraltet. Diese Eigenschaft ist nur aus Gründen der Abwärtskompatibilität enthalten. -
channelData.teamsChannelId:Veraltet. Diese Eigenschaft ist nur aus Gründen der Abwärtskompatibilität enthalten.
Beispiel für ein channelData-Objekt
Der folgende Code zeigt ein Beispiel für ein channelData-Objekt (channelCreated-Ereignis):
"channelData": {
"eventType": "channelCreated",
"tenant": {
"id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
},
"channel": {
"id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
"name": "My New Channel"
},
"team": {
"id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
}
}
Statuscodes von Bot-Konversations-APIs
Stellen Sie sicher, dass Sie diese Fehler in Ihrer Teams-App entsprechend behandeln. In der folgenden Tabelle sind die Fehlercodes und die Beschreibungen aufgeführt, unter denen die Fehler generiert werden:
| Statuscode | Fehlercode und Meldungswerte | Beschreibung | Wiederholungsanforderung | Entwickleraktion |
|---|---|---|---|---|
| 400 |
Code: Bad Argument Meldung: *szenariospezifisch |
Vom Bot bereitgestellte ungültige Anforderungsnutzlast. Weitere Informationen finden Sie in der Fehlermeldung. | Nein | Erneutes Auswerten der Anforderungsnutzlast auf Fehler. Überprüfen Sie die zurückgegebene Fehlermeldung auf Details. |
| 401 |
Code: BotNotRegistered Meldung: Für diesen Bot wurde keine Registrierung gefunden. |
Die Registrierung für diesen Bot wurde nicht gefunden. | Nein | Überprüfen Sie die Bot-ID und das Kennwort. Stellen Sie sicher, dass die Bot-ID (Microsoft Entra ID) im Teams-Entwicklerportal oder über die Azure-Botkanalregistrierung in Azure mit aktiviertem Teams-Kanal registriert ist. |
| 403 |
Code: BotDisabledByAdmin Meldung: Der Mandantenadministrator hat diesen Bot deaktiviert. |
Admin blockierte Interaktionen zwischen Dem Benutzer und der Bot-App. Admin muss die App für den Benutzer innerhalb von App-Richtlinien zulassen. Weitere Informationen finden Sie unter App-Richtlinien. | Nein | Beenden Sie die Veröffentlichung in einer Unterhaltung, bis die Interaktion mit dem Bot explizit von einem Benutzer in der Unterhaltung initiiert wurde, der angibt, dass der Bot nicht mehr blockiert ist. |
| 403 |
Code: BotNotInConversationRoster Meldung: Der Bot ist nicht Teil der Konversationsliste. |
Der Bot ist nicht Teil der Unterhaltung. Die App muss in der Unterhaltung neu installiert werden. | Nein | Bevor Sie versuchen, eine weitere Konversationsanforderung zu senden, warten Sie auf ein installationUpdate Ereignis, das angibt, dass der Bot erneut hinzugefügt wird. |
| 403 |
Code: ConversationBlockedByUser Meldung: Der Benutzer hat die Konversation mit dem Bot blockiert. |
Der Benutzer hat den Bot im persönlichen Chat oder in einem Kanal über Moderationseinstellungen blockiert. | Nein | Löschen Sie die Konversation aus dem Cache. Beenden Sie den Versuch, In Unterhaltungen zu posten, bis die Interaktion mit dem Bot explizit von einem Benutzer in der Unterhaltung initiiert wurde, was darauf hinweist, dass der Bot nicht mehr blockiert wird. |
| 403 |
Code: ForbiddenOperationException Meldung: Bot ist nicht im persönlichen Bereich des Benutzers installiert |
Proaktive Nachrichten werden von einem Bot gesendet, der nicht in einem persönlichen Bereich installiert ist. | Nein | Bevor Sie versuchen, eine weitere Konversationsanforderung zu senden, installieren Sie die App im persönlichen Bereich. |
| 403 |
Code: InvalidBotApiHost Meldung: Ungültiger Bot-API-Host. Rufen Sie für GCC-Mandanten auf https://smba.infra.gcc.teams.microsoft.com. |
Der Bot hat den öffentlichen API-Endpunkt für eine Konversation aufgerufen, die zu einem GCC-Mandanten gehört. | Nein | Aktualisieren Sie die Dienst-URL für die Konversation auf , https://smba.infra.gcc.teams.microsoft.com und wiederholen Sie die Anforderung. |
| 403 |
Code: NotEnoughPermissions Meldung: *szenariospezifisch |
Der Bot verfügt nicht über die erforderlichen Berechtigungen zum Ausführen der angeforderten Aktion. | Nein | Bestimmen Sie die erforderliche Aktion anhand der Fehlermeldung. |
| 404 |
Code: ActivityNotFoundInConversation Meldung: Unterhaltung nicht gefunden. |
Die angegebene Nachrichten-ID konnte in der Unterhaltung nicht gefunden werden. Die Nachricht ist nicht vorhanden, oder sie wird gelöscht. | Nein | Überprüfen Sie, ob die gesendete Nachrichten-ID ein erwarteter Wert ist. Entfernen Sie die ID, wenn sie zwischengespeichert wurde. |
| 404 |
Code: ConversationNotFound Meldung: Unterhaltung nicht gefunden. |
Die Konversation wurde nicht gefunden, da sie nicht vorhanden ist oder gelöscht wird. | Nein | Überprüfen Sie, ob die gesendete Konversations-ID ein erwarteter Wert ist. Entfernen Sie die ID, wenn sie zwischengespeichert wurde. |
| 412 |
Code: PreconditionFailed Meldung: Fehler bei der Vorbedingung. Versuchen Sie es erneut. |
Eine Vorbedingung ist für eine unserer Abhängigkeiten aufgrund mehrerer gleichzeitiger Vorgänge in derselben Konversation fehlgeschlagen. | Ja | Wiederholen Sie den Vorgang mit exponentiellem Backoff. |
| 413 |
Code: MessageSizeTooBig Nachricht: Die Nachrichtengröße ist zu groß. |
Die Größe der eingehenden Anforderung war zu groß. Weitere Informationen finden Sie unter Formatieren Ihrer Botnachrichten. | Nein | Reduzieren Sie die Nutzlastgröße. |
| 429 |
Code: Throttled Meldung: Zu viele Anforderungen. Gibt auch den Zeitpunkt zurück, nach dem versucht werden soll. |
Zu viele Anforderungen, die vom Bot gesendet werden. Weitere Informationen finden Sie unter Ratenlimit. | Ja | Versuchen Sie es mit dem Retry-After Header, um die Backoffzeit zu bestimmen. |
| 500 |
Code: ServiceError Meldung: *verschiedene |
Internal server error. (Interner Serverfehler) | Nein | Melden Sie das Problem in der Entwicklercommunity. |
| 502 |
Code: ServiceError Meldung: *verschiedene |
Dienstabhängigkeitsproblem. | Ja | Wiederholen Sie den Vorgang mit exponentiellem Backoff. Wenn das Problem weiterhin besteht, melden Sie das Problem in der Entwicklercommunity. |
| 503 | Der Dienst ist nicht verfügbar. | Ja | Wiederholen Sie den Vorgang mit exponentiellem Backoff. Wenn das Problem weiterhin besteht, melden Sie das Problem in der Entwicklercommunity. | |
| 504 | Gatewaytimeout. | Ja | Wiederholen Sie den Vorgang mit exponentiellem Backoff. Wenn das Problem weiterhin besteht, melden Sie das Problem in der Entwicklercommunity. |
Anleitung zur Wiederholung von Statuscodes
Die allgemeine Wiederholungsanleitung für jeden status Code ist in der folgenden Tabelle aufgeführt. Bot muss vermeiden, dass status Codes wiederholt werden, die nicht angegeben sind:
| Statuscode | Wiederholungsstrategie |
|---|---|
| 403 | Wiederholen Sie den Vorgang, indem Sie die GCC-API https://smba.infra.gcc.teams.microsoft.com für InvalidBotApiHostaufrufen. |
| 412 | Wiederholen Sie den Vorgang mit exponentiellem Backoff. |
| 429 | Versuchen Sie es mit dem Retry-After -Header, um die Wartezeit in Sekunden und zwischen Anforderungen zu bestimmen, falls verfügbar. Wiederholen Sie andernfalls nach Möglichkeit das exponentielle Backoff mit der Thread-ID. |
| 502 | Wiederholen Sie den Vorgang mit exponentiellem Backoff. |
| 503 | Wiederholen Sie den Vorgang mit exponentiellem Backoff. |
| 504 | Wiederholen Sie den Vorgang mit exponentiellem Backoff. |
Anfordern von Kopfzeilen des Bots
Die aktuellen ausgehenden Anforderungen an den Bot enthalten im Header oder der URL keine Informationen, die Bots dabei helfen, den Datenverkehr weiterzuleiten, ohne die gesamte Nutzlast zu entpacken. Die Aktivitäten werden über eine URL ähnlich wie https://< your_domain>/api/messages an den Bot gesendet. Anforderungen werden empfangen, um die Unterhaltungs-ID und Mandanten-ID in den Headern anzuzeigen.
Anforderungsheaderfelder
Zwei nicht standardmäßige Anforderungsheaderfelder werden allen Anforderungen hinzugefügt, die an Bots gesendet werden, sowohl für asynchronen Fluss als auch für synchronen Fluss. Die folgende Tabelle enthält die Anforderungsheaderfelder und deren Werte:
| Feldschlüssel | Wert |
|---|---|
| x-ms-conversation-id | Die Unterhaltungs-ID, die der Anforderungsaktivität entspricht, falls zutreffend und bestätigt oder überprüft. |
| x-ms-tenant-id | Die Mandanten-ID, die der Unterhaltung in der Anforderungsaktivität entspricht. |
Wenn die Mandanten- oder Konversations-ID nicht in der Aktivität vorhanden ist oder dienstseitig nicht überprüft wurde, ist der Wert leer.
Nur erwähnte Nachrichten empfangen
Damit Ihre Bots nur die Kanal- oder Chatnachrichten abrufen können, in denen Sich Ihr Bot befindet @mentioned, müssen Sie die Nachrichten filtern. Verwenden Sie den folgenden Codeausschnitt, damit Ihr Bot nur die Nachricht empfangen kann, in der er sich befindet @mentioned:
// When ChannelMessage.Read.Group or ChatMessage.Read.Chat RSC is in the app manifest, this method is called even when bot is not @mentioned.
// This code snippet allows the bot to ignore all messages that do not @mention the bot.
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Ignore the message if bot was not mentioned.
// Remove this if block to process all messages received by the bot.
if (!turnContext.Activity.GetMentions().Any(mention => mention.Mentioned.Id.Equals(turnContext.Activity.Recipient.Id, StringComparison.OrdinalIgnoreCase)))
{
return;
}
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text("Using RSC the bot can receive messages across channels or chats in team without being @mentioned."));
}
Wenn Ihr Bot alle Nachrichten empfangen soll, müssen Sie die @mention Nachrichten nicht filtern.
Schrittweise Anleitung
Befolgen Sie die Schritt-für-Schritt-Anleitung, um einen Teams-Konversationsbot zu erstellen.
Nächster Schritt
Kanal- und Gruppenchatunterhaltungen mit einem Bot