AiHummer
Français▾
ConnexionCompte
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
API/Déclencheurs entrants et d'intégration

Déclencheurs entrants et d'intégration

v1.2.x · mis à jour 2026-07-27

Au-delà de l’API compatible avec OpenAI, AiHummer accepte messages entrants à partir de connecteurs et de plateformes d’automatisation, et émet un flux d’événements côté serveur vous pouvez vous abonner. Ces points de terminaison sont la manière dont les systèmes externes transmettent du travail à la passerelle et la manière dont les interfaces utilisateur restent actives.

Points de terminaison entrants

Les points de terminaison entrants sont la manière dont les connecteurs de canal et les intégrations personnalisées transmettent un message au moteur de dialogue. Ils sont sécurisés par un Secret partagé HMAC envoyé dans le X-AIHummer-Inbound-Secret en-tête (le AIHUMMER_INBOUND_SECRET clé du catalogue de paramètres — configurée dans l’interface d’administration sous Gestion → Paramètres ou avec aihummer settings set, pas dans gateway.env).

Méthode et chemin But
POST /v1/inbound/telegram Charges utiles entrantes natives de Telegram
POST /v1/inbound/generic Entrée générique pour email→webhook, cron et applications personnalisées
POST /v1/inbound/binding/status Signaler l’état de liaison du canal

Le générique le point de terminaison est le moyen le plus simple d’alimenter n’importe quelle source dans AiHummer. Envoyez un petit corps JSON avec le nom du canal, un identifiant externe stable et le texte du message :

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] Le dispatcher entrant générique a besoin d’un espace de travail par défaut. Définir AIHUMMER_DEFAULT_WORKSPACE_ID afin que les messages entrants puissent être acheminés.

[!WARNING] Les points de terminaison entrants ne sont pas protégés par un ah- Clé API — ils comptent sur le X-AIHummer-Inbound-Secret HMAC. Gardez ce secret hors du code côté client et faites-le tourner s’il fuit.

Déclencheurs d’intégration (Zapier / Make)

POST /v1/integrations/trigger est le point d’entrée pour les plateformes d’automatisation low-code telles que Zapier et Faire. Le point de terminaison est désactivé par défaut: jusqu’à AIHUMMER_INBOUND_TRIGGER_SECRET le réglage est configuré, il répond avec 501 Not Implemented. Ceci est un séparer secret, distinct de AIHUMMER_INBOUND_SECRET; comme chaque clé du catalogue de paramètres, elle est définie dans l’interface d’administration (Gestion → Paramètres) ou avec aihummer settings set.

Une fois configuré, le point de terminaison accepte soit un X-AIHummer-Signature HMAC ou un jeton Bearer de la forme 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 Admin Sessions

Ces deux routes constituent le transport interne conservé pour la page Admin Sessions. Elles ne forment pas un canal client intégrable pris en charge.

Méthode et chemin Rôle
POST /v1/web/session Ouvrir ou rattacher une conversation Admin Sessions
GET /v1/web/stream Diffuser la réponse de la conversation en SSE

Flux d’événements

GET /v1/events/stream est reprenable Flux d’événements envoyés par le serveur des événements de la passerelle. Le point de terminaison a deux exigences strictes :

  1. Le ?workspace_id=<id> le paramètre est obligatoire — sans cela, la demande est rejeté avec 400. Un agent de sécurité du locataire vérifie que l’espace de travail appartient à le locataire de l’appelant ; celui d’une autre personne workspace_id rendements 403.
  2. L’authentification est requise — une session admin (cookie) ou un ah- API clé dans un Authorization: Bearer en-tête. Sans lui, la réponse est 401.

Passe ?since= curseur pour reprendre là où une connexion précédente s’était arrêtée, de sorte qu’une reconnexion ne perde jamais d’événements.

# 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] Considérez la valeur portée par chaque événement comme la suivante since curseur. Activé reconnecter, rejouer depuis ce curseur pour garantir une livraison au moins une fois à votre consommateur.

Où aller ensuite