Отправка действия боту в API Direct Line 3.0
С помощью протокола Direct Line 3.0 клиенты и боты могут обмениваться различными типами действий, в том числе действиями сообщений, ввода и настраиваемыми действиями, которые поддерживает бот. В каждом запросе клиент может отправить одно действие.
Отправка действия
Чтобы отправить действие боту, клиент должен создать объект Действие для определения действия, а затем выполнить запрос POST к https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, указав объект Activity в теле запроса.
Ниже приведены примеры фрагментов кода для запроса отправки действия и соответствующего ответа.
Запрос
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"
}
Ответ
После того как действие доставлено боту, служба отвечает с кодом состояния HTTP, который отражает код состояния бота. Если в боте возникает ошибка, в ответ на запрос отправки действия клиент получает ответ HTTP 502 ("Недопустимый шлюз").
Примечание
Это может быть вызвано тем, что не был использован правильный маркер. Для отправки действия можно использовать только маркер, полученный для операции Начать беседу.
Если запрос POST выполнен успешно, ответ содержит полезные данные JSON, указывающие идентификатор действия, которое было отправлено боту.
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
Общее время запроса и ответа отправки действия
Общее время для отправки запроса POST в общение Direct Line является суммой следующих значений:
- транзитное время передачи HTTP-запроса с клиента в службу Direct Line;
- время внутренней обработки в Direct Line (обычно меньше 120 мс);
- транзитное время передачи из службы Direct Line в бот;
- время обработки в боте;
- транзитное время обратной передачи ответа HTTP клиенту.
Отправка вложений боту
В некоторых случаях клиенту может потребоваться отправить боту вложения, такие как изображения или документы. Отправка вложений осуществляется либо путем указания URL-адресов вложений в объекте Действие, отправляемом клиентом с помощью POST /v3/directline/conversations/{conversationId}/activities, либо путем передачи вложений с помощью POST /v3/directline/conversations/{conversationId}/upload.
Отправка вложений по URL-адресу
Чтобы отправить одно или несколько вложений в составе объекта Действие с помощью POST /v3/directline/conversations/{conversationId}/activities, нужно просто включить один или несколько объектов Вложение в объект Activity и задать свойству contentUrl каждого объекта Attachment значения HTTP, HTTPS или URI data вложения.
Отправка вложений путем передачи
Иногда на устройстве клиента могут находиться изображения или документы, которые нужно отправить боту, но URL-адреса, соответствующие этим файлам, отсутствуют. В этом случае клиент может выполнить запрос POST /v3/directline/conversations/{conversationId}/upload, чтобы отправить вложения боту путем передачи. Формат и содержимое запроса зависят от того, сколько вложений отправляет клиент, — одно или несколько.
Отправка одного вложения путем передачи
Чтобы отправить одно вложение путем передачи, выполните следующий запрос.
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} на идентификатор общения, а {userId} — на идентификатор пользователя, который отправляет сообщение. Параметр userId является обязательным. В заголовках запроса задайте для Content-Type тип вложения, а для Content-Disposition задайте имя файла вложения.
Ниже приведены примеры фрагментов кода для запроса отправки одного вложения и соответствующего ответа.
Запрос
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]
Ответ
Если запрос выполнен успешно, после завершения передачи боту отправляется сообщение с действием. А ответ, полученный клиентом, будет содержать идентификатор отправленного действия.
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
Отправка нескольких вложений путем передачи
Чтобы отправить несколько вложений путем передачи, отправьте составной запрос POST к конечной точке /v3/directline/conversations/{conversationId}/upload. Задайте multipart/form-data в качестве заголовка Content-Type запроса и включите заголовок Content-Type и заголовок Content-Disposition для каждой части, чтобы указать тип и имя файла каждого вложения. В URI запроса задайте параметру userId значение идентификатора пользователя, который отправляет сообщение.
В запрос можно включить объект Activity, добавив часть, которая указывает значение application/vnd.microsoft.activity заголовка Content-Type. Если запрос включает действие, вложения, указанные другими частями полезных данных, добавляются в качестве вложений в это действие перед его отправкой. Если запрос не включает действие, создается пустое действие для использования в качестве контейнера, в котором отправляются указанные вложения.
Ниже приведены примеры фрагментов кода для запроса отправки нескольких вложений и соответствующего ответа. В этом примере запрос отправляет сообщение, содержащее текст и одно вложение с изображением. Чтобы включить несколько вложений в это сообщение, в запрос можно добавить дополнительные части.
Запрос
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
Ответ
Если запрос выполнен успешно, после завершения передачи боту отправляется сообщение с действием. А ответ, полученный клиентом, будет содержать идентификатор отправленного действия.
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}