Senden und Empfangen von Nachrichten mit der Bot Connector-API
Der Bot Connector-Dienst ermöglicht einem Bot, über verschiedene Kanäle wie E-Mail, Slack und andere zu kommunizieren. Er ermöglicht die Kommunikation zwischen Bot und Benutzer, indem Aktivitäten vom Bot zum Kanal und vom Kanal zum Bot weitergeleitet werden. Jede Aktivität enthält Informationen für die Weiterleitung der Nachricht an das passende Ziel zusammen mit Informationen zum Ersteller der Nachricht, dem Kontext der Nachricht und dem Empfänger der Nachricht. In diesem Artikel wird beschrieben, wie mit dem Bot Connector-Dienst Aktivitäten vom Typ Nachricht zwischen dem Bot und dem Benutzer in einem Kanal ausgetauscht werden.
Beantworten einer Nachricht
Erstellen einer Antwort
Wenn der Benutzer eine Nachricht an Ihren Bot sendet, empfängt der Bot die Nachricht als Aktivität-Objekt vom Typ message. Um eine Antwort auf die Nachricht eines Benutzers zu erstellen, generieren Sie ein neues Activity-Objekt. Legen Sie dazu zunächst die folgenden Eigenschaften fest:
| Eigenschaft | Wert |
|---|---|
| Konversation (conversation) | Legen Sie diese Eigenschaft auf den Inhalt der conversation-Eigenschaft in der Nachricht des Benutzers fest. |
| from | Legen Sie diese Eigenschaft auf den Inhalt der recipient-Eigenschaft in der Nachricht des Benutzers fest. |
| locale | Legen Sie diese Eigenschaft auf den Inhalt der locale-Eigenschaft in der Nachricht des Benutzers fest (sofern angegeben). |
| recipient | Legen Sie diese Eigenschaft auf den Inhalt der from-Eigenschaft in der Nachricht des Benutzers fest. |
| replyToId | Legen Sie diese Eigenschaft auf den Inhalt der id-Eigenschaft in der Nachricht des Benutzers fest. |
| type | Legen Sie diese Eigenschaft auf message fest. |
Legen Sie als Nächstes die Eigenschaften fest, die die Informationen enthalten, die Sie dem Benutzer mitteilen möchten. Sie können beispielsweise mit der text-Eigenschaft den in der Nachricht anzuzeigenden Text und mit der speak-Eigenschaft den durch den Bot zu sprechenden Text festlegen und mit der attachments-Eigenschaft Medienanhänge oder Rich Cards angeben, die in die Nachricht eingeschlossen werden sollen. Ausführliche Informationen zu häufig verwendeten Nachrichteneigenschaften finden Sie unter Erstellen von Nachrichten.
Senden der Antwort
Verwenden Sie die serviceUrl-Eigenschaft in der eingehenden Aktivität zum Identifizieren des Basis-URI, an den Ihr Bot die Antwort ausgeben sollte.
Um die Antwort zu senden, geben Sie diese Anforderung aus:
POST /v3/conversations/{conversationId}/activities/{activityId}
Ersetzen Sie in diesem Anforderungs-URI {conversationId} durch den Wert der id-Eigenschaft des conversation-Objekts in der (Antwort-)Aktivität, und ersetzen Sie {activityId} durch den Wert der replyToId-Eigenschaft in der (Antwort-)Aktivität. Legen Sie den Text der Anforderung auf das Aktivität-Objekt fest, das Sie für Ihre Antwort erstellt haben.
Das folgende Beispiel zeigt eine Anforderung, die eine einfache Nur-Text-Antwort auf eine Nachricht eines Benutzers sendet. In dieser Beispielanforderung stellt https://smba.trafficmanager.net/teams den Basis-URI dar. Der Basis-URI für Anforderungen, die Ihr Bot ausgibt, kann ein anderer sein. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "Pepper's News Feed"
},
"conversation": {
"id": "abcd1234",
"name": "Convo1"
},
"recipient": {
"id": "1234abcd",
"name": "SteveW"
},
"text": "My bot's reply",
"replyToId": "5d5cdc723"
}
Senden einer (nicht als Antwort ausgelegten) Nachricht
Ein Großteil der Nachrichten, die Ihr Bot sendet, sind Antworten auf vom Benutzer empfangene Meldungen. Es kann jedoch vorkommen, dass Ihr Bot eine Nachricht an die Unterhaltung senden muss, die keine direkte Antwort auf eine Nachricht des Benutzers ist. Beispielsweise muss der Bot möglicherweise ein neues Konversationsthema starten oder eine Verabschiedungsnachricht am Ende der Konversation senden.
Um eine Nachricht an eine Unterhaltung zu senden, die keine direkte Antwort auf eine Nachricht des Benutzers ist, geben Sie diese Anforderung aus:
POST /v3/conversations/{conversationId}/activities
Ersetzen Sie in diesem Anforderungs-URI {conversationId} durch die ID der Konversation.
Legen Sie den Text der Anforderung auf ein Aktivität-Objekt fest, das Sie für Ihre Antwort erstellen.
Hinweis
Das Bot Framework erzwingt keine Einschränkungen für die Anzahl der Nachrichten, die ein Bot senden kann. Die meisten Kanäle erzwingen jedoch Drosselungslimits, damit Bots nicht eine große Anzahl von Nachrichten innerhalb kurzer Zeit senden. Wenn die Bots mehrere Nachrichten in schneller Folge senden, kann der Kanal darüber hinaus die Nachrichten nicht immer in der richtigen Reihenfolge rendern.
Starten einer Unterhaltung
Zu bestimmten Zeiten muss der Bot eine Konversation mit einem oder mehreren Benutzern initiieren. Um eine Konversation mit einem Benutzer in einem Kanal zu starten, muss Ihr Bot dessen Kontoinformationen und die Kontoinformationen des Benutzers in diesem Kanal kennen.
Tipp
Wenn Ihr Bot möglicherweise zukünftig Konversationen mit Benutzern starten muss, speichern Sie Benutzerkontoinformationen, weitere relevante Informationen wie Benutzereinstellungen und das Gebietsschema sowie die Dienst-URL (zur Verwendung als Basis-URI in der Anforderung zum Starten der Konversation).
Um eine Konversation zu starten, geben Sie diese Anforderung aus:
POST /v3/conversations
Legen Sie den Hauptteil der Anforderung auf ein ConversationParameters-Objekt fest, das die Kontoinformationen des Bots und die Kontoinformationen der Benutzer angibt, die in die Konversation aufgenommen werden sollen.
Hinweis
Nicht alle Kanäle unterstützen Gruppenkonversationen. Lesen Sie die Dokumentation des Kanals, um zu ermitteln, ob ein Kanal Gruppenkonversationen unterstützt, und die maximale Anzahl von Teilnehmern herauszufinden, die ein Kanal in einer Konversation zulässt.
Das folgende Beispiel zeigt eine Anforderung zum Starten einer Konversation. In dieser Beispielanforderung stellt https://smba.trafficmanager.net/teams den Basis-URI dar. Der Basis-URI für Anforderungen, die Ihr Bot ausgibt, kann ein anderer sein. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.
POST https://smba.trafficmanager.net/teams/v3/conversations
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"bot": {
"id": "12345678",
"name": "bot's name"
},
"isGroup": false,
"members": [
{
"id": "1234abcd",
"name": "recipient's name"
}
],
"topicName": "News Alert"
}
Wenn die Konversation mit den angegebenen Benutzern eingerichtet wurde, enthält die Antwort eine ID, die die Konversation identifiziert.
{
"id": "abcd1234"
}
Ihr Bot kann mit dieser Konversations-ID dann an die Benutzer in der Konversation eine Nachricht senden.