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

Обновлено: 22 июля 2026

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

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

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

к сведению

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

warning

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

Поля тела запроса

Поле	Тип	Описание
`text`	string	Ответ бота на сообщение от клиента. Обязательный параметр, если не использован `formattedText`.
`answerId`	string	Уникальный идентификатор ответа бота. warning В случае повторного получения значения сообщение не будет доставлено клиенту. Если получен ответ на вопрос, для которого ранее уже был получен ответ бота, то в зависимости от настроек системы сообщение может быть: отклонено и доставка сообщения клиенту не будет выполнена (строгий режим) или отправка будет выполнена независимо от текста, отправляемого сообщения (мягкий режим). То есть клиент может получить дублирующее сообщение от бота.
`formattedText`	string (необязательно)	Ответ бота на сообщение от клиента. В ответе может содержаться текст в разметке Markdown. Рекомендуется передать текстовое представление ответа в поле `text` для отображения в пользовательском интерфейсе.
`clientId`	string (необязательно, deprecated)	Внешний ID клиента. Этот параметр устарел, вместо него используйте `threadsClientId`.
`threadsClientId`	long (необязательно)	Внутренний ID клиента
`sessionId`	string (необязательно)	Внутренний ID треда (ID чата клиента с агентом)
`questionId`	number (необязательно)	Внутренний ID сообщения клиента
`questionIndex`	number (необязательно)	Индекс сообщения клиента в треде (чате)
`segmentationInfo`	Map<String, String>	Дополнительные параметры для сегментации (используется как в пользовательских, так и в преднастроенных сегментах). Параметр сегментации `personal_manager` доступен "из коробки". Если в этом параметре передан логин агента, а маршрут для сегмента с этим параметром настроен в системе, треды клиентов распределяются по соответствующему маршруту персональным менеджерам (агентам).
attachments	array (необязательно)	Поля `url` - URL файла, строка до 4000 символов `name` - Название файла, строка до 1000 символов `type` - MIME-тип файла, строка до 256 символов
`code`	string	Значения `UNCLEAR_QUESTION` - Вопрос не понятен боту, поэтому он переводит его человеку (т.е агенту). `SWITCH_TO_HUMAN` - Бот получил запрос на перевод диалога на человека (т.е агенту). `SUCCESS` - Бот успешно обработал сообщение клиента и отправил ответ.
`userIds`	set<long>(необязательно)	Список идентификаторов агентов, на которых необходимо перевести тред после снятия его с текущего бота. Необходимо присылать в сочетании с кодом `SWITCH_TO_HUMAN`.
`skillIds`	set<long>(необязательно)	Список идентификаторов навыков, которыми должны владеть агента, на которых необходимо перевести тред после снятия его с текущего бота. Необходимо присылать в сочетании с кодом `SWITCH_TO_HUMAN`.
`unitIds`	set<long>(необязательно)	Список идентификаторов департаментов, на агентов из которых необходимо перевести тред после снятия его с текущего бота. Необходимо присылать в сочетании с кодом `SWITCH_TO_HUMAN`.
`settings`	Object (необязательно)	Дополнительные настройки сообщения
`settings.blockInput`	`boolean` (необязательно)	Параметр, который указывает, заблокировано ли поле ввода сообщения (`true` - заблокировано, `false` - не заблокировано). Работает только для быстрых ответов.
`settings.masked`	`boolean` (необязательно)	Параметр, который указывает, замаскированы ли цифры в связанном сообщении клиента (`true` - замаскированы, `false` - не замаскированы).
`quickReplies`	`array` (необязательно)	`type` - Тип быстрого ответа. Возможные значения: `TEXT` для текстовых сообщений, `CONTACT` для получения данных о клиенте. `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`
`quickRepliesHeaderFooter`	`Object` (необязательно)	Дополнительные заголовок и подпись (только для Whatsapp)
`quickRepliesHeaderFooter.header`	`array` (необязательно)	`text` - Текст заголовка, максимальная длина 61 символ `imageUrl` - URL изображения `documentUrl` - URL файла `documentName` - Название файла `videoUrl` - URL видеофайла В заголовке `header` можно передать параметры: текст заголовка, изображение, документ, видео. Отправить одновременно в заголовке и текст, и изображение, и документ, и видео нельзя.
`quickRepliesHeaderFooter.footer`	`array` (необязательно)	Поля `text` - Текст подписи, максимальная длина 61 символ
`messageListPicker`	`Object` (необязательно)	Интерактивный список (только для Whatsapp)
`messageListPicker.header`	`Object` (необязательно)	Поля `text` (string) - Текст заголовка, максимальная длина 60 символов
`messageListPicker.footer`	`Object` (необязательно)	Поля `text` (string) - Текст подписи, максимальная длина 60 символов
`messageListPicker.title`	`string`	Наименование кнопки для интерактивного списка, максимальная длина 20 символов
`messageListPicker.sections`	array (Максимум 10 элементов во всех `items`)	Поля `title` (string) - Заголовок секции с элементами, который отображается пользователю, максимальная длина 24 символа `items` (array)
`messageListPicker.section.items`	array	Поля `title` (string) - Название элемента, максимальная длина 24 символа `subTitle` (string (необязательно)) - Подзаголовок элемента, максимальная длина 72 символа `identifier` (string) – сквозной для всего сообщения ID элемента, вернется в ответном сообщении пользователя
`sendSurvey`	Boolean (необязательно)	Параметр указывает о необходимости отправлять опрос после закрытия треда. Если параметр отсутствует, то применяются настройки отправки опросов из АРМ администратора. Каждый последующий вызов с параметром перезаписывает предыдущее значение.

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

