AiHummer
Español▾
Iniciar sesiónCuenta
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
API/Disparadores de Entrada e Integración

Disparadores de Entrada e Integración

v1.2.x · actualizada 2026-07-27

Más allá de la API compatible con OpenAI, AiHummer acepta mensajes entrantes desde conectores y plataformas de automatización, y emite un flujo de eventos del lado del servidor a los que puedes suscribirte. Estos puntos finales son la forma en que los sistemas externos entregan trabajo al gateway y cómo las interfaces de usuario se mantienen activas.

Puntos de entrada entrantes

Los endpoints de entrada son la forma en que los conectores de canal y las integraciones personalizadas entregan un mensaje al motor de turnos. Están asegurados por un Secreto compartido HMAC enviado en el X-AIHummer-Inbound-Secret encabezado (el AIHUMMER_INBOUND_SECRET clave del catálogo de configuraciones — configurada en la interfaz de administración bajo Gestión → Configuraciones o con aihummer settings set, no en gateway.env).

Método y ruta Propósito
POST /v1/inbound/telegram Cargas útiles entrantes nativas de Telegram
POST /v1/inbound/generic Genérico de entrada para correo electrónico→webhook, cron y aplicaciones personalizadas
POST /v1/inbound/binding/status Informar el estado de la vinculación del canal

la genérica el endpoint es la forma más simple de alimentar cualquier fuente en AiHummer. Envía un pequeño cuerpo JSON con el nombre del canal, un identificador externo estable y el texto del mensaje:

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": "A customer asks whether order #4821 has shipped."
  }'

[!NOTE] El despachador de entrada genérico necesita un espacio de trabajo predeterminado. Configurar AIHUMMER_DEFAULT_WORKSPACE_ID para que los mensajes entrantes puedan ser enrutados.

[!WARNING] Los puntos de entrada entrantes no están protegidos por un ah- Clave API — dependen de la X-AIHummer-Inbound-Secret HMAC. Mantén ese secreto fuera del código del lado del cliente y gíralo si gotea.

Disparadores de integración (Zapier / Make)

POST /v1/integrations/trigger es el punto de entrada para plataformas de automatización de bajo código como Zapier y Hacer. El endpoint es desactivado por defecto: hasta AIHUMMER_INBOUND_TRIGGER_SECRET la configuración está configurada responde con 501 Not Implemented. Esto es una separar secreto, distinto de AIHUMMER_INBOUND_SECRET; como cada clave del catálogo de configuraciones, se establece en la interfaz de administración (Administración → Configuración) o con aihummer settings set.

Una vez configurado, el punto de acceso acepta cualquiera de X-AIHummer-Signature HMAC o un token Bearer del tipo Authorization: Bearer <the AIHUMMER_INBOUND_TRIGGER_SECRET value>.

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": "New lead captured from the contact form."
  }'

Backend de Admin Sessions

Estas dos rutas son el transporte interno conservado para la página Admin Sessions. No constituyen un canal insertable orientado al cliente.

Método y ruta Finalidad
POST /v1/web/session Abrir o volver a asociar una conversación de Admin Sessions
GET /v1/web/stream Transmitir la respuesta de la conversación mediante SSE

Flujo de eventos

GET /v1/events/stream es reanudable Fuente de Eventos Enviados por el Servidor de eventos del gateway. El endpoint tiene dos requisitos obligatorios:

  1. la ?workspace_id=<id> el parámetro es obligatorio — sin ello la solicitud es rechazado con 400. Un guardia de inquilino verifica que el espacio de trabajo pertenece a el inquilino del llamante; de otra persona workspace_id producciones 403.
  2. Se requiere autenticación — una sesión de administrador (cookie) o un ah- API llave en un Authorization: Bearer encabezado. Sin él, la respuesta es 401.

Pasar a ?since= cursor para reanudar desde donde la conexión anterior se quedó, de modo que una reconexión nunca pierde eventos.

# Subscribe from the beginning
curl -N -H "Authorization: Bearer ah-..." \
  "https://your-aihummer.example/v1/events/stream?workspace_id=<id>"

# Resume after a known cursor
curl -N -H "Authorization: Bearer ah-..." \
  "https://your-aihummer.example/v1/events/stream?workspace_id=<id>&since=<cursor>"

[!TIP] Trata el valor que lleva cada evento como el siguiente since cursor. Encendido reconectar, reproducir desde ese cursor para garantizar una entrega al menos una vez a su consumidor.

¿A dónde vamos ahora?