• KB Home
  • API
  • API edna Chat Center для Bot Connect
  • Отправка ответов бота

Отправка ответов бота

4 октября 2022

Этот метод отправляет ответы, которые бот сможет использовать, отвечая на вопросы клиентов. После того как боту отправлено сообщение (вебхук MESSAGE), отправьте ответ бота на это сообщение на POST эндпоинт <threadsUrl>/api/v1/chatbot.

Типы ответов:

  • По threadsClientId – Внутренний ID клиента, подходит и для авторизованных, и для неавторизованных клиентов. Этот тип предпочтителен для всех новых интеграций.
  • По questionId – Используется, когда известен идентификатор конкретного вопроса.
  • По sessionId и questionIndex – Используется, когда questionID вопроса неизвестен, и вам необходимо ответить на сообщение, чтобы выяснить индекс вопроса в треде.
  • (Устарело) По clientId – Чаще используется для авторизованных клиентов, когда требуется написать клиенту. Не имеет привязки к конкретному вопросу.
Чтобы изображения верно отображались для клиентов, вводите имя файла вместе с расширением или указывайте тип файла (например, image/jpg).
Если получено сообщение с типом EMAIL, на него необходимо отвечать по sessionId и questionIndex. У одного клиента может быть несколько активных тредов с одной темой, так что вам необходимо знать, в какой конкретно тред отправить сообщение.

Параметры запроса

ПараметрТипОписание
textstringОтвет бота на сообщение от клиента. Обязательный параметр, если не использован formattedText.
answerIdstringУникальный идентификатор ответа бота.
formattedTextstring (необязательно)Ответ бота на сообщение от клиента. В ответе может содержаться текст в разметке Markdown. Рекомендуется передать текстовое представление ответа в поле text для отображения в пользовательском интерфейсе.
clientIdstring (необязательно, deprecated)Внешний ID клиента. Этот параметр устарел, вместо него используйте threadsClientId.
threadsClientIdlong (необязательно)Внутренний ID клиента.
sessionIdstring (необязательно)Внутренний ID треда (ID чата клиента с агентом).
questionIdnumber (необязательно)Внутренний ID сообщения клиента.
questionIndexnumber (необязательно)Индекс сообщения клиента в треде (чате).
segmentationInfoMap<String, String>Дополнительные параметры для сегментации (используется как в пользовательских, так и в преднастроенных сегментах). Параметр сегментации personal_manager доступен “из коробки”. Если в этом параметре передан логин агента, а маршрут для сегмента с этим параметром настроен в системе, треды клиентов распределяются по соответствующему маршруту персональным менеджерам (агентам).
attachmentsarray (необязательно)Настройки вложения. Поля:

• url – URL файла, строка до 4000 символов
• name – Название файла, строка до 1000 символов
• type – MIME-тип файла, строка до 256 символов
quickRepliesarray (необязательно)Настройки быстрого ответа. Поля:

• type – Тип быстрого ответа. Возможные значения: TEXT для текстовых сообщений.
• text – Текст сообщения, строка до 4000 символов.
• shown_text – Текстовое содержимое, необязательный параметр, строка до 2000 символов. Используется только в комбинации с параметром text. Если параметр указан, этот текст отправляется как клиентское сообщение после нажатия на кнопку быстрого ответа.
• callback_data – Текстовое содержимое, необязательный параметр, строка до 255 символов. Название события, которое будет передаваться, когда вызван JS SDK API для последующей обработки заказчиком на стороне сайта.
• imageUrl – URL иконки кнопки, строка до 4000 символов.
• url – Ссылка на прикрепленный файл, строка до 4000 символов.

