AiHummer
Русский▾
ВойтиЛичный кабинет
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
API/Входящие и интеграционные триггеры

Входящие и интеграционные триггеры

v1.2.x · обновлено 2026-07-27

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

Входящие endpoints

Входящие endpoints (в API — inbound) — это способ для коннекторов каналов и собственных интеграций передать сообщение в движок обработки запросов. Они защищены HMAC-секретом в заголовке X-AIHummer-Inbound-Secret (настройка AIHUMMER_INBOUND_SECRET из каталога настроек — задаётся в веб-интерфейсе «Управление → Настройки» или командой aihummer settings set, а не в gateway.env).

Метод и путь Назначение
POST /v1/inbound/telegram Нативные входящие payload-ы Telegram
POST /v1/inbound/generic Универсальный входящий вебхук для почты, cron и своих приложений
POST /v1/inbound/binding/status Отчёт о статусе привязки канала

Endpoint generic — самый простой способ подать любой источник в AiHummer. Отправьте небольшое JSON-тело с именем канала, стабильным внешним идентификатором и текстом сообщения:

curl https://your-aihummer.example/v1/inbound/generic \
  -H "X-AIHummer-Inbound-Secret: $AIHUMMER_INBOUND_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "external_id": "ticket-4821",
    "text": "Клиент спрашивает, отгружен ли заказ #4821."
  }'

[!NOTE] Диспетчеру универсального входящего вебхука нужно рабочее пространство по умолчанию. Установите AIHUMMER_DEFAULT_WORKSPACE_ID, чтобы входящие можно было маршрутизировать.

[!WARNING] Что произойдёт: злоумышленник сможет подавать поддельные входящие сообщения. При каком условии: если утечёт HMAC-секрет X-AIHummer-Inbound-Secret — входящие endpoints не защищены ключом ah-. Как исправить: держите секрет вне клиентского кода и при утечке сразу смените его в настройках.

Интеграционные триггеры (Zapier / Make)

POST /v1/integrations/trigger — точка входа для low-code платформ автоматизации, таких как Zapier и Make. Endpoint выключен по умолчанию: пока не задана настройка AIHUMMER_INBOUND_TRIGGER_SECRET, он отвечает 501 Not Implemented. Это отдельный секрет, не совпадающий с AIHUMMER_INBOUND_SECRET; как и все параметры каталога настроек, он задаётся в веб-интерфейсе («Управление → Настройки») или командой aihummer settings set.

Настроенный endpoint принимает либо HMAC X-AIHummer-Signature, либо Bearer-токен вида Authorization: Bearer <значение AIHUMMER_INBOUND_TRIGGER_SECRET>.

curl https://your-aihummer.example/v1/integrations/trigger \
  -H "Authorization: Bearer $AIHUMMER_INBOUND_TRIGGER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "zapier",
    "external_id": "lead-99",
    "text": "Новый лид из формы обратной связи."
  }'

Backend Admin Sessions

Эти два маршрута сохранены как внутренний транспорт страницы Admin Sessions. Это не поддерживаемый встраиваемый клиентский канал.

Метод и путь Назначение
POST /v1/web/session Открыть или продолжить диалог Admin Sessions
GET /v1/web/stream Получать ответ диалога по SSE

Поток событий

GET /v1/events/stream — это возобновляемый поток Server-Sent Events с событиями шлюза. У endpoint два обязательных требования:

  1. Параметр ?workspace_id=<id> обязателен — без него запрос отклоняется с 400. Tenant-guard проверяет, что указанное рабочее пространство принадлежит арендатору вызывающего; чужой workspace_id даёт 403.
  2. Нужна аутентификация — admin-сессия (cookie) либо API-ключ ah- в заголовке Authorization: Bearer. Без неё — 401.

Передайте курсор ?since=, чтобы продолжить с того места, где оборвалось предыдущее соединение, — тогда переподключение не теряет события.

# Подписка с самого начала
curl -N -H "Authorization: Bearer ah-..." \
  "https://your-aihummer.example/v1/events/stream?workspace_id=<id>"

# Возобновление после известного курсора
curl -N -H "Authorization: Bearer ah-..." \
  "https://your-aihummer.example/v1/events/stream?workspace_id=<id>&since=<cursor>"

[!TIP] Считайте значение, которое несёт каждое событие, следующим курсором since. При переподключении воспроизводите с этого курсора, чтобы гарантировать доставку «не менее одного раза» вашему потребителю.

Куда дальше