將活動傳送至 Direct Line API 3.0 中的 Bot
使用 Direct Line 3.0 通訊協定時，用戶端與 Bot 可交換許多不同類型的活動，包括訊息活動、輸入活動，以及 Bot 所支援的自訂活動。 對於每個要求，用戶端可傳送一個活動。
傳送活動
若要將活動傳送至 Bot，用戶端必須建立活動物件以定義活動，然後在要求本文中指定活動物件，並對 https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities 發出 POST 要求。
下列程式碼片段提供「傳送活動」要求和回應的範例。
要求
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]
{
"locale": "en-EN",
"type": "message",
"from": {
"id": "user1"
},
"text": "hello"
}
回應
當活動傳遞至 Bot 時，服務會以反映 Bot 狀態碼的 HTTP 狀態碼來回應。 如果 Bot 產生錯誤，系統會將 HTTP 502 回應 (「錯誤的閘道」) 傳回至用戶端，以回應其「傳送活動」要求。
注意
這可能是因為未使用正確的權杖所造成。 只有針對開始對話所接收的權杖可以用來傳送活動。
如果 POST 成功，則回應會包含 JSON 承載，指定已傳送至 Bot 的活動識別碼。
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
傳送活動要求/回應的時間總計
將訊息 POST 至 Direct Line 對話的時間總計，是以下幾項的總和：
- HTTP 要求從用戶端到 Direct Line 服務的傳輸時間
- Direct Line 中的內部處理時間 (通常少於 120 毫秒)
- 從 Direct Line 服務到 Bot 的傳輸時間
- Bot 內的處理時間
- HTTP 回應回到用戶端的傳輸時間
將附件傳送至 Bot
在某些情況下，用戶端可能需要將影像或文件之類的附件傳送至 Bot。 用戶端可藉由在它要使用 POST /v3/directline/conversations/{conversationId}/activities 傳送的活動物件內為附件指定 URL，或藉由使用 POST /v3/directline/conversations/{conversationId}/upload 來上傳附件，將附件傳送至 Bot。
依 URL 傳送附件
若要使用 POST /v3/directline/conversations/{conversationId}/activities 傳送隨附於活動物件的一或多個附件，只需將一或多個附件物件包含在活動物件內，並設定每個附件物件的 contentUrl 屬性以指定附件的 HTTP、HTTPS 或 data URI 即可。
藉由上傳來傳送附件
常常用戶端的裝置上有影像或文件要傳送至 Bot，但卻沒有對應至這些檔案的 URL。 在此情況下，用戶端可以發出 POST /v3/directline/conversations/{conversationId}/upload 要求，以藉由上傳將附件傳送至 Bot。 要求的格式和內容，將取決於用戶端是要傳送單一附件還是傳送多個附件。
藉由上傳來傳送單一附件
若要藉由上傳來傳送單一附件，請發出下列要求：
POST https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload?userId={userId}
Authorization: Bearer SECRET_OR_TOKEN
Content-Type: TYPE_OF_ATTACHMENT
Content-Disposition: ATTACHMENT_INFO
[other headers]
[file content]
在此要求 URI 中，請將 {conversationId} 取代為對話的識別碼，並將 {userId} 取代為訊息傳送者的使用者識別碼。
userId 是必要參數。 在要求標頭中，請設定 Content-Type 以指定附件的類型，並設定 Content-Disposition 以指定附件的檔案名稱。
下列程式碼片段提供「傳送 (單一) 附件」要求和回應的範例。
要求
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
回應
如果要求成功，將會在上傳完成後將訊息活動傳送至 Bot，且用戶端收到的回應將會包含已傳送的活動識別碼。
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
藉由上傳來傳送多個附件
若要藉由上傳來傳送多個附件，請將有多個部分的要求 POST 至 /v3/directline/conversations/{conversationId}/upload 端點。 請將要求的 Content-Type 標頭設定為 multipart/form-data，並且為每個部分納入 Content-Type 標頭和 Content-Disposition 標頭，以指定每個附件的類型和檔案名稱。 在要求 URI 中，請將 userId 參數設定為訊息傳送者的使用者識別碼。
您可以藉由新增一個指定 Content-Type 標頭值 application/vnd.microsoft.activity 的部分，在要求內納入 Activity 物件。 如果要求包含 Activity，則承載其他部分所指定的附件會新增為該活動的附件，再傳送該活動。 如果要求不包含活動，則會建立空的 Activity 作為傳送指定附件的容器。
下列程式碼片段提供「傳送 (多個) 附件」要求和回應的範例。 在此範例中，要求會傳送包含一些文字和單一影像附件的訊息。 在要求中可以新增其他部分，以將多個附件包含在此訊息中。
要求
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89
[other headers]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity
[other headers]
{
"type": "message",
"from": {
"id": "user1"
},
"text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}
----DD4E5147-E865-4652-B662-F223701A8A89
回應
如果要求成功，將會在上傳完成後將訊息活動傳送至 Bot，且用戶端收到的回應將會包含已傳送的活動識別碼。
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}