Длина и количество быстрых ответов настраивается в БД: message.max-quick-replies, message.max-quick-reply-length.
codestringЗначения:
• UNCLEAR_QUESTION – Вопрос непонятен боту, поэтому он переводит его агенту.
• SWITCH_TO_HUMAN – Бот получил запрос на перевод диалога на агента.
• SUCCESS – Бот успешно обработал сообщение клиента и отправил ответ.
userIdsset<long>(необязательно)Список идентификаторов агентов, на которых необходимо перевести тред после снятия его с текущего бота. Необходимо отправлять вместе с кодом SWITCH_TO_HUMAN.
skillIdsset<long>(необязательно)Список идентификаторов навыков, которыми должны владеть агенты, на которых необходимо перевести тред после снятия его с текущего бота. Необходимо отправлять вместе с кодом SWITCH_TO_HUMAN.
unitIdsset<long>(необязательно)Список идентификаторов департаментов, на агентов из которых необходимо перевести тред после снятия его с текущего бота. Необходимо отправлять вместе с кодом SWITCH_TO_HUMAN.
settingsobject (необязательно)Дополнительные настройки сообщения.
settings.blockInputboolean (необязательно)Параметр, который указывает, заблокировано ли поле ввода сообщения (true – заблокировано, false – не заблокировано). Работает только для быстрых ответов.
settings.maskedboolean (необязательно)Параметр, который указывает, замаскированы ли цифры в связанном сообщении клиента (true – замаскированы, false – не замаскированы).
quickRepliesHeaderFooterobject (необязательно)Дополнительные заголовок и подпись (только для Whatsapp).
quickRepliesHeaderFooter.headerarray (необязательно)Поля:
• text – Текст заголовка, максимальная длина 61 символ.
• imageUrl – URL изображения
• documentUrl – URL файла.
• documentName – Название файла
• videoUrl – URL видеофайла
В заголовке header можно передать параметры: текст заголовка, изображение, документ, видео. Отправить одновременно в заголовке и текст, и изображение, и документ, и видео нельзя.
quickRepliesHeaderFooter.footerarray (необязательно)Поля:
• text – Текст подписи, максимальная длина 61 символ
messageListPickerobject (необязательно)Интерактивный список (только для Whatsapp).
messageListPicker.headerobject (необязательно)Поля:
• text (string) – Текст заголовка, максимальная длина 60 символов
messageListPicker.footerobject (необязательно)Поля:
• text – Текст подписи, максимальная длина 60 символов
messageListPicker.titlestringНаименование кнопки для интерактивного списка, максимальная длина 20 символов
messageListPicker.sectionsarray (максимум 10 элементов во всех items)Поля:
• title (string) – Заголовок интерактивного списка, максимальная длина 24 символа
• items (array) – массив элементов интерактивного списка
messageListPicker.section.itemsarrayПоля:
• title (string) – Название элемента, максимальная длина 24 символа
• subTitle (string) – Необязательное. Подзаголовок элемента, максимальная длина 72 символа
• identifier (string) – сквозной для всего сообщения ID элемента, вернется в ответном сообщении пользователя

Пример: ответ по clientId

Пример curl

$ curl 'http: //localhost:8080/api/v1/chatbot' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "segmentationInfo": {
        "key": "value"
    },
    "clientId": "1",
    "threadsClientId": 1,
    "receivedAt": "2022-05-18T08:45:07.291Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "settings": {
        "blockInput": false,
        "masked": true
    },
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}'

HTTP запрос

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Content-Length: 474
Host: localhost: 8080
{
    "segmentationInfo": {
        "key": "value"
    },
    "clientId": "1",
    "threadsClientId": 1,
    "receivedAt": "2022-05-18T08:45:07.291Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "settings": {
        "blockInput": false,
        "masked": true
    },
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}

Пример успешного HTTP ответа

HTTP/1.1 200 OK

Пример: ответ по questionId

Пример curl

$ curl 'http: //localhost:8080/api/v1/chatbot' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "segmentationInfo": {
        "key": "value"
    },
    "questionId": 43,
    "receivedAt": "2022-05-18T08:45:07.606Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}

HTTP запрос

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Content-Length: 450
Host: localhost: 8080
{
    "segmentationInfo": {
        "key": "value"
    },
    "questionId": 43,
    "receivedAt": "2022-05-18T08:45:07.606Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}

Пример успешного HTTP ответа

HTTP/1.1 200 OK

Пример: ответ по sessionId и questionIndex

Пример curl

$ curl 'http: //localhost:8080/api/v1/chatbot' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "segmentationInfo": {},
    "sessionId": "1",
    "questionIndex": 3,
    "receivedAt": "2022-05-18T08:45:07.656Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}'

HTTP запрос

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Content-Length: 383
Host: localhost: 8080
{
    "segmentationInfo": {},
    "sessionId": "1",
    "questionIndex": 3,
    "receivedAt": "2022-05-18T08:45:07.656Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}

Пример успешного HTTP ответа

HTTP/1.1 200 OK

Пример: сообщение с быстрым ответом

Пример curl

$ curl 'http: //localhost:8080/api/v1/chatbot' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "segmentationInfo": {},
    "clientId": "1",
    "threadsClientId": 1,
    "receivedAt": "2022-05-18T08:45:07.464Z",
    "quickReplies": [
        {
            "type": "TEXT",
            "text": "quick reply 1",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
            "payload" : null
        },
        {
            "type": "TEXT",
            "text": "quick reply 2",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
            "payload" : null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SUCCESS",
    "answerId": "externalAnswerId"
}'

HTTP запрос

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Content-Length: 570
Host: localhost: 8080
{
    "segmentationInfo": {},
    "clientId": "1",
    "threadsClientId": 1,
    "receivedAt": "2022-05-18T08:45:07.464Z",
    "quickReplies": [
        {
            "type": "TEXT",
            "text": "quick reply 1",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
            "payload" : null
        },
        {
            "type": "TEXT",
            "text": "quick reply 2",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
            "payload" : null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SUCCESS",
    "answerId": "externalAnswerId"
}

Пример успешного HTTP ответа

HTTP/1.1 200 OK
In this article
Разделы статьи