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

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

<h2 id="konfiguraciya" align="center">Конфигурация</h2>

### Ссылка вебхука <a href="#ssylka-vebkhuka" id="ssylka-vebkhuka"></a>

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

**Пример:**

```http
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 сообщения (если не указан — создаётся автоматически)                                                |

{% hint style="info" %}
Для передачи изображений, документов или аудио используйте поля `image_url`/`image_urls`, `document_url`/`document_urls` или `audio_url`. Поле `text` при этом опционально — может служить подписью к файлу.
{% endhint %}

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

<h2 align="center">Пример: обработка вебхука от платёжной системы</h2>

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

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

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

<figure><img src="/files/tjw0rz6dXCgsxg3TpLCf" alt=""><figcaption></figcaption></figure>

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

1. Извлекаем тело входящего запроса (`args["request"]`)
2. Получаем `dialog_id` из `metadata`
3. Формируем человекочитаемый текст сообщения
4. Возвращаем результат в формате Nextbot

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

```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"
}
```

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

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

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

<figure><img src="/files/JylVml0UhBvDiNWUVtlW" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Для включения режима отладки добавьте параметр `?debug=true` к URL вебхука. В ответе вы получите подробные логи выполнения запроса.
{% endhint %}

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

* `dialog_id` **должен существовать** в Nextbot
* Адаптер может обрабатывать **любую структуру данных**
* В одном адаптере можно:
  * валидировать подписи вебхуков
  * проверять статус событий
  * фильтровать ненужные уведомления
  * формировать разные сообщения в зависимости от типа события


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.nextbot.ru/functional/integrations/vebkhuki/nuzhna-obrabotka-cherez-adapter.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.