# Подключение API-канала

API-канал позволяет передавать сообщения из собственного сервиса в ChatRex. ChatRex сразу подтверждает приём запроса, обрабатывает сообщение асинхронно и отправляет готовый ответ на указанный HTTPS webhook с HMAC-подписью.

Подготовьте:

• публичный HTTPS-адрес обработчика callback без query-параметров;
• секрет для проверки HMAC-подписи длиной не менее 32 символов;
• способ формировать уникальный request_id для каждого сообщения;
• стабильный client_id, по которому сообщения одного клиента объединяются в диалог;
• серверное хранилище для токена доступа и callback-секрета.

Если планируете передавать медиафайлы, ваш сервис также должен уметь отправлять запросы multipart/form-data и сохранять полученный media_id до отправки сообщения.

API-канал предназначен для серверной интеграции. Не вызывайте его напрямую из браузера или мобильного приложения: токен доступа станет доступен пользователю приложения.

1. В ChatRex откройте Интеграции.
2. Нажмите Подключить интеграцию.
3. На вкладке Каналы выберите API и нажмите Подключить.
4. Откройте вкладку Установка соединения.
5. Скопируйте URL для входящих сообщений.
6. Скопируйте Токен доступа и сразу сохраните его в защищённом хранилище вашего сервиса.

После создания API-канал получает статус Подключено и включается автоматически.

1. Откройте Мои боты и нажмите Изменить напротив нужного бота.
2. Перейдите во вкладку Каналы и запуск.
3. В блоке Условия по каналам нажмите Добавить канал.
4. Выберите созданный API-канал.
5. Настройте условия запуска и сохраните изменения.

Без назначения канала бот не будет обрабатывать входящие API-запросы.

Медиафайлы передаются в два этапа: сначала загрузите файл в ChatRex, затем укажите полученный media_id в сообщении.

URL загрузки находится рядом с URL входящих сообщений: замените окончание /messages на /uploads. Используйте тот же Bearer-токен API-канала.

POST https://api.example.com/api/channel/{ID_КАНАЛА}/uploads
Authorization: Bearer {ТОКЕН_ДОСТУПА}
Content-Type: multipart/form-data

Передайте два поля формы:

Пример с curl:

curl --request POST \
  --url "https://api.example.com/api/channel/{ID_КАНАЛА}/uploads" \
  --header "Authorization: Bearer {ТОКЕН_ДОСТУПА}" \
  --form "upload_id=order-42-photo" \
  --form "file=@./photo.png"

Успешная загрузка возвращает HTTP 201:

{
  "status": "uploaded",
  "upload_id": "order-42-photo",
  "media_id": "11111111-1111-4111-8111-111111111111",
  "type": "image",
  "name": "photo.png",
  "mime_type": "image/png",
  "size": 184203,
  "expires_at": "2026-08-12T15:00:00+00:00"
}

Поддерживаемые форматы:

Видео и архивы API-канал не принимает. ChatRex определяет фактический MIME-тип файла и сверяет его с расширением. По умолчанию максимальный размер одного файла — 25 МиБ.

Незакреплённая загрузка хранится 24 часа. До истечения срока повторная загрузка того же файла с тем же upload_id вернёт прежний media_id. Если содержимое отличается, ChatRex вернёт HTTP 409 с кодом upload_id_conflict — используйте новый upload_id.

Отправьте POST-запрос на скопированный URL для входящих сообщений. Передайте токен в заголовке Authorization по схеме Bearer и JSON в теле запроса.

POST {URL_КАНАЛА}
Authorization: Bearer {ТОКЕН_ДОСТУПА}
Content-Type: application/json

{
  "request_id": "req-20260808-0001",
  "client_id": "customer-12345",
  "message": "Подскажите стоимость доставки",
  "attachments": [
    {
      "media_id": "11111111-1111-4111-8111-111111111111"
    }
  ],
  "additional_info": "Заказ 00042, приоритетный клиент",
  "callback_url": "https://example.com/webhooks/chatrex",
  "callback_secret": "replace-with-a-random-secret-at-least-32-characters"
}

Поля attachments и additional_info необязательные. Поле message можно не передавать только при наличии хотя бы одного вложения. Остальные поля обязательны:

Успешный ответ на входящий запрос подтверждает только приём сообщения. Готовый ответ бота поступит отдельным запросом на callback_url.

В одном сообщении можно передать не более трёх вложений: максимум одно изображение, одно аудио и один документ. Общий размер вложений не должен превышать 80 МиБ.

