AiHummer доки
v1.0.x ▾
v1.0.x stable
RU EN
API /Входящие и интеграционные триггеры

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

v1.0.x · обновлено 2026-06-26

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

Inbound-эндпоинты

Inbound-эндпоинты — это способ для коннекторов каналов и собственных интеграций передать сообщение в turn-движок. Они защищены HMAC-секретом в заголовке X-AIHummer-Inbound-Secret (настраивается через AIHUMMER_INBOUND_SECRET).

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

Эндпоинт 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] Диспетчеру generic-inbound нужен рабочий workspace по умолчанию. Установите AIHUMMER_DEFAULT_WORKSPACE_ID, чтобы входящие можно было маршрутизировать.

[!WARNING] Inbound-эндпоинты не защищены ключом ah- — они полагаются на HMAC X-AIHummer-Inbound-Secret. Держите этот секрет вне клиентского кода и меняйте его при утечке.

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

POST /v1/integrations/trigger — точка входа для low-code платформ автоматизации, таких как Zapier и Make. Принимает либо HMAC X-AIHummer-Signature, либо Bearer-токен.

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

Веб-виджет

Встраиваемый веб-виджет использует два эндпоинта: один открывает сессию, другой стримит ответ ассистента.

Метод и путьНазначение
POST /v1/web/sessionОткрыть сессию виджета
GET /v1/web/streamПолучать ответы виджета по SSE
# 1) Открыть сессию
curl https://your-aihummer.example/v1/web/session \
  -H "Content-Type: application/json" \
  -d '{}'

# 2) Стримить ответы (Server-Sent Events)
curl -N https://your-aihummer.example/v1/web/stream

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

GET /v1/events/stream — это возобновляемый поток Server-Sent Events с событиями gateway. Передайте курсор ?since=, чтобы продолжить с того места, где оборвалось предыдущее соединение, — тогда переподключение не теряет события.

# Подписка с самого начала
curl -N https://your-aihummer.example/v1/events/stream

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

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

Куда дальше