API Канал

Здесь мы рассмотрим, как подключить канал, через который ваша внешняя система (CRM, сайт, бот, мобильное приложение и т.д.) обменивается сообщениями с ИИ-агентом на платформе. Вы отправляете сообщения клиента на платформу, агент их обрабатывает и присылает ответ на ваш сервер через вебхук.

Подключение API канала за 4 шага

Endpoint уже выдан платформой. Это адрес, на который ваша система отправляет сообщения клиентов. Найти его можно в настройках канала, в поле API Endpoint URL.
Создайте активный API-ключ. Ключ нужен для аутентификации входящих запросов — платформа проверяет его в заголовке каждого запроса. Значение ключа показывается только один раз в момент создания, поэтому скопируйте и сохраните его сразу в надёжном месте.
Укажите Webhook URL. Это HTTPS-адрес вашего сервера, на который платформа будет отправлять ответы агента, сообщения оператора и другие события диалога.
Готово. После сохранения настроек канал начинает принимать входящие сообщения и отправлять ответы на ваш вебхук.

Настройки канала

API Endpoint URL

Постоянный адрес платформы, на который ваша система должна слать запросы с сообщениями клиентов. Этот адрес присваивается каналу автоматически и не меняется.

API-ключи

Раздел, где создаются и хранятся ключи для аутентификации запросов:

ключ передаётся в заголовке X-API-Key при каждом запросе к платформе;
значение ключа отображается только один раз при создании — если вы его не скопировали, придётся создать новый;
ключ можно сделать неактивным или удалить, если он скомпрометирован;
для каждого ключа платформа показывает дату создания и название, но ключ невозможно будет просмотреть еще раз после создания.

Важно: если ключ неверный, удалён или неактивен, платформа вернёт ошибку 401.

Исходящий вебхук

Для работы канала нужен сервер с публичным HTTPS-адресом — именно на него платформа будет присылать ответы агента и другие события.

Настройки вебхука:

Параметр	Описание
Webhook URL (обязательно)	HTTPS-адрес вашего сервера, принимающего события.
Заголовки	Дополнительные HTTP-заголовки, которые платформа добавит к каждому запросу на ваш сервер (например, для собственной авторизации на вашей стороне).
Таймаут ответа, сек	Сколько секунд платформа ждёт ответ от вашего сервера. По умолчанию — 300 секунд.

После настройки можно нажать «Тест вебхука», чтобы отправить тестовое событие и убедиться, что сервер его принимает.

Правило доставки: вебхук считается успешно доставленным, если ваш сервер вернул любой HTTP-статус 2xx. Если сервер ответил ошибкой или не ответил вовсе, платформа повторит отправку по retry-механизму.

Фильтры сообщений

Позволяют выбрать, какие события вебхук должен присылать:

Основные фильтры
- Сообщения клиента — входящие сообщения от конечного пользователя.
- Ответы ИИ-агента — сообщения, сгенерированные агентом.
Расширенные фильтры — дополнительные типы событий (например, вызовы инструментов агентом, системные сообщения) для более детального контроля над тем, что приходит на ваш сервер.

Суб-каналы (опционально)

Суб-каналы позволяют разделить входящий трафик внутри одного API Channel по источникам — например, отдельно сайт, отдельно CRM, отдельно чат-бот. Это вспомогательная функция: канал полноценно работает и без неё, использовать суб-каналы стоит только если вам нужно логически разделять потоки сообщений из разных систем внутри одного подключения.

3. Отправка сообщений на платформу

Все запросы отправляются методом POST на адрес:

https://core.example.com/api/v1/channels/api/messages

с заголовками:

X-API-Key: <ваш api_key>
Content-Type: application/json

3.1. Текстовое сообщение

Для отправки текста используется message_type: "text".

curl -X POST "https://core.example.com/api/v1/channels/api/messages" \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "deal-123",
    "source": "crm",
    "from_type": "user",
    "from_name": "Иван",
    "message_type": "text",
    "data": {
      "text": "Здравствуйте, хочу узнать цену"
    }
  }'

Поля запроса:

Поле	Обязательное	Описание
`thread_id`	Да	Стабильный ID диалога в вашей системе. По нему платформа понимает, что это сообщения одного и того же разговора.
`source`	Нет	Источник сообщения (например, `crm`, `site`). Если не передан — используется `default`.
`from_type`	Нет	Кто отправитель: `user` или `manager`. По умолчанию `user`.
`from_name`	Нет	Имя отправителя — отображается в интерфейсе диалога.
`message_type`	Нет	Тип сообщения. Для текста: `text` (значение по умолчанию).
`data.text`	Да	Текст сообщения.

Успешный ответ:

{
  "accepted": true,
  "thread_id": "api:crm:deal-123",
  "external_thread_id": "deal-123",
  "source": "crm"
}

thread_id в ответе — это полный внутренний ID диалога в формате api:{source}:{ваш thread_id}.
external_thread_id — исходный thread_id, который вы передали в запросе. Сохраняйте соответствие между этими двумя значениями на своей стороне, это пригодится при обработке вебхуков.

3.2. Сообщение с файлом

Для отправки файла используется message_type: "multi". Файл можно передать двумя способами:

url — платформа сама скачает файл по HTTP/HTTPS-адресу;
data — файл передаётся как base64-строка прямо в запросе.