Пример curl

$ curl 'http://localhost:8080/api/v1/chatbot' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <token' \
    -H 'X-Tenant-Name: local' \
    -d '{
  "segmentationInfo" : {
    "key" : "value"
  ,
  "clientId" : "1",
  "threadsClientId" : 1,
  "receivedAt" : "2024-12-28T11:39:34.304Z",
  "text" : "testPostAnswersByClientId",
  "attachments" : [ {
    "url" : "http://test...",
    "name" : "testImage.png",
    "type" : "image/jpeg",
    "size" : 256,
    "contentType" : null,
    "fileId" : null,
    "state" : null,
    "errorCode" : null,
    "errorMessage" : 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>
X-Tenant-Name: local
Content-Length: 566
Host: localhost:8080

{
  "segmentationInfo" : {
    "key" : "value"
  },
  "clientId" : "1",
  "threadsClientId" : 1,
  "receivedAt" : "2024-12-28T11:39:34.304Z",
  "text" : "testPostAnswersByClientId",
  "attachments" : [
    {
      "url" : "http://test...",
      "name" : "testImage.png",
      "type" : "image/jpeg",
      "size" : 256,
      "contentType" : null,
      "fileId" : null,
      "state" : null,
      "errorCode" : null,
      "errorMessage" : null
    }
  ],
  "settings" : {
    "blockInput" : false,
    "masked" : true
  },
  "code" : "SWITCH_TO_HUMAN",
  "answerId" : "externalAnswerId"
}

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

HTTP/1.1 200 OK
X-Request-Id: a26146a5-0858-45f8-b914-a1731ab50c42
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

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

Пример curl

$ curl 'http://localhost:8080/api/v1/chatbot' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <token' \
    -H 'X-Tenant-Name: local' \
    -d '{
  "segmentationInfo" : {
    "key" : "value"
  ,
  "questionId" : 43,
  "receivedAt" : "2024-12-28T11:39:34.356Z",
  "text" : "testPostAnswersByClientId",
  "attachments" : [ {
    "url" : "http://test...",
    "name" : "testImage.png",
    "type" : "image/jpeg",
    "size" : 256,
    "contentType" : null,
    "fileId" : null,
    "state" : null,
    "errorCode" : null,
    "errorMessage" : 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>
X-Tenant-Name: local
Content-Length: 542
Host: localhost:8080

{
  "segmentationInfo" : {
    "key" : "value"
  },
  "questionId" : 43,
  "receivedAt" : "2024-12-28T11:39:34.356Z",
  "text" : "testPostAnswersByClientId",
  "attachments" : [
    {
      "url" : "http://test...",
      "name" : "testImage.png",
      "type" : "image/jpeg",
      "size" : 256,
      "contentType" : null,
      "fileId" : null,
      "state" : null,
      "errorCode" : null,
      "errorMessage" : null
    }
  ],
  "settings" : {
    "blockInput" : true,
    "masked" : false
  },
  "code" : "SWITCH_TO_HUMAN",
  "answerId" : "externalAnswerId"
}

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

HTTP/1.1 200 OK
X-Request-Id: a88aedba-36e1-4f0a-9c52-e01b3455d024
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

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

Пример curl

$ curl 'http://localhost:8080/api/v1/chatbot' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <token' \
    -H 'X-Tenant-Name: local' \
    -d '{
  "segmentationInfo" : { ,
  "sessionId" : "1",
  "questionIndex" : 3,
  "receivedAt" : "2024-12-28T11:39:34.383Z",
  "text" : "testPostAnswersByClientId",
  "attachments" : [ {
    "url" : "http://test...",
    "name" : "testImage.png",
    "type" : "image/jpeg",
    "size" : 256,
    "contentType" : null,
    "fileId" : null,
    "state" : null,
    "errorCode" : null,
    "errorMessage" : null
   ],
  "code" : "SWITCH_TO_HUMAN",
  "answerId" : "externalAnswerId"
'

Пример HTTP запроса

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
X-Tenant-Name: local
Content-Length: 475
Host: localhost:8080

{
  "segmentationInfo" : { },
  "sessionId" : "1",
  "questionIndex" : 3,
  "receivedAt" : "2024-12-28T11:39:34.383Z",
  "text" : "testPostAnswersByClientId",
  "attachments" : [
    {
      "url" : "http://test...",
      "name" : "testImage.png",
      "type" : "image/jpeg",
      "size" : 256,
      "contentType" : null,
      "fileId" : null,
      "state" : null,
      "errorCode" : null,
      "errorMessage" : null
    }
  ],
  "code" : "SWITCH_TO_HUMAN",
  "answerId" : "externalAnswerId"
}

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

HTTP/1.1 200 OK
X-Request-Id: 0e2b8474-c889-4355-9721-de3c180ba58d
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

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

Пример curl

$ curl 'http://localhost:8080/api/v1/chatbot' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <token' \
    -H 'X-Tenant-Name: local' \
    -d '{
  "segmentationInfo" : { ,
  "clientId" : "1",
  "threadsClientId" : 1,
  "receivedAt" : "2024-12-28T11:39:34.344Z",
  "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>
X-Tenant-Name: local
Content-Length: 614
Host: localhost:8080

{
  "segmentationInfo" : { },
  "clientId" : "1",
  "threadsClientId" : 1,
  "receivedAt" : "2024-12-28T11:39:34.344Z",
  "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
X-Request-Id: 236280d9-3e4d-41f8-a983-ca5c8a554144
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Поля тела запроса​

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

Пример curl​

Пример HTTP запроса​

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

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

Пример curl​

Пример HTTP запроса​

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

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

Пример curl​

Пример HTTP запроса​

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

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

Пример curl​

Пример HTTP запроса​

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

Поля тела запроса

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

Пример curl

Пример HTTP запроса

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

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

Пример curl

Пример HTTP запроса

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

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

Пример curl

Пример HTTP запроса

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

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

Пример curl

Пример HTTP запроса

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