Вебхук по правилам Nextbot

Способ подключения "Вебхук по правилам Nextbot" можно использовать, когда внешний сервис может отправлять вебхук в предопределенном JSON-формате. Это удобный способ интеграции, не требующий написания скрипта-адаптера.

Конфигурация

Ссылка вебхука

URL-адрес (endpoint) для получения вебхука находится в поле "Ссылка вебхука" на главной странице интеграции. Используйте этот URL для отправки POST-запросов с данными вебхука.

Пример:

https://app.nextbot.ru/api/webhooks/v1/682db757-7981-4bd4-8bb4-61bd1665a29/923ef269bf224bacadafb5ab05a2e75

Если необходимо обновить токен (например, при компрометации старого), нажмите кнопку "Обновить токен". Прежний URL станет недействительным.

Формат входящего JSON

Отправляйте POST-запрос с JSON-телом в указанном формате. Через вебхуки можно передавать не только текст, но и изображения, документы и аудио.

Поле	Тип	Статус	Описание
dialog_id	number	обязательно	ID существующего диалога в Nextbot
content_type	string	опционально	Тип контента. Если не указан, определяется автоматически по файловым полям (или text по умолчанию). Возможные значения: text — текстовое сообщение; image — сообщение с image_url/image_urls; document — сообщение с document_url/document_urls; audio — сообщение с audio_url
text	string	опционально	Текст сообщения. Обязателен для content_type=text, для файловых сообщений — опционален (подпись/контекст)
image_url / image_urls	string / string[]	опционально	URL изображения (или массив image_urls) для content_type=image
document_url / document_urls	string / string[]	опционально	URL документа (или массив document_urls) для content_type=document
audio_url	string	опционально	URL аудиофайла для content_type=audio
message_type	string	опционально	Тип сообщения. По умолчанию: input. См. раздел «Типы сообщений» ниже
message_id	string	опционально	Уникальный ID сообщения. Если не указан — генерируется автоматически (UUID)

Для включения режима отладки добавьте параметр ?debug=true к URL вебхука. В ответе вы получите подробные логи выполнения запроса.

Типы сообщений (message_type)

В зависимости от значения message_type сообщение будет обработано по-разному. Доступны четыре типа, каждый из которых определяет, как сообщение появится в диалоге:

input

Имитация входящего сообщение от клиента (не будет отправлено клиенту в диалог)

forwarded_output

Текст будет отправлен клиенту в мессенджер как обычное сообщение от ИИ-Агента

output

Текст сохраняется как отправленное сообщение оператора. Используется только для контекста ИИ-агента и не отображается клиенту

notification

Текст придёт как системное уведомление (не будет отправлено клиенту в диалог)

Отправка тестового запроса

Для примера используем JSON с типом сообщения message_type = "notification":

{
  "dialog_id": 10177062,
  "text": "проверка вебхука",
  "message_type": "notification"
}

Пример отправки изображения с подписью:

{
  "dialog_id": 10177062,
  "content_type": "image",
  "image_url": "https://example.com/photo.jpg",
  "text": "Подпись к изображению"
}

Для нескольких изображений используйте image_urls (массив URL). Аналогично для документов — document_url или document_urls; для аудио — audio_url.

Отправим на наш URL и получим ответ:

200 OK "Webhook received and queued for processing" — значит вебхук успешно отправлен

На скриншоте показан результат обработки вебхука: в диалоге появилось входящее сообщение от клиента, как если бы оно было отправлено через обычный канал связи.