Direct Line API 3.0 でボットにアクティビティを送信する
Direct Line 3.0 プロトコルを利用すると、メッセージ アクティビティ、入力アクティビティ、ボットでサポートされるカスタム アクティビティなど、さまざまな種類のアクティビティをクライアントとボットで交換できます。 クライアントでは、要求ごとにアクティビティを 1 つを送信できます。
アクティビティを送信する
ボットにアクティビティを送信するには、クライアントで Activity オブジェクトを作成してアクティビティを定義し、POST 要求を https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities に発行し、要求の本文でその Activity オブジェクトを指定する必要があります。
次のスニペットは、アクティビティ送信要求と応答の例を示しています。
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
アクティビティがボットに配信されるとき、サービスでは、ボットのステータス コードを反映する HTTP ステータス コードで応答します。 ボットによりエラーが生成された場合、そのアクティビティ送信要求への応答で、HTTP 502 応答 ("ゲートウェイが不適切です") がクライアントに返されます。
注意
これは、正しいトークンが使用されなかったことが原因で発生する可能性があります。 アクティビティの送信には、"会話の開始" に対して受信したトークンのみを使用できます。
投稿が成功した場合、ボットに送信されたアクティビティの ID を指定する JSON ペイロードが応答に含まれます。
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
アクティビティ送信要求/応答の合計時間
Direct Line 会話にメッセージを POST するための合計時間は次を足したものになります。
- HTTP 要求がクライアントから Direct Line サービスに至るための移動時間
- Direct Line 内の内部処理時間 (通常、120 ミリ秒未満)
- Direct Line サービスからボットまでの移動時間
- ボット内の処理時間
- HTTP 応答がクライアントに戻るための移動時間
ボットに添付ファイルを送信する
状況によっては、クライアントから画像や文書などの添付ファイルをボットに送信しなければならないことがあります。 POST /v3/directline/conversations/{conversationId}/activities を利用して送信される Activity オブジェクト内で添付ファイルの URL を指定するか、POST /v3/directline/conversations/{conversationId}/upload を利用して添付ファイルをアップロードすることで、クライアントでは添付ファイルを送信できます。
URL で添付ファイルを送信する
POST /v3/directline/conversations/{conversationId}/activities を利用し、Activity オブジェクトの一部として 1 つまたは複数の添付ファイルを送信するには、Activity オブジェクト内に 1 つまたは複数の Attachment オブジェクトを含め、各 Attachment オブジェクトの contentUrl プロパティを設定し、添付ファイルの HTTP、HTTPS、data URI を指定します。
アップロードで添付ファイルを送信する
クライアントから送信する画像や文書がデバイスにあるものの、それらのファイルに対応する URL がないことがしばしばあります。 そのような場合、クライアントでは、アップロードでボットに添付ファイルを送信する POST /v3/directline/conversations/{conversationId}/upload 要求を発行できます。 要求の形式とコンテンツは、クライアントから 1 つの添付ファイルを送信するか、複数の添付ファイルを送信するかによって変わります。
アップロードで 1 つの添付ファイルを送信する
アップロードで 1 つの添付ファイルを送信するには、次のような要求を発行します。
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 に置換します。 userId パラメーターは必須です。 要求ヘッダーで、Content-Type を設定して添付ファイルの種類を指定し、Content-Disposition を設定して添付ファイルのファイル名を指定します。
次のスニペットは、(単一の) 添付ファイル送信要求と応答の例を示しています。
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
要求が成功した場合、アップロードが完了したとき、メッセージ アクティビティがボットに送信されます。クライアントにより受け取られる応答には、送信されたアクティビティの ID が含まれます。
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
アップロードで複数の添付ファイルを送信する
アップロードで複数の添付ファイルを送信するには、/v3/directline/conversations/{conversationId}/upload エンドポイントに対して、マルチパート要求の POST を実行します。 要求の Content-Type ヘッダーを multipart/form-data に設定し、パートごとに Content-Type ヘッダーと Content-Disposition ヘッダーを含めて各添付ファイルの種類とファイル名を指定します。 要求 URI で、userId パラメーターを、メッセージを送信するユーザーの ID に設定します。
Content-Type ヘッダー値 application/vnd.microsoft.activity を指定するパートを追加することで、要求内に Activity オブジェクトを含めることができます。 要求に Activity が含まれている場合、ペイロードの他の部分で指定された添付ファイルは、送信される前にそのアクティビティに添付ファイルとして追加されます。 要求に Activity が含まれていない場合は、指定された添付ファイルが送信されるコンテナーとして機能する空のアクティビティが作成されます。
次のスニペットは、(複数の) 添付ファイル送信要求と応答の例を示しています。 この例では、要求により、テキストと 1 つの画像添付ファイルが含まれるメッセージが送信されます。 要求にさらにパートを追加して、このメッセージに複数の添付ファイルを含めることができます。
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
要求が成功した場合、アップロードが完了したとき、メッセージ アクティビティがボットに送信されます。クライアントにより受け取られる応答には、送信されたアクティビティの ID が含まれます。
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}