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

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

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

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

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

**Пример:**

```http
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)                                                                                                                                                                                                                   |

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

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

### Типы сообщений (message\_type)

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

{% tabs %}
{% tab title="input" %}
Имитация входящего сообщение от клиента (не будет отправлено клиенту в диалог)

<div align="left"><figure><img src="/files/qjSOReZYDOjdozKbTjdW" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="forwarded\_output" %}
Текст будет отправлен клиенту в мессенджер как обычное сообщение от ИИ-Агента

<div align="left"><figure><img src="/files/nZWTAkEhd1MHhcwUmukG" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="output" %}
Текст сохраняется как отправленное сообщение оператора. Используется только для контекста ИИ-агента и не отображается клиенту

<div align="left"><figure><img src="/files/i2yNbqQLjOBFo17Bv5Et" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="notification" %}
Текст придёт как системное уведомление (не будет отправлено клиенту в диалог)

<div align="left"><figure><img src="/files/hloAr8yeQVOujPl5hc84" alt=""><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

<h2 align="center">Отправка тестового запроса</h2>

Для примера используем 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 и получим ответ:

<mark style="color:green;">200 OK</mark> "Webhook received and queued for processing" — значит вебхук успешно отправлен

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

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

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


---

# 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/vebkhuk-po-pravilam-nextbot.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.