Server Setup

Der Evolo Chat-Server bietet drei Haupt-API-Endpunkte, die zusammenarbeiten, um KI-gestützte Unterhaltungen mit Wissensbasis-Integration zu ermöglichen. Diese Anleitung bietet einen detaillierten Überblick über jeden Endpunkt und deren Implementierung.

API-Überblick

Der Chat-Server besteht aus drei Kern-Endpunkten:

• Session-Endpunkt (POST /chat/session) - Initialisiert Chat-Sessions und verwaltet Authentifizierung
• Zustimmungs-Endpunkt (PUT /chat/session/consent) - Verwaltet DSGVO-Tracking-Zustimmung
• Chat-Endpunkt (POST /chat) - Verarbeitet KI-Unterhaltungen mit Wissensbasis-Kontext

Session-Management-Endpunkt

POST /chat/session

Initialisiert eine neue Chat-Session oder ruft eine bestehende Session mit Tracking-Zustimmungsstatus ab.

Anfrage:

• Methode: POST
• URL: /chat/session
• Headers: Content-Type: application/json
• Authentifizierung: Optional (erstellt neue Session, falls keine existiert)

Antwort:

{
  "id": "session_123abc",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z", 
  "expiresAt": "2024-01-16T10:30:00.000Z",
  "trackingConsent": "PENDING" | "GRANTED" | "DENIED"
}

Antwort-Felder:

• id: Eindeutige Session-Kennung
• createdAt: Session-Erstellungszeitstempel
• updatedAt: Zeitstempel der letzten Session-Aktualisierung
• expiresAt: Session-Ablaufzeitstempel
• trackingConsent: Aktueller DSGVO-Zustimmungsstatus
  • PENDING: Benutzer hat noch keine Wahl getroffen
  • GRANTED: Benutzer hat Tracking-Cookies akzeptiert
  • DENIED: Benutzer hat Tracking-Cookies abgelehnt

Implementierungshinweise:

• Erstellt automatisch eine neue Session mit Standard-Chat-Anmeldedaten, falls keine existiert
• Gibt neue Session-Cookies in den Antwort-Headern zurück
• Sessions laufen standardmäßig nach 24 Stunden ab

Zustimmungs-Management-Endpunkt

PUT /chat/session/consent

Aktualisiert die Tracking-Zustimmungseinstellung des Benutzers für DSGVO-Konformität.

Anfrage:

• Methode: PUT
• URL: /chat/session/consent
• Headers: Content-Type: application/json
• Authentifizierung: Erforderlich (Session-Token)
• Body:

{
  "trackingConsent": "GRANTED" | "DENIED"
}

Antwort:

{
  "id": "session_123abc",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z",
  "expiresAt": "2024-01-16T10:30:00.000Z", 
  "trackingConsent": "GRANTED"
}

Fehlerantworten:

• 400 Bad Request: Fehlende oder ungültige Tracking-Zustimmungswert
• 401 Unauthorized: Ungültige oder abgelaufene Session
• 500 Internal Server Error: Fehler beim Aktualisieren der Zustimmung

KI-Chat-Verarbeitungsendpunkt

POST /chat

Verarbeitet KI-Unterhaltungen mit automatischer Wissensbasis-Kontexteinbettung und Streaming-Antworten.

Anfrage:

• Methode: POST
• URL: /chat
• Headers: Content-Type: application/json
• Authentifizierung: Erforderlich (Bearer-Token oder Session-Cookie)
• Berechtigungen: Benötigt chat:send-Berechtigung
• Body:

{
  "messages": [
    {
      "role": "user",
      "parts": [
        {
          "type": "text", 
          "text": "How do I configure the chatbot?"
        }
      ]
    }
  ]
}

Anfrage-Schema:

• messages: Array von Unterhaltungsnachrichten
  • role: Entweder "user" oder "assistant"
  • parts: Array von Nachrichtenteilen (unterstützt derzeit nur Text)
    • type: Nachrichtenteil-Typ ("text")
    • text: Der Nachrichteninhalt

Antwort:

• Content-Type: text/event-stream
• Format: Server-Sent Events (SSE) streaming
• Encoding: UTF-8 text chunks

Antwort-Headers:

• Content-Type: text/event-stream
• Cache-Control: no-cache
• Connection: keep-alive

Verarbeitungsablauf:

<user-message>
  {original_user_message}
</user-message>

<knowledgebase-context>
  {relevant_knowledge_base_content}
</knowledgebase-context>

Fehlerantworten:

• 400 Bad Request: Ungültiges Nachrichtenformat oder leeres Nachrichten-Array
• 401 Unauthorized: Fehlende oder ungültige Authentifizierung
• 403 Forbidden: Unzureichende Berechtigungen (fehlt chat:send)
• 500 Internal Server Error: KI-Verarbeitungs- oder Streaming-Fehler