Intégrez par HTTPS, pas par diapositives
Déployez le chat serveur à serveur, diffusez les tokens en temps réel vers votre propre interface et déclenchez des automatisations via des webhooks qui aboutissent sur votre hôte FlexyAgents. Les routes ci-dessous sont les vrais gestionnaires Next.js : copiez les valeurs depuis Déploiement après avoir généré la connexion à l'API FlexyAgents.
- POST /api/agents/{agentId}/chat accepte Bearer liés à la connexion FlexyAgents d'automatisation et exécute la même pile RAG + modèle que le widget
- Le streaming optionnel renvoie des fragments JSON NDJSON ; sans streaming la réponse est un payload assistant unique
- Limites par IP avant les forfaits ; les forfaits hébergés appliquent budgets de tokens et BYOK renvoie erreurs explicites si la clé fournisseur manque
- Déclencheurs webhook, callbacks de canal et intégrations sortantes partagent le même modèle de tenancy — tout se résout à organization_id et agent
Besoin de clés avant ? Créer un espace de travail et ouvrez Paramètres → Clés API ou la modale de connexion de l'agent.
Surfaces HTTP en un coup d'œil
Les routes reflètent l'arborescence Next.js. Remplacez les espaces réservés par l'ID de l'agent et l'hôte affiché sur votre écran de déploiement.
- POST/api/agents/{agentId}/chat
Chat agent et streaming
Envoyez un corps JSON avec un array messages (role + content) et le flag stream optionnel. Bearer valide contre la clé API FlexyAgents stockée sur la connexion de l'agent ; avec clé correcte, organization_id se résout automatiquement.
- POST/api/webhooks/automations/...
Ingress déclencheurs d'automatisation
Les automatisations publiées peuvent exposer des URLs webhook qui désérialisent les payloads et appellent executeAutomation — utile quand vos services doivent lancer des flux sans OAuth.
- GET/POST/api/webhooks/*
Webhooks canal et fournisseur
Routes sœurs sous /api/webhooks gèrent WhatsApp, Instagram, Facebook Messenger, email entrant et callbacks similaires pour que le déploiement omnicanal reste sur votre domaine.
- —Integrations → Webhooks
Livraison sortante
Configurez des webhooks sortants signés depuis le panneau quand vous voulez que FlexyAgents pousse événements de conversation ou système vers votre SIEM, data lake ou pont ticketing.
Appel minimal sans streaming en temps réel
curl -X POST "https://VOTRE_HOST_APP/api/agents/ID_AGENT/chat" \
-H "Authorization: Bearer VOTRE_CLE_API_FLEXYAGENTS" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Bonjour"}],"stream":false}'Remplacez-les par les valeurs copiées depuis Déploiement → API après avoir connecté l'application FlexyAgents sur cet agent.
Invoquer
Chat HTTPS-first avec le même cerveau que le widget
L'écran de déploiement copie un curl contre votre host live. Le handler valide les clés API avec le store de connexions d'automatisation, charge comportement + connaissances et incrémente l'usage comme tout autre canal.
Contrat de l'array messages
Le corps doit inclure au moins un tour de chat. L'exécuteur trim l'historique au dernier message user pour la récupération mais accepte des arrays multi-tours pour usage futur.
- Rôles limités à user, assistant ou system dans le validateur
- Métadonnées en en-têtes seulement quand documenté — priorisez le contrat JSON
- Formes invalides renvoient 400 avec détail Zod pour déboguer plus vite
Mode streaming
Avec stream: true vous recevez des fragments NDJSON (un objet JSON par ligne) que le frontend peut afficher au fil des tokens.
- Idéal pour clients mobile ou desktop avec parité widget hébergé
- Erreurs en milieu de stream aussi sérialisées en lignes JSON
- Désactivez le streaming si les proxies tamponnent agressivement les réponses
Clés Bearer API vs cookies de session
Les comptes de service doivent utiliser la clé de connexion FlexyAgents générée par agent. Les tests interactifs peuvent utiliser session panneau, mais serveur à serveur toujours Bearer.
- Les clés sont chiffrées au repos aux côtés des autres credentials d'automatisation
- Faire tourner une clé ne change pas l'ID agent dans votre URL
- Clés invalides ou absentes renvoient 401 avant dépense modèle
Limites que vous verrez en production
Limites Redis renvoient 429 sur pics. Le forfait ajoute MESSAGE_LIMIT_REACHED pour plafonds mensuels hébergé/BYOK et plafonds de tokens en inférence hébergée.
- Automatisations et chat partagent la même comptabilité au niveau org
- Loggez les IDs de corrélation des erreurs en parlant au support
- Montez de forfait ou ajoutez crédits là où la facturation permet plus de débit
Événements
Amenez votre stack à FlexyAgents — et poussez des événements en retour
Les routes entrantes normalisent signatures fournisseur tandis que la config sortante vit aux côtés des autres intégrations. Les automatisations peuvent aussi POST HTTP arbitraire dans un flux.
Déclencheurs webhook d'automatisation
Quand un flux publie un déclencheur webhook, FlexyAgents stocke le segment de route et vérifie les payloads avant d'appeler executeAutomation avec le corps parsé.
- Combine avec étapes agent appelant Slack, CRMs ou REST sur mesure
- Le gating par forfait peut exiger niveau supérieur avant ingress générique
- Les logs apparaissent dans le même historique d'exécution que déclencheurs OAuth
Callbacks fournisseurs de canal
WhatsApp, Instagram DM, Messenger et email entrant enregistrent endpoints HTTPS publics pour que Meta, Twilio ou le courrier vérifient et livrent événements.
- Configurez URLs de callback dans la console fournisseur pour correspondre à votre host de déploiement
- Handshakes de vérification sur les mêmes routes que trafic live
- Garde payloads sensibles sur infra que vous auditez déjà
Actions HTTP sortantes
Les actions d'automatisation peuvent POST ou PUT vers URLs client avec corps templatisés — p.ex. « notifier Opsgenie » ou « créer ticket Jira » sans attendre connecteur first-party.
- Mappez champs déclencheur vers corps JSON avec le builder d'automatisations
- Retries et erreurs suivent les defaults de l'exécuteur d'automatisations
- Combine avec étapes agent pour résumés lisibles avant livraison
Référence
Spécifications, docs et outils exploratoires
Les pages marketing sont narratives ; les ingénieurs doivent s'appuyer sur /docs, définitions OpenAPI dans le repo et snippets de déploiement qui correspondent toujours à vos IDs tenant.
Hub documentation
Commencez sur /docs avec guides conceptuels et liez vers /api pour démarrages rapides, primers authentification et références en onglets quand disponibles.
- Exemples curl, JavaScript et patterns d'embed widget
- Promesses SDK/Postman doivent correspondre à ce que nous distribuons réellement
- Signalez lacunes via support pour aligner marketing et rédaction technique
OpenAPI comme source de vérité
Le dépôt inclut OpenAPI complet avec schémas auth, payloads chat et ressources REST auxiliaires — générez clients ou importez dans Postman depuis ce fichier.
- Versionnement suit le rythme des releases du package, pas cette landing
- URLs base staging et production dans servers du spec
- En local vous appelez le même path /api/agents/{id}/chat qu'en production sur votre host tenant
Widget et compagnons mobile
Toute expérience n'a pas besoin de REST brut — le script embarqué appelle le même endpoint chat avec contexte visiteur. Combinez API et widget pour self-service web et jobs backend.
- Les pages hébergées réutilisent la config agent que vous avez déjà testée
- CSP et cookies doivent autoriser l'origine widget que vous configurez
- Liens profonds depuis email peuvent ouvrir chat hébergé avec query params
Combinez les API avec Automatisations, Canaux et la gouvernance dans Analytics.
Étape suivante
Copiez un curl fonctionnel et préparez-le pour la production
Générez la clé de connexion FlexyAgents, collez-la dans votre coffre de secrets et pointez les webhooks d'automatisation vers les routes que vous contrôlez. Quand vous êtes prêt, branchez l'observabilité sur le même espace analytics que votre équipe Customer Success.