ChatRex использует вложения в той же обработке, что текст сообщения и additional_info:

• изображение передаётся в контур распознавания изображений;
• аудио расшифровывается, и транскрипция учитывается при генерации ответа;
• документ передаётся модели как файловый ввод.

Сообщение может состоять только из вложения. Например:

{
  "request_id": "req-20260808-0002",
  "client_id": "customer-12345",
  "attachments": [
    {
      "media_id": "11111111-1111-4111-8111-111111111111"
    }
  ],
  "callback_url": "https://example.com/webhooks/chatrex",
  "callback_secret": "replace-with-a-random-secret-at-least-32-characters"
}

Каждый media_id можно закрепить только за одним входящим запросом. Повторная отправка полностью идентичного запроса с тем же request_id безопасна и вернёт существующую квитанцию. Для другого сообщения загрузите файл с новым upload_id и используйте новый media_id.

Вложения входят в состав идемпотентного запроса. Если изменить состав или порядок attachments, сохранив прежний request_id, ChatRex вернёт HTTP 409 с кодом request_id_conflict.

При ошибке ChatRex возвращает JSON с кодом в поле error.code. Основные коды:

Используйте additional_info, если вместе с сообщением нужно передать боту сведения из вашей системы, например статус заказа, категорию клиента или выбранный тариф.

ChatRex добавляет непустое значение в дополнительный системный контекст текущей обработки с пометкой Дополнительная информация. При этом значение:

• не добавляется в текст сообщения клиента;
• не возвращается в callback;
• не используется для выбора бота и проверки условий запуска;
• не переносится автоматически в следующий API-запрос.

Если контекст нужен при обработке следующего сообщения, передайте его повторно. Не помещайте в additional_info пароли, токены, платёжные реквизиты и другие секреты: содержимое поля передаётся модели при генерации ответа.

additional_info входит в состав идемпотентного запроса. Повтор с теми же request_id и данными не создаёт новое сообщение. Если изменить additional_info или другое поле, сохранив прежний request_id, ChatRex вернёт HTTP 409 с кодом request_id_conflict. Для изменённого запроса сформируйте новый request_id.

Обработчик callback должен:

1. принимать HTTPS-запросы от ChatRex;
2. проверять HMAC-подпись с помощью callback_secret до обработки данных;
3. сопоставлять результат с исходным запросом по request_id;
4. сохранять ответ или передавать его клиенту только после успешной проверки подписи;
5. возвращать успешный HTTP-статус после приёма результата.

Не записывайте токен, callback-секрет и полное содержимое обращений в общедоступные логи. Ограничьте доступ к журналам и храните секреты отдельно от исходного кода.

1. Назначьте API-канал тестовому боту.
2. Отправьте запрос с новым request_id и тестовым client_id.
3. Убедитесь, что ChatRex подтвердил приём запроса.
4. Проверьте получение callback на указанном HTTPS-адресе.
5. Убедитесь, что HMAC-подпись прошла проверку и ответ относится к нужному request_id.
6. Проверьте диалог в разделах Чаты и История ChatRex.
7. Отправьте второе сообщение с тем же client_id и новым request_id, чтобы проверить продолжение диалога.
8. Для проверки медиа загрузите тестовый файл, передайте его media_id в attachments и убедитесь, что ответ учитывает содержимое файла.

Проверьте:

• используется ли актуальный токен и заголовок Authorization: Bearer;
• отправляется ли запрос на URL нужного API-канала;
• заполнены ли все обязательные поля;
• передан ли message или хотя бы один объект в attachments;
• является ли additional_info строкой длиной не более 10 000 символов или значением null;
• получен ли каждый media_id через endpoint /uploads именно этого API-канала;
• не истекли ли 24 часа с момента загрузки незакреплённого файла;
• не использовался ли media_id ранее в другом запросе;
• не превышены ли ограничения: один файл каждого типа, до трёх вложений, до 25 МиБ на файл и до 80 МиБ суммарно;
• совпадает ли расширение файла с его фактическим MIME-типом и поддерживается ли формат;
• уникален ли request_id;
• начинается ли callback_url с https:// и отсутствуют ли в нём query-параметры;
• содержит ли callback_secret не менее 32 символов;
• доступен ли callback из интернета и принимает ли он входящие запросы;
• назначен ли канал боту и подходят ли условия запуска;
• активны ли интеграция и подписка.

Если токен мог попасть в логи, репозиторий или клиентское приложение, немедленно перевыпустите его и обновите секрет в вашем серверном хранилище.