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

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

4 октября 2022

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

Существуют четыре типа ответов:

  • По threadsClientId — Внутренний ID клиента, подходит и для авторизованных, и для неавторизованных клиентов. Этот тип предпочтителен для всех новых интеграций.
  • По questionId — Используется, когда известен идентификатор конкретного вопроса.
  • По sessionId и questionIndex — Используется, когда questionID вопроса неизвестен, и вам необходимо ответить на сообщение для того, чтобы выяснить индекс вопроса в треде.
  • 4. (Устарело) По clientId — Чаще используется для авторизованных клиентов, когда требуется написать клиенту; не имеет привязки к конкретному вопросу.

Если в ответе есть вложения, то для того, чтобы файл верно отображался клиенту, название изображения должно содержать расширение файла, либо же должен быть указан тип файла (например, image/jpg).

Если получено сообщение с типом EMAIL, на него необходимо отвечать по sessionId и questionIndex, т.к. у одного email адреса клиента может быть несколько активных тредов, созданных по теме email, так что вам необходимо знать, в какой конкретно тред отправить сообщение.

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

ПараметрТипОписание
textstringОтвет бота на сообщение от клиента. Обязательный параметр, если не использован formattedText.
answerIdstringУникальный идентификатор ответа бота, строка до 4000 символов.
formattedTextstring (необязательно)Ответ бота на сообщение от клиента. В ответе может содержаться текст в разметке Markdown. Рекомендуется передать текстовое представление ответа в поле text для отображения в пользовательском интерфейсе.
clientIdstring (необязательно, deprecated)Внешний ID клиента. Этот параметр устарел, вместо него используйте threadsClientId.
threadsClientIdlong (необязательно)Внутренний ID клиента
receivedAtstring (необязательно)Время получения сообщения, дата в формате UTC: yyyy-MM-dd’T’HH:mm:ss.SSS’Z
sessionIdstring (необязательно)Внутренний ID треда (ID чата клиента с агентом)
questionIdnumber (необязательно)Внутренний ID сообщения клиента
questionIndexnumber (необязательно)Индекс сообщения клиента в треде (чате)
segmentationInfoMap<String, String>Дополнительные параметры для сегментации (используется как в пользовательских, так и в преднастроенных сегментах). Параметр сегментации personal_manager доступен «из коробки». Если в этом параметре передан логин агента, а маршрут для сегмента с этим параметром настроен в системе, треды клиентов распределяются по соответствующему маршруту персональным менеджерам (агентам).
attachmentsarray (необязательно)Настройки вложения. Поля:

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

• type — Тип быстрого ответа. Возможные значения: TEXT для текстовых сообщений, WEBVIEW для веб-форм.
• 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 — не замаскированы).

Пример: ответ по 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
        },
        {
            "type": "TEXT",
            "text": "quick reply 2",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": 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
        },
        {
            "type": "TEXT",
            "text": "quick reply 2",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SUCCESS",
    "answerId": "externalAnswerId"
}

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

HTTP/1.1 200 OK
Приветствие
Cледующая статья Подсказки
In this article
Разделы статьи