ダイレクトライン API 3.0 でメッセージ交換を開始するStart a conversation in Direct Line API 3.0

Direct Line の会話はクライアントによって明示的に開かれ、ボットとクライアントが参加し、有効な資格情報を持っている限り続きます。Direct Line conversations are explicitly opened by clients and may run as long as the bot and client participate and have valid credentials. 会話が開いている間は、ボットとクライアントの両方がメッセージを送信できます。While the conversation is open, both the bot and client may send messages. 複数のクライアントが特定の会話に接続でき、各クライアントは、複数のユーザーの代理として参加できます。More than one client may connect to a given conversation and each client may participate on behalf of multiple users.

新しい会話を開くOpen a new conversation

クライアントから新しい会話を開始するには、/v3/directline/conversations エンドポイントに POST を発行します。To open a new conversation from your client, issue POST to the /v3/directline/conversations endpoint.

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer SECRET_OR_TOKEN

次のスニペットは、開始メッセージ交換の要求と応答の例を示しています。The following snippets provide an example of the start conversation request and response.

RequestRequest

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

ResponseResponse

要求が成功すると、応答には、会話の ID、トークン、トークンの有効期限が切れるまでの秒数を示す値、およびクライアントが WebSocket ストリーム経由でアクティビティを受信するために使用できるストリーム URL が含まれます。If the request is successful, the response will contain an ID for the conversation, a token, a value that indicates the number of seconds until the token expires, and a stream URL that the client may use to receive activities via WebSocket stream.

HTTP/1.1 201 Created
[other headers]
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
  "streamUrl": "https://directline.botframework.com/v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
}

通常、メッセージ交換の開始要求は、新しいメッセージ交換を開くために使用されます。新しいメッセージ交換が正常に開始された場合は、 HTTP 201 状態コードが返されます。Typically, a start conversation request is used to open a new conversation and an HTTP 201 status code is returned if the new conversation is successfully started. ただし、クライアントが、メッセージ交換の開始操作を使用してメッセージ交換を開始するために以前に使用されたヘッダー内のダイレクト行トークンを使用して開始メッセージ交換要求を送信した場合、 Authorization HTTP 200 ステータスコードが返され、要求が受け入れ可能であることを示します (既に存在している場合)。However, if a client submits a start conversation request with a Direct Line token in the Authorization header that has previously been used to start a conversation using the start conversation operation, an HTTP 200 status code will be returned to indicate that the request was acceptable but no conversation was created (as it already existed).

ヒント

WebSocket stream URL に接続されるまで 60 秒の猶予があります。You have 60 seconds to connect to the WebSocket stream URL. この時間内に接続を確立できない場合は、会話に再接続して新しいストリーム URL を生成する必要があります。If the connection cannot be established during this time, you can reconnect to the conversation to generate a new stream URL.

メッセージ交換の開始とトークンの生成Start conversation versus generate token

メッセージ交換の開始操作 ( POST /v3/directline/conversations ) は、両方の操作が POST /v3/directline/tokens/generate token 1 つのメッセージ交換にアクセスするために使用できるを返すという点で、トークン生成操作 () に似ています。The start conversation operation (POST /v3/directline/conversations) is similar to the generate token operation (POST /v3/directline/tokens/generate) in that both operations return a token that can be used to access a single conversation. ただし、メッセージ交換の開始操作では、メッセージ交換を開始し、bot に連絡して、WebSocket ストリームの URL を作成します。一方、トークン生成操作では、これらの処理は行われません。However, the start conversation operation also starts the conversation, contacts the bot, and creates a WebSocket stream URL, whereas the generate token operation does none of these things.

クライアントでメッセージ交換をすぐに開始する場合は、メッセージ交換の開始操作を使用します。If you intend to start the conversation immediately with your client, use the start conversation operation. クライアントにトークンを配布して、メッセージ交換を開始する予定の場合は、代わりに トークンの生成 操作を使用します。If you plan to distribute the token to clients and want them to initiate the conversation, use the generate token operation instead.

その他のリソースAdditional resources