ダイレクトライン API 3.0 でボットにアクティビティを送信するSend an activity to the bot in Direct Line API 3.0

Direct Line 3.0 プロトコルを利用すると、メッセージ アクティビティ、入力アクティビティ、ボットでサポートされるカスタム アクティビティなど、さまざまな種類のアクティビティをクライアントとボットで交換できます。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. クライアントでは、要求ごとにアクティビティを 1 つを送信できます。A client may send a single activity per request.

アクティビティを送信するSend an activity

ボットにアクティビティを送信するには、クライアントで Activity オブジェクトを作成してアクティビティを定義し、POST 要求を https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities に発行し、要求の本文でその Activity オブジェクトを指定する必要があります。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.

RequestRequest

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

ResponseResponse

アクティビティがボットに配信されるとき、サービスでは、ボットのステータス コードを反映する HTTP ステータス コードで応答します。When the activity is delivered to the bot, the service responds with an HTTP status code that reflects the bot's status code. ボットによりエラーが生成された場合、そのアクティビティ送信要求への応答で、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.

投稿が成功した場合、ボットに送信されたアクティビティの ID を指定する JSON ペイロードが応答に含まれます。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

Direct Line 会話にメッセージを POST するための合計時間は次を足したものになります。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 サービスからボットまでの移動時間Transit time from the Direct Line service to the bot
  • ボット内の処理時間Processing time within the bot
  • HTTP 応答がクライアントに戻るための移動時間Transit time for the HTTP response to travel back to the client

ボットに添付ファイルを送信するSend attachment(s) to the 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 を利用して送信される Activity オブジェクト内で添付ファイルの URL を指定するか、POST /v3/directline/conversations/{conversationId}/upload を利用して添付ファイルをアップロードすることで、クライアントでは添付ファイルを送信できます。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 を利用し、Activity オブジェクトの一部として 1 つまたは複数の添付ファイルを送信するには、Activity オブジェクト内に 1 つまたは複数の Attachment オブジェクトを含め、各 Attachment オブジェクトの 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

クライアントから送信する画像や文書がデバイスにあるものの、それらのファイルに対応する 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 要求を発行できます。In this situation, a client can can issue a POST /v3/directline/conversations/{conversationId}/upload request to send attachments to the bot by upload. 要求の形式とコンテンツは、クライアントから 1 つの添付ファイルを送信するか、複数の添付ファイルを送信するかによって変わります。The format and contents of the request will depend upon whether the client is sending a single attachment or sending multiple attachments.

アップロードで 1 つの添付ファイルを送信するSend a single attachment by upload

アップロードで 1 つの添付ファイルを送信するには、次のような要求を発行します。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} を会話の ID に置換し、 {userId} をメッセージを送信するユーザーの ID に置換します。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.

RequestRequest

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]

ResponseResponse

要求が成功した場合、アップロードが完了したとき、メッセージ アクティビティがボットに送信されます。クライアントにより受け取られる応答には、送信されたアクティビティの ID が含まれます。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

アップロードで複数の添付ファイルを送信するには、/v3/directline/conversations/{conversationId}/upload エンドポイントに対して、マルチパート要求の POST を実行します。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 パラメーターを、メッセージを送信するユーザーの ID に設定します。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. この例では、要求により、テキストと 1 つの画像添付ファイルが含まれるメッセージが送信されます。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.

RequestRequest

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

ResponseResponse

要求が成功した場合、アップロードが完了したとき、メッセージ アクティビティがボットに送信されます。クライアントにより受け取られる応答には、送信されたアクティビティの ID が含まれます。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