在 Direct Line API 3.0 中將活動傳送至 botSend an activity to the bot in Direct Line API 3.0

使用 Direct Line 3.0 通訊協定時,用戶端與 Bot 可交換許多不同類型的活動,包括訊息活動、輸入活動,以及 Bot 所支援的自訂活動。Using the Direct Line 3.0 protocol, clients and bots may exchange several different types of activities, including message activities, typing activities, and custom activities that the bot supports. 對於每個要求,用戶端可傳送一個活動。A client may send a single activity per request.

傳送活動Send an activity

若要將活動傳送至 Bot,用戶端必須建立活動物件以定義活動,然後在要求本文中指定活動物件,並對 https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities 發出 POST 要求。To send an activity to the bot, the client must create an Activity object to define the activity and then issue a POST request to https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, specifying the Activity object in the body of the request.

下列程式碼片段提供「傳送活動」要求和回應的範例。The following snippets provide an example of the Send Activity request and response.

要求Request

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"
}

回應Response

當活動傳遞至 Bot 時,服務會以反映 Bot 狀態碼的 HTTP 狀態碼來回應。When the activity is delivered to the bot, the service responds with an HTTP status code that reflects the bot's status code. 如果 Bot 產生錯誤,系統會將 HTTP 502 回應 (「錯誤的閘道」) 傳回至用戶端,以回應其「傳送活動」要求。If the bot generates an error, an HTTP 502 response ("Bad Gateway") is returned to the client in response to its Send Activity request.

注意

這可能是因為未使用正確的權杖所造成。This can be caused by the fact that a correct token was not used. 只有針對開始對話所接收的權杖可以用來傳送活動。Only the token which was received against start conversation can be used to send an activity.

如果 POST 成功,則回應會包含 JSON 承載,指定已傳送至 Bot 的活動識別碼。If the POST is successful, the response contains a JSON payload that specifies the ID of the Activity that was sent to the bot.

HTTP/1.1 200 OK
[other headers]
{
    "id": "0001"
}

傳送活動要求/回應的時間總計Total time for the Send Activity request/response

將訊息 POST 至 Direct Line 對話的時間總計,是以下幾項的總和:The total time to POST a message to a Direct Line conversation is the sum of the following:

  • HTTP 要求從用戶端到 Direct Line 服務的傳輸時間Transit time for the HTTP request to travel from the client to the Direct Line service
  • Direct Line 中的內部處理時間 (通常少於 120 毫秒)Internal processing time within Direct Line (typically less than 120ms)
  • 從 Direct Line 服務到 Bot 的傳輸時間Transit time from the Direct Line service to the bot
  • Bot 內的處理時間Processing time within the bot
  • HTTP 回應回到用戶端的傳輸時間Transit time for the HTTP response to travel back to the client

將附件傳送至 BotSend attachment(s) to the bot

在某些情況下,用戶端可能需要將影像或文件之類的附件傳送至 Bot。In some situations, a client may need to send attachments to the bot such as images or documents. 用戶端可藉由在它要使用 POST /v3/directline/conversations/{conversationId}/activities 傳送的活動物件內為附件指定 URL,或藉由使用 POST /v3/directline/conversations/{conversationId}/upload上傳附件,將附件傳送至 Bot。A client may send attachments to the bot either by specifying the URL(s) of the attachment(s) within the Activity object that it sends using POST /v3/directline/conversations/{conversationId}/activities or by uploading attachment(s) using POST /v3/directline/conversations/{conversationId}/upload.

依 URL 傳送附件Send attachment(s) by URL

若要使用 POST /v3/directline/conversations/{conversationId}/activities 傳送隨附於活動物件的一或多個附件,只需將一或多個附件物件包含在活動物件內,並設定每個附件物件的 contentUrl 屬性以指定附件的 HTTP、HTTPS 或 data URI 即可。To send one or more attachments as part of the Activity object using POST /v3/directline/conversations/{conversationId}/activities, simply include one or more Attachment objects within the Activity object and set the contentUrl property of each Attachment object to specify the HTTP, HTTPS, or data URI of the attachment.

藉由上傳來傳送附件Send attachment(s) by upload

