Нужна обработка (через адаптер)

"Нужна обработка (через адаптер)" — способ подключения для работы с данными в любом формате. Требует создания Python-скрипта, который преобразует входящие данные в формат, понятный платформе Nextbot.

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

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

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

Пример:

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

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

Как работает адаптер

Адаптер — это Python-скрипт, который принимает входящий вебхук в произвольном формате и преобразует его в стандартный формат для Nextbot.

Он используется в тех случаях, когда сторонний сервис не может отправлять данные сразу в формате Nextbot.

Общая схема работы

1. Сторонний сервис отправляет POST-запрос на ваш URL вебхука. Формат данных — JSON с произвольной структурой.

2. Входящий запрос передаётся в адаптер. Адаптер получает:

   • тело запроса

   • HTTP-заголовки

   • служебные метаданные

3. Python-адаптер:

   • извлекает нужные поля из входящих данных

   • формирует сообщение (текст, изображения, документы, аудио)

   • указывает dialog_id

   • возвращает результат в формате Nextbot

Данные, доступные в адаптере

В адаптере доступен объект args, содержащий входящие данные:

Поле	Тип	Описание
args["request"]	dict	JSON-тело входящего запроса (структура зависит от стороннего сервиса)
args["headers"]	dict	HTTP-заголовки запроса (например, content_type, user_agent)
args["meta"]	dict	Метаданные (agent_hash, url_token)

Что должен вернуть адаптер

Python-скрипт обязан вернуть result следующего формата. Через адаптер можно передавать не только текст, но и изображения, документы и аудио.

Поле	Тип	Обязательно	Описание
dialog_id	int	✅	ID существующего диалога в Nextbot
content_type	str	⛔	Тип контента: text, image, document, audio. Если не указан — определяется автоматически по файловым полям
text	str	⛔	Текст сообщения. Обязателен для content_type=text, для файловых сообщений — опционален (подпись/контекст)
image_url / image_urls	str или list	⛔	URL изображения (или список URL) для content_type=image
document_url / document_urls	str или list	⛔	URL документа (или список URL) для content_type=document
audio_url	str	⛔	URL аудиофайла для content_type=audio
message_type	str	⛔	Тип сообщения: input, forwarded_output, output, notification. По умолчанию input
message_id	str	⛔	Уникальный ID сообщения (если не указан — создаётся автоматически)

Для передачи изображений, документов или аудио используйте поля image_url/image_urls, document_url/document_urls или audio_url. Поле text при этом опционально — может служить подписью к файлу.

Раскройте вкладку "Пример: уведомление о платеже", чтобы увидеть готовый пример с входящим запросом, Python-адаптером и результатом его работы

Пример: обработка вебхука от платёжной системы

Настройте функцию в Nextbot, которая после выполнения будет отправлять ID диалога (номер диалога) во внешнюю систему, например, через Custom API.

После этого платёжная система отправляет уведомление об успешной оплате. ID диалога передаётся в поле metadata.dialog_id (настраивается при создании платежа).

Вот пример JSON, который приходит через вебхук. Это произвольный формат данных, который еще не соответствует стандарту Nextbot:

Логика работы адаптера

1. Извлекаем тело входящего запроса (args["request"])

2. Получаем dialog_id из metadata

3. Формируем человекочитаемый текст сообщения

4. Возвращаем результат в формате Nextbot

Пример Python-кода адаптера

request = args.get("request", {})

metadata = request.get("metadata", {})
dialog_id = metadata.get("dialog_id")
if not dialog_id:
    raise ValueError("dialog_id not found in metadata")

amount = request.get("amount", {})
amount_value = amount.get("value", "0")
currency = amount.get("currency", "RUB")

card_info = request.get("payment_method", {}).get("card", {})
last4 = card_info.get("last4", "****")

order_id = metadata.get("order_id", "—")

text = f"Оплата получена: {amount_value} {currency} (карта *{last4}). Заказ: {order_id}"

result = {
    "dialog_id": int(dialog_id),
    "text": text,
    "message_type": "output"
}

Результат работы адаптера

{
  "dialog_id": 10177062,
  "text": "Оплата получена: 5500.00 RUB (карта *4242). Заказ: ORD-789",
  "message_type": "output"
}

Сообщение появляется в указанном диалоге Nextbot, при этом его тип (input, output или forwarded_output) определяется настройкой message_type в адаптере:

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

Важно учитывать

• dialog_id должен существовать в Nextbot

• Адаптер может обрабатывать любую структуру данных

• В одном адаптере можно:

  • валидировать подписи вебхуков

  • проверять статус событий

  • фильтровать ненужные уведомления

  • формировать разные сообщения в зависимости от типа события