Chat-API-Referenz

Authentifizierung

Jede Anfrage wird mit dem API-Schlüssel Ihres Workspace authentifiziert, der im X-API-Key-Header (oder als api_key-Parameter) gesendet wird. Schlüssel sehen aus wie ck_live_.... Behandeln Sie den Schlüssel wie ein Passwort - wer ihn besitzt, kann Nachrichten senden, die Ihrem Workspace in Rechnung gestellt werden. Rotieren Sie ihn jederzeit über Einstellungen -> API-Zugriff; der vorherige Schlüssel funktioniert sofort nicht mehr.

Eine Nachricht senden

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

Parameter:

• message (Zeichenkette) - die Besuchernachricht. Erforderlich, sofern keine files angehängt sind.
• ticket_id (Zeichenkette, optional) - eine bestehende Konversation fortsetzen. Weglassen, um eine neue zu beginnen.
• visitor_email / visitor_name (Zeichenkette, optional) - Kontaktdaten an das Ticket anhängen.
• files (multipart, optional) - Anhänge des Besuchers. Erfordert einen Plan mit Datei-Uploads.

Antwort

Der Aufruf gibt 202 Accepted zurück, sobald die Nachricht gespeichert ist; die KI-Antwort wird asynchron generiert.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

Übergeben Sie data.ticket_id beim nächsten Aufruf wieder als ticket_id, um die Konversation fortzusetzen. Um die KI-Antwort zu erhalten, abonnieren Sie über WebSocket (ActionCable) den Kanal, der durch data.id identifiziert wird - denselben Besucher-Hash, den das eingebettete Widget verwendet.

Konversationen lesen

Rufen Sie Tickets und deren Nachrichten mit demselben X-API-Key ab. Jeder Lese-Endpunkt ist auf Ihren Workspace beschränkt und im Business-Plan verfügbar.

• GET /api/v1/chat/tickets - listet Tickets auf, neueste zuerst. Query-Parameter: status, limit (max. 100), offset. Gibt tickets und pagination zurück.
• GET /api/v1/chat/tickets/:id - ein einzelnes Ticket.
• GET /api/v1/chat/tickets/:id/messages - die Nachrichten eines Tickets in Reihenfolge, jede mit role, content und attachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

Ratenbegrenzungen & Kontingent

Anfragen werden auf etwa 20 pro Minute pro Schlüssel (und pro IP) gedrosselt. Jede generierte Antwort zehrt außerdem am monatlichen Nachrichtenkontingent Ihres Plans; sobald dieses aufgebraucht ist, gibt der Endpunkt ein 200 mit data.limit_reached: true zurück, anstatt eine Antwort zu generieren.

Fehler

• 401 - kein API-Schlüssel angegeben.
• 404 - der Schlüssel passt zu keinem Workspace (z. B. nach einer Rotation).
• 403 plan_upgrade_required - der Workspace ist nicht im Business-Plan.
• 403 - das Abonnement ist inaktiv oder die Anfrage kam von einer Domain, die durch die Widget-Einstellungen nicht zugelassen ist.
• 422 - die Nachricht fehlt (und es wurden keine Dateien angehängt).