Starten einer Konversation in der Direct Line-API 3,0Start a conversation in Direct Line API 3.0

Direct Line-Unterhaltungen werden explizit von Clients geöffnet und können solange ausgeführt werden, wie Bot und Client daran teilnehmen und gültige Anmeldeinformationen aufweisen.Direct Line conversations are explicitly opened by clients and may run as long as the bot and client participate and have valid credentials. Solange die Unterhaltung geöffnet ist, können der Bot und der Client Nachrichten senden.While the conversation is open, both the bot and client may send messages. Es können mehrere Clients eine Verbindung mit einer bestimmten Unterhaltung herstellen, und jeder Client kann im Namen mehrerer Benutzer teilnehmen.More than one client may connect to a given conversation and each client may participate on behalf of multiple users.

Öffnen einer neuen UnterhaltungOpen a new conversation

Wenn Sie eine neue Konversation über Ihren Client beginnen möchten, senden Sie eine POST-Anforderung an den Endpunkt „/v3/directline/conversations“ aus.To open a new conversation from your client, issue POST to the /v3/directline/conversations endpoint.

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer SECRET_OR_TOKEN

Die folgenden Code Ausschnitte enthalten ein Beispiel für die Anforderung und die Antwort zum Starten der Konversation.The following snippets provide an example of the start conversation request and response.

AnforderungRequest

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

AntwortResponse

Wenn die Anforderung erfolgreich war, enthält die Antwort eine ID für die Unterhaltung, ein Token, einen Wert, der die Anzahl von Sekunden bis zum Ablauf des Tokens angibt, und eine Stream-URL, mit der der Client Aktivitäten über den WebSocket-Stream empfangen kann.If the request is successful, the response will contain an ID for the conversation, a token, a value that indicates the number of seconds until the token expires, and a stream URL that the client may use to receive activities via WebSocket stream.

HTTP/1.1 201 Created
[other headers]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
  "streamUrl": "https://directline.botframework.com/v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
}

In der Regel wird eine Start Conversation-Anforderung verwendet, um eine neue Konversation zu öffnen, und ein http 201 -Statuscode wird zurückgegeben, wenn die neue Konversation erfolgreich gestartet wurde.Typically, a start conversation request is used to open a new conversation and an HTTP 201 status code is returned if the new conversation is successfully started. Wenn ein Client jedoch eine Start-Konversations Anforderung mit einem direkten Zeilen Token in der Kopfzeile übermittelt, die Authorization zuvor zum Starten einer Konversation mithilfe des Vorgangs zum Starten der Konversation verwendet wurde, wird ein http 200 -Statuscode zurückgegeben, um anzugeben, dass die Anforderung akzeptabel war, aber es wurde keine Konversation erstellt (da Sie bereits vorhanden war).However, if a client submits a start conversation request with a Direct Line token in the Authorization header that has previously been used to start a conversation using the start conversation operation, an HTTP 200 status code will be returned to indicate that the request was acceptable but no conversation was created (as it already existed).

Tipp

Sie haben 60 Sekunden, um eine Verbindung mit der WebSocket-Stream-URL herzustellen.You have 60 seconds to connect to the WebSocket stream URL. Wenn die Verbindung in diesem Zeitraum nicht hergestellt werden kann, können Sie erneut eine Verbindung mit der Unterhaltung herstellen, um eine neue Stream-URL zu generieren.If the connection cannot be established during this time, you can reconnect to the conversation to generate a new stream URL.

Konversation starten und Token generierenStart conversation versus generate token

Der Vorgang zum Starten der Konversation ( POST /v3/directline/conversations ) ähnelt dem Vorgang zum Generieren von Token ( POST /v3/directline/tokens/generate ), da beide Vorgänge einen zurückgeben token , der für den Zugriff auf eine einzelne Konversation verwendet werden kann.The start conversation operation (POST /v3/directline/conversations) is similar to the generate token operation (POST /v3/directline/tokens/generate) in that both operations return a token that can be used to access a single conversation. Der Vorgang zum Starten der Konversation startet jedoch auch die Konversation, kontaktiert den bot und erstellt eine WebSocket-Datenstrom-URL, während der Vorgang zum Generieren von Token keines dieser Aktionen bewirkt.However, the start conversation operation also starts the conversation, contacts the bot, and creates a WebSocket stream URL, whereas the generate token operation does none of these things.

Wenn Sie beabsichtigen, die Konversation sofort mit Ihrem Client zu starten, verwenden Sie den Vorgang zum Starten der Konversation.If you intend to start the conversation immediately with your client, use the start conversation operation. Wenn Sie planen, das Token an Clients zu verteilen und die Konversation initiieren möchten, verwenden Sie stattdessen den Vorgang zum Generieren von Token .If you plan to distribute the token to clients and want them to initiate the conversation, use the generate token operation instead.

Zusätzliche RessourcenAdditional resources