Schnittstelle: Integration

Die Integrationsschnittstelle verbindet Ihre eigenen Systeme mit XICBOT. Mit einem API-Schlüssel lesen Sie Gespräche, Anfragen, Termine und Kennzahlen, legen Anfragen und Wissensquellen an und stellen einem Assistenten Fragen, deren Antwort als Ereignisstrom zurückkommt. Jeder Weg liegt unter /api/v1/integration/ und prüft den Bereich des Schlüssels für sich.

Überblick

Die Schnittstelle erreichen Sie unter https://app.xicbot.de/api/v1/integration/. Jede Anfrage trägt den Schlüssel im Kopf X-Api-Key; ein Schlüssel beginnt mit xbot_. Wie Sie einen Schlüssel anlegen, seine Bereiche wählen und ihn ablaufen lassen, steht unter Schlüssel und Webhooks, das Anmeldeverfahren unter Anmeldung. Die Integrationswege liegen außerhalb der Sitzungsanmeldung der App: ein Sitzungstoken öffnet sie nicht.

Schreiben ist ein eigener Bereich: ein Schlüssel mit leads liest Anfragen, legt aber keine an. In der App steht dazu unter Bereiche der Satz *Schreiben ist ein eigener Bereich. Ohne ihn liest ein Schlüssel nur.*

Fehler, die jeder Weg kennt

Bevor ein Weg seine eigentliche Arbeit beginnt, prüft die Schnittstelle Schlüssel, Konto, Paket, Drossel und Bereich. Fehler kommen als JSON mit dem Feld error.

Drosselung

Jeder Schlüssel hat einen Minutendeckel, den Sie beim Anlegen unter Anfragen pro Minute eintragen, und einen Tagesdeckel aus den Einstellungen Ihres Kontos; beide zählen je Schlüssel. Ist einer erreicht, antwortet der Weg mit 429 und too_many_requests. Werte, Zeitfenster und die Felder der Antwort stehen unter Paketsperren und Drosseln.

Seitenweise lesen

Die Listen für Gespräche, Anfragen und Termine liefern 50 Einträge je Seite. Gespräche und Anfragen stehen nach Anlage geordnet, die jüngsten zuerst; Termine nach Beginn, die spätesten zuerst. Die Seite wählen Sie mit page, gezählt ab 1; ein fehlender oder kleinerer Wert gilt als 1, ein Wert, der keine ganze Zahl ist, wird mit 422 abgewiesen. Die Antwort wiederholt die Seite im Feld page und nennt keine Gesamtzahl. Lesen Sie weiter, bis eine Seite weniger als 50 Einträge hat.

Status

curl -s https://app.xicbot.de/api/v1/integration/status \
  -H "X-Api-Key: $XICBOT_KEY"

# {"alive":true,"tenant":"…","scopes":["leads","leads.write"],"limit_per_min":120}

Gespräche

Anfragen

Anfragen sind Kontaktwünsche. Sie entstehen im Gespräch mit einem Assistenten oder über diese Schnittstelle. Legt ein Assistent eine Anfrage über ein Werkzeug an, löst das ebenfalls den Webhook lead.created aus, mit anderer Nutzlast als hier, siehe Ausgelöste Webhooks. In der App bearbeiten Sie Anfragen unter Termine und Vorgänge.

Termine

Kennzahlen

Das Fenster schließt den laufenden Tag ein und endet an der nächsten Mitternacht der angegebenen Zone: 7d umfasst heute und die sechs Tage davor.

Wissensquellen anlegen

Ob ein Website-Abruf gelungen ist, melden die Webhooks knowledge.indexed und knowledge.failed. Im Fehlerfall nennt reason einen benannten Grund, etwa no_text_extracted, url_unreachable, website_too_large oder redirect_off_origin; andere Ursachen erscheinen als ingest_failed. Der Abruf bekommt bis zu drei Versuche, und jeder gescheiterte Versuch meldet knowledge.failed. Für dieselbe source_id können darum mehrere Ereignisse eintreffen, auch ein knowledge.indexed nach einem knowledge.failed; maßgeblich ist das jüngste.

Chat

Das Kontingent erklärt Pakete und Kontingente. Ein Gespräch führt höchstens eine Antwort gleichzeitig; bricht ein Lauf ab, ist das Gespräch nach 180 Sekunden wieder frei. Auch ein Gespräch, das in der App als erledigt markiert ist, lässt sich fortsetzen, und die Frage öffnet es wieder: war es übergeben (escalated_at gesetzt), wird es escalated mit neuem escalated_at und liegt wieder im Postfach, sonst wird es open; resolved_at wird leer. Ein Ereignis geht dabei nicht hinaus, und eine abgewiesene Frage öffnet nichts. Als Herkunft eines neuen Gesprächs gilt der Host aus dem Kopf Origin oder Referer, falls Ihr Aufruf einen davon sendet; sonst bleibt sie leer.

Ereignisstrom

Die Antwort hat den Typ text/event-stream; charset=utf-8 und wird ohne Zwischenspeicher ausgeliefert (Cache-Control: no-cache, no-store). Jedes Ereignis besteht aus einer Zeile event: mit der Art und einer Zeile data: mit einem JSON-Objekt, gefolgt von einer Leerzeile. Die Kennung eines neuen Gesprächs steht im ersten Ereignis start; merken Sie sie sich für Folgefragen.

curl -N https://app.xicbot.de/api/v1/integration/chat \
  -H "X-Api-Key: $XICBOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assistant_id": "…", "text": "Welche Öffnungszeiten gelten?"}'

event: start
data: {"conversation_id":"…","question_id":null}

event: text
data: {"t":"Wir sind montags bis freitags "}

event: text
data: {"t":"für Sie da."}

event: end
data: {"state":"done","message_id":"…",…}

Ausgelöste Webhooks

Die Wege dieser Schnittstelle lösen die folgenden Webhooks aus, sofern Sie für das Ereignis einen Empfänger eingerichtet haben, siehe Schlüssel und Webhooks. Die Ereignisse mit allen Auslösern, auch denen außerhalb der Integration, listet Ereignisse.

Häufige Fragen