В одном attachment должен быть ровно один из этих источников — либо url, либо data, но не оба одновременно.

Файл по URL:

curl -X POST "https://core.example.com/api/v1/channels/api/messages" \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "deal-123",
    "source": "crm",
    "from_type": "user",
    "from_name": "Иван",
    "message_type": "multi",
    "data": {
      "text": "Отправляю документ",
      "attachments": [
        {
          "url": "https://client.example.com/files/contract.pdf",
          "filename": "contract.pdf",
          "mime_type": "application/pdf"
        }
      ]
    }
  }'

Файл в base64:

FILE_BASE64="$(base64 -i contract.pdf)"

curl -X POST "https://core.example.com/api/v1/channels/api/messages" \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d "{
    \"thread_id\": \"deal-123\",
    \"source\": \"crm\",
    \"from_type\": \"user\",
    \"message_type\": \"multi\",
    \"data\": {
      \"text\": \"Отправляю документ\",
      \"attachments\": [
        {
          \"data\": \"$FILE_BASE64\",
          \"filename\": \"contract.pdf\",
          \"mime_type\": \"application/pdf\"
        }
      ]
    }
  }"

Поля attachment:

Поле	Обязательное	Описание
`url`	Да, если нет `data`	HTTP/HTTPS-адрес файла.
`data`	Да, если нет `url`	Содержимое файла в base64.
`filename`	Да	Имя файла.
`mime_type`	Нет	MIME-тип файла.

Ограничения:

максимальный размер файла — 20 MB;
URL файла обязательно должен начинаться с http:// или https://;
запрос с message_type: "multi" должен содержать хотя бы один attachment;
если base64-строка невалидна, платформа вернёт 422;
если файл превышает лимит в 20 MB, платформа вернёт 413.

Формат успешного ответа такой же, как при отправке текстового сообщения.

4. Получение ответов: вебхук

Платформа отправляет события на ваш Webhook URL, указанный в настройках канала. Адрес обязательно должен быть HTTPS.

Пример: текстовый ответ агента

{
  "event_id": "f05a0fd4-4d6d-4a3c-8b98-4a7b1a2b7f2e",
  "event_type": "agent_message",
  "thread_id": "api:crm:deal-123",
  "external_thread_id": "deal-123",
  "source": "crm",
  "source_name": "CRM",
  "created_at": "2026-06-12T10:15:30.000000+00:00",
  "message": {
    "id": "665f2b7a4b2f6d1f0f3a5678",
    "from_type": "agent",
    "from_name": null,
    "message_type": "text",
    "data": {
      "text": "Здравствуйте! Цена зависит от тарифа."
    },
    "at": "2026-06-12T10:15:29.000000+00:00"
  }
}

Пример: ответ агента с файлом

{
  "event_id": "9e8d44e0-89ff-4d0a-9a1d-b1f52f3423b2",
  "event_type": "agent_message",
  "thread_id": "api:crm:deal-123",
  "external_thread_id": "deal-123",
  "source": "crm",
  "source_name": "CRM",
  "created_at": "2026-06-12T10:16:30.000000+00:00",
  "message": {
    "id": "665f2c0a4b2f6d1f0f3a5678",
    "from_type": "agent",
    "from_name": null,
    "message_type": "multi",
    "data": {
      "text": "Документ во вложении",
      "attachments": [
        {
          "file_id": 123,
          "reader_file_id": null,
          "filename": "offer.pdf",
          "url": "https://core.example.com/api/v1/storage/files/123/content?token=..."
        }
      ]
    },
    "at": "2026-06-12T10:16:29.000000+00:00"
  }
}

Поля payload

Поле	Описание
`event_id`	Уникальный ID события вебхука.
`event_type`	Тип события (см. таблицу ниже).
`thread_id`	Полный внутренний ID диалога в формате `api:{source}:{thread_id}`.
`external_thread_id`	Исходный `thread_id`, который вы передавали в своём запросе.
`source`	Источник сообщения.
`source_name`	Отображаемое название источника из настроек канала.
`created_at`	Время создания события вебхука.
`message`	Содержимое сообщения (текст и/или вложения).

Типы событий (`event_type`)

event_type	Когда отправляется
`user_message`	В диалог добавлено новое сообщение от клиента.
`agent_message`	Агент отправил ответ.
`manager_message`	Оператор отправил сообщение вручную.
`tool_call`	Агент вызвал инструмент / функцию.
`tool_result`	Получен результат выполнения инструмента / функции.
`system_message`	Системное сообщение (например, техническое уведомление о диалоге).

Какие из этих событий реально будут приходить на ваш сервер, зависит от настроенных фильтров сообщений в канале (см. раздел 2).

5. Обработка ошибок

HTTP-статус	Причина
`401`	Неверный, удалённый или неактивный `X-API-Key`.
`403`	Канал отключён или не подключён (not connected).
`422`	Невалидный payload запроса.
`413`	Файл превышает лимит 20 MB.

Частые причины ошибки 422:

не передан обязательный thread_id;
from_type указан со значением, отличным от user или manager;
текстовое сообщение (message_type: "text") отправлено без data.text;
сообщение с файлом (message_type: "multi") отправлено без data.attachments;
в attachment одновременно переданы и url, и data, либо не передано ни одного из них — допускается только один источник.