Direct Line API 1.1 でボットにメッセージを送信する
重要
この記事では、Direct Line API 1.1 を利用してボットにメッセージを送信する方法について説明します。 クライアント アプリケーションとボットの間に新しい接続を作成する場合は、代わりに Direct Line API 3.0 を使用します。
クライアントは、Direct Line 1.1 プロトコルを使用してボットとメッセージを交換できます。 これらのメッセージは、ボットがサポートするスキーマ (Bot Framework v1 または Bot Framework v3) に変換されます。 クライアントは、要求ごとに 1 つのメッセージを送信できます。
メッセージの送信
ボットにメッセージを送信するには、クライアントで Message オブジェクトを作成してメッセージを定義し、POST 要求を https://directline.botframework.com/api/conversations/{conversationId}/messages に発行し、要求の本文でその Message オブジェクトを指定する必要があります。
次のスニペットは、メッセージ送信要求と応答の例を示しています。
Request
POST https://directline.botframework.com/api/conversations/abc123/messages
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
[other headers]
{
"text": "hello",
"from": "user1"
}
Response
メッセージがボットに配信されると、サービスは、ボットの状態コードを反映する HTTP 状態コードで応答します。 ボットでエラーが生成されると、クライアントからのメッセージ送信要求への応答として、HTTP 500 応答 ("内部サーバー エラー") が返されます。 POST が正常に実行されると、サービスから HTTP 204 状態コードが返されます。 応答の本文で返されるデータはありません。 クライアントのメッセージと、ボットからのメッセージは、ポーリングで取得できます。
HTTP/1.1 204 No Content
[other headers]
メッセージ送信要求/応答の合計時間
Direct Line 会話にメッセージを POST するための合計時間は次を足したものになります。
- HTTP 要求がクライアントから Direct Line サービスに至るための移動時間
- Direct Line 内の内部処理時間 (通常、120 ミリ秒未満)
- Direct Line サービスからボットまでの移動時間
- ボット内の処理時間
- HTTP 応答がクライアントに戻るための移動時間
ボットに添付ファイルを送信する
状況によっては、クライアントから画像や文書などの添付ファイルをボットに送信しなければならないことがあります。 POST /api/conversations/{conversationId}/messages を利用して送信される Message オブジェクト内で添付ファイルの URL を指定するか、POST /api/conversations/{conversationId}/upload を利用して添付ファイルをアップロードすることで、クライアントから添付ファイルを送信できます。
URL で添付ファイルを送信する
POST /api/conversations/{conversationId}/messages を利用して Message オブジェクトの一部として 1 つ以上の添付ファイルを送信するには、メッセージの images 配列または attachments 配列 (あるいはその両方) に添付ファイル URL を指定します。
アップロードで添付ファイルを送信する
クライアントから送信する画像や文書がデバイスにあるものの、それらのファイルに対応する URL がないことがしばしばあります。 そのような場合、クライアントでは、アップロードでボットに添付ファイルを送信する POST /api/conversations/{conversationId}/upload 要求を発行できます。 要求の形式とコンテンツは、クライアントから 1 つの添付ファイルを送信するか、複数の添付ファイルを送信するかによって変わります。
アップロードで 1 つの添付ファイルを送信する
アップロードで 1 つの添付ファイルを送信するには、次のような要求を発行します。
POST https://directline.botframework.com/api/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 に置換します。 要求ヘッダーで、Content-Type を設定して添付ファイルの種類を指定し、Content-Disposition を設定して添付ファイルのファイル名を指定します。
次のスニペットは、(単一の) 添付ファイル送信要求と応答の例を示しています。
Request
POST https://directline.botframework.com/api/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
要求が成功すると、アップロードの完了時にメッセージがボットに送信され、サービスから HTTP 204 状態コードが返されます。
HTTP/1.1 204 No Content
[other headers]
アップロードで複数の添付ファイルを送信する
アップロードで複数の添付ファイルを送信するには、/api/conversations/{conversationId}/upload エンドポイントに対して、マルチパート要求の POST を実行します。 要求の Content-Type ヘッダーを multipart/form-data に設定し、パートごとに Content-Type ヘッダーと Content-Disposition ヘッダーを含めて各添付ファイルの種類とファイル名を指定します。 要求 URI で、userId パラメーターを、メッセージを送信するユーザーの ID に設定します。
Content-Type ヘッダー値 application/vnd.microsoft.bot.message を指定するパートを追加することで、要求内に Message オブジェクトを含めることができます。 これにより、クライアントは、添付ファイルが含まれるメッセージをカスタマイズできます。 要求にメッセージが含まれている場合、ペイロードの他の部分で指定された添付ファイルは、送信される前にそのメッセージに添付ファイルとして追加されます。
次のスニペットは、(複数の) 添付ファイル送信要求と応答の例を示しています。 この例では、要求により、テキストと 1 つの画像添付ファイルが含まれるメッセージが送信されます。 要求にさらにパートを追加して、このメッセージに複数の添付ファイルを含めることができます。
Request
POST https://directline.botframework.com/api/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.bot.message
[other headers]
{
"text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe",
"from": "user1"
}
----DD4E5147-E865-4652-B662-F223701A8A89
Response
要求が成功すると、アップロードの完了時にメッセージがボットに送信され、サービスから HTTP 204 状態コードが返されます。
HTTP/1.1 204 No Content
[other headers]