常常用戶端的裝置上有影像或文件要傳送至 Bot,但卻沒有對應至這些檔案的 URL。Often, a client may have image(s) or document(s) on a device that it wants to send to the bot, but no URLs corresponding to those files. 在此情況下,用戶端可以發出 POST /v3/directline/conversations/{conversationId}/upload 要求,以藉由上傳將附件傳送至 Bot。In this situation, a client can can issue a POST /v3/directline/conversations/{conversationId}/upload request to send attachments to the bot by upload. 要求的格式和內容,將取決於用戶端是要傳送單一附件還是傳送多個附件The format and contents of the request will depend upon whether the client is sending a single attachment or sending multiple attachments.

藉由上傳來傳送單一附件Send a single attachment by upload

若要藉由上傳來傳送單一附件,請發出下列要求:To send a single attachment by upload, issue this request:

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} 取代為訊息傳送者的使用者識別碼。In this request URI, replace {conversationId} with the ID of the conversation and {userId} with the ID of the user that is sending the message. userId 是必要參數。The userId parameter is required. 在要求標頭中,請設定 Content-Type 以指定附件的類型,並設定 Content-Disposition 以指定附件的檔案名稱。In the request headers, set Content-Type to specify the attachment's type and set Content-Disposition to specify the attachment's filename.

下列程式碼片段提供「傳送 (單一) 附件」要求和回應的範例。The following snippets provide an example of the Send (single) Attachment request and response.

要求Request

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]

回應Response

如果要求成功,將會在上傳完成後將訊息活動傳送至 Bot,且用戶端收到的回應將會包含已傳送的活動識別碼。If the request is successful, a message Activity is sent to the bot when the upload completes and the response that the client receives will contain the ID of the Activity that was sent.

HTTP/1.1 200 OK
[other headers]
{
  "id": "0003"
}

藉由上傳來傳送多個附件Send multiple attachments by upload

若要藉由上傳來傳送多個附件,請將有多個部分的要求 POST/v3/directline/conversations/{conversationId}/upload 端點。To send multiple attachments by upload, POST a multipart request to the /v3/directline/conversations/{conversationId}/upload endpoint. 請將要求的 Content-Type 標頭設定為 multipart/form-data,並且為每個部分納入 Content-Type 標頭和 Content-Disposition 標頭,以指定每個附件的類型和檔案名稱。Set the Content-Type header of the request to multipart/form-data and include the Content-Type header and Content-Disposition header for each part to specify each attachment's type and filename. 在要求 URI 中,請將 userId 參數設定為訊息傳送者的使用者識別碼。In the request URI, set the userId parameter to the ID of the user that is sending the message.

您可以藉由新增一個指定 Content-Type 標頭值 application/vnd.microsoft.activity 的部分,在要求內納入 Activity 物件。You may include an Activity object within the request by adding a part that specifies the Content-Type header value application/vnd.microsoft.activity. 如果要求中包含活動,則承載的其他部分所指定的附件會先新增為該活動的附件,然後才會傳送。If the request includes an Activity, the attachments that are specified by other parts of the payload are added as attachments to that Activity before it is sent. 如果要求未包含活動,則會建立空的活動,作為指定的附件藉以傳送的容器。If the request does not include an Activity, an empty Activity is created to serve as the container in which the specified attachments are sent.

下列程式碼片段提供「傳送 (多個) 附件」要求和回應的範例。The following snippets provide an example of the Send (multiple) Attachments request and response. 在此範例中,要求會傳送包含一些文字和單一影像附件的訊息。In this example, the request sends a message that contains some text and a single image attachment. 在要求中可以新增其他部分,以將多個附件包含在此訊息中。Additional parts could be added to the request to include multiple attachments in this message.

要求Request

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

回應Response

如果要求成功,將會在上傳完成後將訊息活動傳送至 Bot,且用戶端收到的回應將會包含已傳送的活動識別碼。If the request is successful, a message Activity is sent to the bot when the upload completes and the response that the client receives will contain the ID of the Activity that was sent.

HTTP/1.1 200 OK
[other headers]
{
    "id": "0004"
}

其他資源Additional resources