Senden und Empfangen von Nachrichten mit der Bot Connector-APISend and receive messages with the Bot Connector API

Der Bot Connector-Dienst ermöglicht einem Bot, über verschiedene Kanäle wie E-Mail, Slack und andere zu kommunizieren.The Bot Connector service enables a bot to communicate across multiple channels such as Email, Slack, and more. Er ermöglicht die Kommunikation zwischen Bot und Benutzer, indem Aktivitäten vom Bot zum Kanal und vom Kanal zum Bot weitergeleitet werden.It facilitates communication between bot and user, by relaying activities from bot to channel and from channel to bot. 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.Every activity contains information used for routing the message to the appropriate destination along with information about who created the message, the context of the message, and the recipient of the message. 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.This article describes how to use the Bot Connector service to exchange message activities between bot and user on a channel.

Beantworten einer NachrichtReply to a message

Erstellen einer AntwortCreate a reply

Wenn der Benutzer eine Nachricht an Ihren Bot sendet, empfängt der Bot die Nachricht als Aktivität-Objekt vom Typ message.When the user sends a message to your bot, your bot will receive the message as an Activity object of type 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:To create a reply to a user's message, create a new Activity object and start by setting these properties:

EigenschaftProperty WertValue
Konversation (conversation)conversation Legen Sie diese Eigenschaft auf den Inhalt der conversation-Eigenschaft in der Nachricht des Benutzers fest.Set this property to the contents of the conversation property in the user's message.
fromfrom Legen Sie diese Eigenschaft auf den Inhalt der recipient-Eigenschaft in der Nachricht des Benutzers fest.Set this property to the contents of the recipient property in the user's message.
localelocale Legen Sie diese Eigenschaft auf den Inhalt der locale-Eigenschaft in der Nachricht des Benutzers fest (sofern angegeben).Set this property to the contents of the locale property in the user's message, if specified.
recipientrecipient Legen Sie diese Eigenschaft auf den Inhalt der from-Eigenschaft in der Nachricht des Benutzers fest.Set this property to the contents of the from property in the user's message.
replyToIdreplyToId Legen Sie diese Eigenschaft auf den Inhalt der id-Eigenschaft in der Nachricht des Benutzers fest.Set this property to the contents of the id property in the user's message.
typetype Legen Sie diese Eigenschaft auf message fest.Set this property to message.

Legen Sie als Nächstes die Eigenschaften fest, die die Informationen enthalten, die Sie dem Benutzer mitteilen möchten.Next, set the properties that specify the information that you want to communicate to the user. 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.For example, you can set the text property to specify the text to be displayed in the message, set the speak property to specify text to be spoken by your bot, and set the attachments property to specify media attachments or rich cards to include in the message. Ausführliche Informationen zu häufig verwendeten Nachrichteneigenschaften finden Sie unter Erstellen von Nachrichten.For detailed information about commonly-used message properties, see Create messages.

Senden der AntwortSend the reply

Verwenden Sie die serviceUrl-Eigenschaft in der eingehenden Aktivität zum Identifizieren des Basis-URI, an den Ihr Bot die Antwort ausgeben sollte.Use the serviceUrl property in the incoming activity to identify the base URI that your bot should use to issue its response.

Um die Antwort zu senden, geben Sie diese Anforderung aus:To send the reply, issue this request:

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.In this request URI, replace {conversationId} with the value of the conversation object's id property within your (reply) Activity and replace {activityId} with the value of the replyToId property within your (reply) Activity. Legen Sie den Text der Anforderung auf das Aktivität-Objekt fest, das Sie für Ihre Antwort erstellt haben.Set the body of the request to the Activity object that you created to represent your reply.

Das folgende Beispiel zeigt eine Anforderung, die eine einfache Nur-Text-Antwort auf eine Nachricht eines Benutzers sendet.The following example shows a request that sends a simple text-only reply to a user's message. In dieser Beispielanforderung stellt https://smba.trafficmanager.net/apis den Basis-URI dar. Der Basis-URI für Anforderungen, die Ihr Bot ausgibt, kann ein anderer sein.In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/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) NachrichtSend a (non-reply) message

