在 Direct Line API 3.0 中開始交談Start a conversation in Direct Line API 3.0

直接線路對話是由用戶端明確地開啟,且只要 Bot 和用戶端在參與且具有有效認證,對話就會繼續執行。Direct Line conversations are explicitly opened by clients and may run as long as the bot and client participate and have valid credentials. 對話開啟時,Bot 和用戶端可以傳送訊息。While the conversation is open, both the bot and client may send messages. 可以有超過一個用戶端連線到指定對話,且每個用戶端都可以代表多個使用者參與對話。More than one client may connect to a given conversation and each client may participate on behalf of multiple users.

開啟新的對話Open a new conversation

若要從您的用戶端開啟新對話,請對 /v3/directline/conversations 端點發出 POST。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

下列程式碼片段提供開始對話要求和回應的範例。The following snippets provide an example of the start conversation request and response.

要求Request

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

回應Response

如果要求成功,回應將會包含對話識別碼、權杖、一個表示直到權杖過期前秒數的值,以及用戶端可用來透過 WebSocket 資料流接收活動的資料流 URL。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..."
}

一般來說,會使用「開始對話」要求來開啟新的交談,並在新的交談成功啟動時傳回 HTTP 201 狀態碼。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. 但是,如果用戶端使用先前用來啟動交談作業的標頭中的 Direct Line token 來提交開始對話要求 Authorization ,則會傳回 HTTP 200 狀態碼,指出要求是可接受的,但未建立任何交談 (因為它已經存在) 。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).

提示

您有 60 秒的時間可以連線到 WebSocket 資料流 URL。You have 60 seconds to connect to the WebSocket stream URL. 如果無法在這段時間內建立連線,您可以重新連線到對話,以產生新的資料流 URL。If the connection cannot be established during this time, you can reconnect to the conversation to generate a new stream URL.

開始對話與產生權杖Start conversation versus generate token

開始交談作業 (POST /v3/directline/conversations) 類似于 產生權杖 POST /v3/directline/tokens/generate 作業 () 在這兩個作業都會傳回 token 可用於存取單一對話的。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. 不過,開始對話作業也會開始對話、與 bot 連線,並建立 WebSocket 串流 URL,而產生權杖作業不會執行上述任何動作。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.

如果您想要立即開始與用戶端的對話,請使用「開始對話」作業。If you intend to start the conversation immediately with your client, use the start conversation operation. 如果您計畫要將權杖散發給用戶端,並希望它們起始交談,請改用 產生權杖 作業。If you plan to distribute the token to clients and want them to initiate the conversation, use the generate token operation instead.

其他資源Additional resources