Chat-API

Die Chat-API ist der Hono.js-Backend-Service, der den fiskaly Workspace-Assistenten betreibt. Sie bietet Server-Sent Events (SSE)-Streaming, RAG-Kontextabruf mit Vertex AI und eine robuste Sicherheitsschicht für öffentlichen Chat und Admin-Dashboards.

Kernfunktionen

• Streaming-Antworten — Server-Sent Events (SSE) liefern Zeichen mit geringer Latenz und strukturierte Metadaten.
• RAG-Verankerung — Kontext wird aus 5 integrierten Quellen abgerufen (Docs MDX, OpenAPI, Zendesk KB, Web und PDFs).
• Zwei Modelle — Anfragen werden intelligent zwischen Gemini 2.5 Pro (komplexe Anfragen) und Gemini 2.0 Flash (einfache Anfragen/Begrüßungen) geroutet.
• Persona-System — Passen Sie Antworten für Entwickler, Produktmanager oder Einzelhandels-Operatoren mit unterschiedlichem Fallback-Verhalten an.

API-Integration

Um die Chat-API zu nutzen, erstellen Sie in der Regel eine anonyme Sitzung und öffnen dann eine EventSource-Verbindung zum /api/chat-Streaming-Endpunkt.

1. Sitzung erstellen

POST /api/session

Gibt ein JWT-Sitzungstoken zurück, das für Rate-Limiting und Kontinuität benötigt wird.

2. Konversation streamen

POST /api/chat
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "message": "How do I create a TSS in SIGN DE?",
  "persona": "developer",
  "history": []
}

Die Antwort ist ein SSE-Stream, der JSON-Payloads mit dem data:-Präfix ausgibt. Der Stream enthält sowohl Textabschnitte als auch Metadaten (z. B. abgerufene Zitate oder den finalen Qualitätswert).

💡React im Einsatz?

Wenn Sie eine React-Anwendung entwickeln, stellen wir eine vollständige Drop-in-UI-Bibliothek zur Verfügung. Lesen Sie stattdessen die Dokumentation zu den Chat-UI-Komponenten, anstatt den SSE-Client von Grund auf zu erstellen.

Sicherheit und Limits

Die Chat-API enthält strikte Schutzmaßnahmen für den Produktionseinsatz:

• Rate-Limiting — 5 Nachrichten pro Minute, 30 pro Stunde und Sitzung.
• Eingabefilterung — Jailbreak-Erkennung und Längenvalidierung (max. 3000 Zeichen pro Nachricht).
• Ausgabefilterung — PII-Scanning und Verifizierbarkeitsprüfung.
• Budget-Schutz — Ein konfigurierbares tägliches Ausgabelimit für den gesamten Mandanten verhindert unerwartete LLM-Kosten.

Inhalts-Neuindizierung

Die RAG-Wissensdatenbank wird täglich um 3:00 Uhr UTC automatisch über einen Kubernetes-CronJob neu indiziert. Dies stellt sicher, dass neue oder aktualisierte Dokumentationen, Zendesk-Artikel und API-Spezifikationen innerhalb von 24 Stunden in Chat-Antworten einfließen.

Admin-Dashboard

Der chat-api-Service hostet auch ein internes React-SPA unter /admin/*, das durch Google OAuth gesichert ist. Das Dashboard bietet:

• Überprüfung und Qualitätsbewertung von Konversationen.
• Verbesserungs-Action-Items (Todos) für Inhalte.
• LLM-Prompt-Überschreibungen basierend auf Schlüsselwort-Triggern.
• Nutzungs-, Kosten- und Budget-Analysen.

Nächste Schritte

Chat-UI-Komponenten

Drop-in-React-Komponenten für das fiskaly-Chat-Widget und die Vollseiten-Erfahrung.

Backend-Quellcode

Quellcode der zugrunde liegenden API einschließlich Hono-Routen und der RAG-Pipeline anzeigen.