Bot Chat API

Die Bot Chat API ermöglicht dir, Bot-Antworten programmatisch abzurufen — ohne Dashboard, ohne WhatsApp. Typische Anwendungsfaelle sind n8n-Workflows, E-Mail-Processing oder eigene Integrationen.

Endpoint

POST /api/bot-chat/:botId/chat

Mount-Pfad in server.js:

app.use('/api/bot-chat', require('./routes/botChatRoutes'));

Authentifizierung

Alle Requests werden über die apiKeyAuth-Middleware authentifiziert. Du brauchst einen Tenant API Key (Prefix via_), der in der Tabelle tenant_api_keys als bcrypt-Hash gespeichert ist.

Der Key kann auf zwei Arten übergeben werden:

Methode	Header
Bearer Token	Authorization: Bearer via_XXXXXXXX_...
Custom Header	x-api-key: via_XXXXXXXX_...

Die Middleware prueft:

1. Key-Prefix (erste 12 Zeichen) gegen tenant_api_keys.key_prefix
2. bcrypt-Vergleich gegen key_hash
3. is_active = true
4. expires_at nicht abgelaufen

Bei Erfolg wird req.tenantId und req.apiKeyId gesetzt.

Rate Limiting

Parameter	Wert
Fenster	60 Sekunden
Max. Requests	60 pro Fenster
Key	apiKeyId (Fallback: IP)
Standard-Headers	RateLimit-* (RFC Draft)
Legacy-Headers	deaktiviert

Bei Überschreitung erhaeltst du:

{
  "error": "Rate-Limit erreicht",
  "message": "Maximale Anzahl von 60 Anfragen pro Minute erreicht. Bitte warte kurz."
}

Request

URL-Parameter

Parameter	Typ	Pflicht	Beschreibung
botId	UUID	Ja	ID des Bots (muss zum Tenant des API Keys gehoeren)

Body (JSON)

Feld	Typ	Pflicht	Beschreibung
message	string	Ja	Die Nachricht an den Bot (max. 10.000 Zeichen)
sender_id	string	Nein	Absender-Kennung, z.B. E-Mail-Adresse (max. 255 Zeichen)
channel	string	Nein	Kanal-Typ (Default: "api")
conversation_id	UUID	Nein	Bestehende Conversation fortsetzen
metadata	object	Nein	Zusaetzliche Metadaten (z.B. { "subject": "Anfrage" })

Gültige Channels

const VALID_CHANNELS = ['email', 'api', 'webhook'];

Wenn ein ungültiger Channel übergeben wird, faellt der Wert auf "api" zurück.

Response

Erfolg (200)

{
  "reply": "Unsere Oeffnungszeiten sind...",
  "conversation_id": "uuid",
  "tokens_used": 123,
  "model": "mistral-medium-latest",
  "knowledge_used": true,
  "quota_remaining": 897,
  "channel": "email"
}

Feld	Typ	Beschreibung
reply	string	Die Bot-Antwort
conversation_id	UUID	ID der Conversation (für Folge-Nachrichten)
tokens_used	number	Verbrauchte Tokens für diesen Request
model	string	Verwendetes AI-Modell
knowledge_used	boolean	Ob Knowledge-Base-Eintraege in die Antwort eingeflossen sind
quota_remaining	number | null	Verbleibende Nachrichten im monatlichen Kontingent
channel	string	Der verwendete Kanal

Fehler-Codes

HTTP	error	Ursache
400	Nachricht erforderlich	message fehlt, ist leer oder kein String
400	Nachricht zu lang	message hat mehr als 10.000 Zeichen
400	Ungültige sender_id	sender_id ist kein String oder laenger als 255 Zeichen
401	API Key erforderlich	Kein API Key im Header
401	Ungültiger API Key	Key nicht gefunden oder Validierung fehlgeschlagen
401	API Key abgelaufen	expires_at überschritten
403	Bot deaktiviert	Bot ist nicht aktiv (is_active = false oder status = 'disabled')
404	Bot nicht gefunden	Bot existiert nicht oder gehoert nicht zum Tenant
404	Conversation nicht gefunden	conversation_id existiert nicht für diesen Bot/Tenant
429	Nachrichtenlimit erreicht	Monatliches Message-Kontingent aufgebraucht
429	Rate-Limit erreicht	Mehr als 60 Requests/Minute
500	Interner Fehler	Unerwarteter Server-Fehler

Conversation History

Der Endpoint laedt automatisch die letzten 10 Nachrichten der Conversation als Kontext für die AI. Du kannst eine bestehende Conversation fortsetzen, indem du die conversation_id aus der ersten Response in Folge-Requests mitschickst.

Knowledge Base

Die Knowledge Base wird automatisch durchsucht (Top 3 Ergebnisse). Nur Ergebnisse mit einem Score >= QDRANT_MIN_SCORE (Default: 0.4) fliessen in den Kontext ein. Die Strictness-Stufe des Bots (bot.knowledge_strictness) steuert, wie streng die AI an die KB-Ergebnisse gebunden ist.

Beispiel

curl -X POST https://api.getvia.at/api/bot-chat/BOT_UUID/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer via_XXXXXXXX_dein_api_key" \
  -d '{
    "message": "Wie sind eure Oeffnungszeiten?",
    "sender_id": "kunde@example.com",
    "channel": "email",
    "metadata": { "subject": "Anfrage Oeffnungszeiten" }
  }'

Folge-Nachricht (gleiche Conversation)

curl -X POST https://api.getvia.at/api/bot-chat/BOT_UUID/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer via_XXXXXXXX_dein_api_key" \
  -d '{
    "message": "Und am Wochenende?",
    "conversation_id": "CONVERSATION_UUID_AUS_ERSTER_RESPONSE",
    "channel": "email"
  }'

Dateien

Datei	Beschreibung
src/routes/botChatRoutes.js	Route-Definition + Rate Limiter
src/controllers/botChatController.js	Controller-Logik
src/middleware/apiKeyAuth.js	API Key Authentifizierung