Integrieren über HTTPS, nicht über Folien
Liefern Sie Server-zu-Server-Chat, streamen Sie Tokens in Ihre eigene UI und lösen Sie Automatisierungen über Webhooks aus, die auf Ihrem FlexyAgents-Host enden. Die Routen unten sind die echten Next.js-Handler – kopieren Sie Werte aus Bereitstellung, nachdem Sie eine FlexyAgents-API-Verbindung erstellt haben.
- POST /api/agents/{agentId}/chat akzeptiert Bearer, die an die FlexyAgents-Automatisierungsverbindung gebunden sind, und führt dieselbe RAG- + Modell-Stack wie das Widget aus
- Optionales Streaming liefert NDJSON-Fragmente; ohne Streaming ist die Antwort ein einzelner Assistant-Payload
- Rate Limits pro IP vor Tarifen; gehostete Tarife wenden Token-Budgets an und BYOK liefert explizite Fehler, wenn der Anbieterschlüssel fehlt
- Webhook-Trigger, Kanal-Callbacks und ausgehende Integrationen teilen dasselbe Tenancy-Modell — alles löst sich auf organization_id und agent auf
Zuerst Schlüssel benötigt? Workspace erstellen und öffnen Sie Einstellungen → API-Schlüssel oder das Verbindungsmodal des Agenten.
HTTP-Oberflächen auf einen Blick
Pfade spiegeln den Next.js-Routenbaum. Ersetzen Sie Platzhalter durch Agenten-ID und Host aus Ihrem Bereitstellungsbildschirm.
- POST/api/agents/{agentId}/chat
Agent-Chat & Streaming
Senden Sie einen JSON-Body mit messages-Array (role + content) und optionalem stream-Flag. Bearer validiert gegen den auf der Agent-Verbindung gespeicherten FlexyAgents-API-Schlüssel; bei korrektem Schlüssel löst sich organization_id automatisch auf.
- POST/api/webhooks/automations/...
Automatisierungs-Trigger-Ingress
Veröffentlichte Automatisierungen können Webhook-URLs bereitstellen, die Payloads deserialisieren und executeAutomation aufrufen — nützlich, wenn Ihre Services Flows ohne OAuth starten müssen.
- GET/POST/api/webhooks/*
Kanal- & Anbieter-Webhooks
Schwester-Routen unter /api/webhooks verarbeiten WhatsApp, Instagram, Facebook Messenger, eingehende E-Mail und ähnliche Callbacks, damit omnichannel Deployment auf Ihrer Domain bleibt.
- —Integrations → Webhooks
Ausgehende Zustellung
Konfigurieren Sie signierte ausgehende Webhooks im Dashboard, wenn FlexyAgents Gesprächs- oder Systemereignisse an Ihr SIEM, Data Lake oder Ticketing-Bridge pushen soll.
Minimaler Nicht-Streaming-Aufruf
curl -X POST "https://IHR_APP_HOST/api/agents/AGENT_ID/chat" \
-H "Authorization: Bearer IHR_FLEXYAGENTS_API_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Hallo"}],"stream":false}'Ersetzen Sie die Werte, die Sie kopiert haben aus Bereitstellung → API , nachdem Sie die FlexyAgents-App für diesen Agenten verbunden haben.
Aufrufen
HTTPS-first Chat mit demselben Gehirn wie das Widget
Der Deployment-Screen kopiert einen curl gegen Ihren Live-Host. Der Handler validiert API-Schlüssel gegen den Automatisierungs-Connection-Store, lädt Verhalten + Wissen und inkrementiert Nutzung wie jeder andere Kanal.
messages-Array-Vertrag
Der Body muss mindestens eine Chat-Runde enthalten. Der Executor trimmt Historie auf die letzte User-Nachricht für Retrieval, akzeptiert aber Multi-Turn-Arrays für zukünftige Nutzung.
- Rollen auf user, assistant oder system im Validator begrenzt
- Metadaten nur in Headern, wenn dokumentiert — JSON-Vertrag priorisieren
- Ungültige Formen liefern 400 mit Zod-Detail zum schnelleren Debuggen
Streaming-Modus
Mit stream: true erhalten Sie NDJSON-Fragmente (ein JSON-Objekt pro Zeile), die das Frontend tokenweise rendern kann.
- Ideal für Mobile- oder Desktop-Clients mit gehosteter Widget-Parität
- Fehler mitten im Stream ebenfalls als JSON-Zeilen serialisiert
- Streaming deaktivieren, wenn Proxies Antworten aggressiv puffern
Bearer-API-Schlüssel vs. Session-Cookies
Service-Accounts müssen den pro Agent generierten FlexyAgents-Verbindungsschlüssel nutzen. Interaktive Tests können Dashboard-Session nutzen, Server-zu-Server immer Bearer.
- Schlüssel ruhend verschlüsselt neben anderen Automatisierungs-Credentials
- Schlüssel rotieren ändert nicht die Agent-ID in Ihrer URL
- Ungültige oder fehlende Schlüssel liefern 401 vor Modell-Ausgabe
Limits, die Sie in Produktion sehen
Redis-Limits liefern 429 bei Spitzen. Der Tarif fügt MESSAGE_LIMIT_REACHED für monatliche gehostete/BYOK-Obergrenzen und Token-Caps bei gehosteter Inferenz hinzu.
- Automatisierungen und Chat teilen dieselbe Org-Level-Abrechnung
- Korrelations-IDs aus Fehlern loggen, wenn Sie mit Support sprechen
- Tarif upgraden oder Credits hinzufügen, wo Abrechnung mehr Durchsatz erlaubt
Ereignisse
Bringen Sie Ihren Stack zu FlexyAgents — und pushen Sie Ereignisse zurück
Eingehende Routen normalisieren Anbieter-Signaturen, während ausgehende Config neben anderen Integrationen lebt. Automatisierungen können auch beliebig HTTP POSTen in einem Flow.
Automatisierungs-Webhook-Trigger
Wenn ein Flow einen Webhook-Trigger veröffentlicht, speichert FlexyAgents das Route-Segment und prüft Payloads, bevor executeAutomation mit dem geparsten Body aufgerufen wird.
- Kombinieren mit Agent-Schritten, die Slack, CRMs oder Custom REST aufrufen
- Tarif-Gating kann höhere Stufe vor generischem Ingress verlangen
- Logs erscheinen in derselben Ausführungshistorie wie OAuth-Trigger
Kanal-Anbieter-Callbacks
WhatsApp, Instagram DM, Messenger und eingehende E-Mail registrieren öffentliche HTTPS-Endpoints, damit Meta, Twilio oder Mail Verifizierung und Events liefern.
- Callback-URLs in der Anbieter-Konsole auf Ihren Deployment-Host abstimmen
- Verifizierungs-Handshakes auf denselben Routen wie Live-Traffic
- Sensible Payloads auf Infrastruktur halten, die Sie bereits auditieren
Ausgehende HTTP-Actions
Automatisierungs-Actions können POST oder PUT an Kunden-URLs mit templated Bodies — z. B. „Opsgenie benachrichtigen“ oder „Jira-Ticket erstellen“ ohne First-Party-Connector.
- Trigger-Felder auf JSON-Body im Automatisierungs-Builder mappen
- Retries und Fehler folgen Automatisierungs-Executor-Defaults
- Mit Agent-Schritten kombinieren für lesbare Zusammenfassungen vor Zustellung
Referenz
Specs, Docs und Erkundungstools
Marketing-Seiten sind narrativ; Engineers sollten sich auf /docs, OpenAPI-Definitionen im Repo und Deployment-Snippets stützen, die immer zu Ihren Tenant-IDs passen.
Dokumentations-Hub
Starten Sie auf /docs mit Konzept-Guides und verlinken Sie zu /api für Quickstarts, Auth-Primers und Tab-Referenzen, wo verfügbar.
- curl-, JavaScript- und Widget-Embed-Muster
- SDK/Postman-Versprechen müssen dem entsprechen, was wir tatsächlich ausliefern
- Lücken via Support melden, um Marketing und Tech Writing abzustimmen
OpenAPI als Source of Truth
Das Repo enthält vollständige OpenAPI mit Auth-Schemas, Chat-Payloads und Hilfs-REST-Ressourcen — Clients generieren oder in Postman aus dieser Datei importieren.
- Versionierung folgt Package-Release-Takt, nicht dieser Landing Page
- Staging- und Produktions-Base-URLs in servers des Specs
- Lokal rufen Sie denselben Path /api/agents/{id}/chat wie in Prod auf Ihrem Tenant-Host auf
Widget & Mobile-Begleiter
Nicht jede Experience braucht rohes REST — das Embed-Script ruft denselben Chat-Endpoint mit Besucherkontext auf. API und Widget für Web-Self-Service und Backend-Jobs kombinieren.
- Gehostete Seiten nutzen die Agent-Config, die Sie bereits getestet haben
- CSP und Cookies müssen die konfigurierte Widget-Origin erlauben
- Deep Links aus E-Mail können gehosteten Chat mit Query-Params öffnen
Kombinieren Sie APIs mit Automatisierungen, Kanälen und Governance unter Analytics.
Nächster Schritt
Funktionierenden curl-Befehl kopieren, dann für Produktion härten
Erzeugen Sie den FlexyAgents-Verbindungsschlüssel, hinterlegen Sie ihn in Ihrem Secret Store und richten Sie Automatisierungs-Webhooks auf Ihre eigenen Pfade. Wenn Sie bereit sind, binden Sie Observability in denselben Analytics-Workspace ein, den Ihr Success-Team bereits nutzt.