직접 라인 API 1.1의 봇에 메시지 보내기Send a message to the bot in Direct Line API 1.1

중요

이 문서에서는 직접 회선 API 1.1을 사용하여 봇에게 메시지를 보내는 방법을 설명합니다.This article describes how to send a message to the bot using Direct Line API 1.1. 클라이언트 애플리케이션과 봇 간에 새 연결을 만들 경우에는 직접 회선 API 3.0을 대신 사용합니다.If you are creating a new connection between your client application and bot, use Direct Line API 3.0 instead.

직접 회선 1.1 프로토콜을 사용하면 클라이언트가 봇을 사용하여 메시지를 교환할 수 있습니다.Using the Direct Line 1.1 protocol, clients can exchange messages with bots. 이러한 메시지는 봇이 지원하는(Bot Framework v1 또는 Bot Framework v3) 스키마로 변환됩니다.These messages are converted to the schema that the bot supports (Bot Framework v1 or Bot Framework v3). 클라이언트는 요청당 하나의 메시지를 보낼 수 있습니다.A client may send a single message per request.

메시지 보내기Send a message

봇에게 메시지를 보내려면 Message 개체를 만들어서 메시지를 정의한 다음, 요청 본문에 Message 개체를 지정하는 https://directline.botframework.com/api/conversations/{conversationId}/messagesPOST 요청을 발급해야 합니다.To send a message to the bot, the client must create a Message object to define the message and then issue a POST request to https://directline.botframework.com/api/conversations/{conversationId}/messages, specifying the Message object in the body of the request.

다음 코드 조각은 메시지 보내기 요청 및 응답 예제를 제공합니다.The following snippets provide an example of the Send Message request and response.

요청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 상태 코드로 응답합니다.When the message is delivered to the bot, the service responds with an HTTP status code that reflects the bot's status code. 봇이 오류를 생성하면 메시지 보내기 요청에 대한 응답으로 HTTP 500 응답("내부 서버 오류")이 클라이언트에 반환됩니다.If the bot generates an error, an HTTP 500 response ("Internal Server Error") is returned to the client in response to its Send Message request. POST가 성공하면 서비스는 HTTP 204 상태 코드를 반환합니다.If the POST is successful, the service returns an HTTP 204 status code. 응답 본문에 데이터가 반환되지 않습니다.No data is returned in body of the response. 클라이언트의 메시지와 봇의 모든 메시지는 폴링을 통해 얻을 수 있습니다.The client's message and any messages from the bot can be obtained via polling.

HTTP/1.1 204 No Content
[other headers]

메시지 보내기 요청/응답의 총 시간Total time for the Send Message 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 내부 처리 시간(일반적으로 120ms 미만)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 /api/conversations/{conversationId}/messages를 사용하여 보내는 Message 개체 내에 첨부 파일의 URL을 지정하거나 POST /api/conversations/{conversationId}/upload를 사용하여 첨부 파일을 업로드하는 방식으로 봇에 첨부 파일을 보냅니다.A client may send attachments to the bot either by specifying the URL(s) of the attachment(s) within the Message object that it sends using POST /api/conversations/{conversationId}/messages or by uploading attachment(s) using POST /api/conversations/{conversationId}/upload.

URL을 통해 첨부 파일 보내기Send attachment(s) by URL

POST /api/conversations/{conversationId}/messages를 사용하여 Message 개체의 일부로 하나 이상의 첨부 파일을 보내려면 메시지의 images 배열 및/또는 attachments 배열 내에 첨부 파일 URL을 지정합니다.To send one or more attachments as part of the Message object using POST /api/conversations/{conversationId}/messages, specify the attachment URL(s) within the message's images array and/or attachments array.

업로드를 통해 첨부 파일 보내기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 /api/conversations/{conversationId}/upload 요청을 발급하여 업로드를 통해 봇에게 첨부 파일을 보낼 수 있습니다.In this situation, a client can can issue a POST /api/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/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로 바꿉니다.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. 요청 헤더에 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/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 상태 코드를 반환합니다.If the request is successful, a message is sent to the bot when the upload completes and the service returns an HTTP 204 status code.

HTTP/1.1 204 No Content
[other headers]

업로드를 통해 여러 첨부 파일 보내기Send multiple attachments by upload

업로드를 통해 여러 첨부 파일을 보내려면 /api/conversations/{conversationId}/upload 엔드포인트에 여러 파트를 포함하는 요청을 POST합니다.To send multiple attachments by upload, POST a multipart request to the /api/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.bot.message를 지정하는 파트를 추가하여 요청 내에 Message 개체를 포함할 수 있습니다.You may include a Message object within the request by adding a part that specifies the Content-Type header value application/vnd.microsoft.bot.message. 이렇게 하면 첨부 파일이 포함된 메시지를 클라이언트가 사용자 지정할 수 있습니다.This allows the client to customize the message that contains the attachment(s). 요청에 메시지가 포함된 경우, 페이로드의 다른 파트에 의해 지정된 첨부 파일이 메시지를 보내기 전에 해당 메시지의 첨부 파일로 추가됩니다.If the request includes a Message, the attachments that are specified by other parts of the payload are added as attachments to that Message before it is 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/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 상태 코드를 반환합니다.If the request is successful, a message is sent to the bot when the upload completes and the service returns an HTTP 204 status code.

HTTP/1.1 204 No Content
[other headers]

추가 리소스Additional resources