Ein Großteil der Nachrichten, die Ihr Bot sendet, sind Antworten auf vom Benutzer empfangene Meldungen.A majority of the messages that your bot sends will be in reply to messages that it receives from the user. Zu bestimmten Zeiten muss der Bot jedoch eine Nachricht an die Konversation senden, die keine direkte Antwort auf eine Nachricht des Benutzers ist.However, there may be times when your bot needs to send a message to the conversation that is not a direct reply to any message from the user. Beispielsweise muss der Bot möglicherweise ein neues Konversationsthema starten oder eine Verabschiedungsnachricht am Ende der Konversation senden.For example, your bot may need to start a new topic of conversation or send a goodbye message at the end of the conversation.

Um eine Nachricht an eine Konversation, die keine direkte Antwort auf eine Nachricht des Benutzers ist, zu senden, geben Sie diese Anforderung aus:To send a message to a conversation that is not a direct reply to any message from the user, issue this request:

POST /v3/conversations/{conversationId}/activities

Ersetzen Sie in diesem Anforderungs-URI {conversationId} durch die ID der Konversation.In this request URI, replace {conversationId} with the ID of the conversation.

Legen Sie den Text der Anforderung auf ein Aktivität-Objekt fest, das Sie für Ihre Antwort erstellen.Set the body of the request to an Activity object that you create to represent your reply.

Hinweis

In Bot Framework ist die Anzahl der Nachrichten, die ein Bot senden kann, nicht eingeschränkt.The Bot Framework does not impose any restrictions on the number of messages that a bot may send. Die meisten Kanäle erzwingen jedoch Drosselungslimits, damit Bots nicht eine große Anzahl von Nachrichten innerhalb kurzer Zeit senden.However, most channels enforce throttling limits to restrict bots from sending a large number of messages in a short period of time. Wenn die Bots mehrere Nachrichten in schneller Folge senden, kann der Kanal darüber hinaus die Nachrichten nicht immer in der richtigen Reihenfolge rendern.Additionally, if the bot sends multiple messages in quick succession, the channel may not always render the messages in the proper sequence.

Starten einer UnterhaltungStart a conversation

Zu bestimmten Zeiten muss der Bot eine Konversation mit einem oder mehreren Benutzern initiieren.There may be times when your bot needs to initiate a conversation with one or more users. 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.To start a conversation with a user on a channel, your bot must know its account information and the user's account information on that channel.

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).If your bot may need to start conversations with its users in the future, cache user account information, other relevant information such as user preferences and locale, and the service URL (to use as the base URI in the Start Conversation request).

Um eine Konversation zu starten, geben Sie diese Anforderung aus:To start a conversation, issue this request:

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.Set the body of the request to a ConversationParameters object that specifies your bot's account information and the account information of the user(s) that you want to include in the conversation.

Hinweis

Nicht alle Kanäle unterstützen Gruppenkonversationen.Not all channels support group conversations. 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.Consult the channel's documentation to determine whether a channel supports group conversations and to identify the maximum number of participants that a channel allows in a conversation.

Das folgende Beispiel zeigt eine Anforderung zum Starten einer Konversation.The following example shows a request that starts a conversation. In dieser Beispielanforderung stellt https://smba.trafficmanager.net/apis den Basis-URI dar. Der Basis-URI für Anforderungen, die Ihr Bot ausgibt, kann ein anderer sein.In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. Weitere Informationen zum Festlegen des Basis-URI finden Sie in der API-Referenz.For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/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.If the conversation is established with the specified users, the response will contain an ID that identifies the conversation.

{
    "id": "abcd1234"
}

Ihr Bot kann mit dieser Konversations-ID dann an die Benutzer in der Konversation eine Nachricht senden.Your bot can then use this conversation ID to send a message to the user(s) within the conversation.

Zusätzliche RessourcenAdditional resources