Chatwoot
de
Sprache
en English pt_BR Portuguese (Brazil) es Spanish de German

Wie richtet man benutzerdefinierte Tools für Captain ein?

Open in
View as Markdown Open in ChatGPT Open in Claude
Sojan

Sojan

Zuletzt aktualisiert am Jul 22, 2026

Custom Tools ermöglichen es Captain, während Gesprächen auf Ihre externen APIs zuzugreifen – so kann er den Garantiestatus prüfen, die Serviceabdeckung verifizieren oder Daten aus Ihren eigenen Diensten abrufen, ohne an einen menschlichen Agenten weiterzuleiten.

Wenn ein Kunde eine Frage stellt, extrahiert Captain die relevanten Werte aus dem Gespräch, fügt sie in Ihre API-Anfrage ein und verwendet die Antwort, um seine Antwort zu formulieren.

Custom Tools sind im Business-Tarif und höher verfügbar.

Tool erstellen

Navigieren Sie zu Captain -> Tools und klicken Sie auf Neues Tool erstellen.
Füllen Sie die folgenden Felder aus:

Tool-Name — Ein kurzer Name wie „Garantieprüfung“ oder „Servicegebietprüfung“ (max. 55 Zeichen).

Beschreibung — Beschreiben Sie Captain, wann dieses Tool zu verwenden ist. Dies ist das wichtigste Feld. Schreiben Sie es, als würden Sie einen Support-Mitarbeiter briefen: „Prüft den Garantiestatus eines Produkts anhand der Seriennummer.“ Unklare Beschreibungen wie „Garantie-API“ führen dazu, dass Captain Möglichkeiten zur Nutzung des Tools verpasst.

Methode — Wählen Sie GET (zum Abrufen von Daten) oder POST (zum Senden von Daten).

Endpunkt-URL — Die URL Ihrer API. Verwenden Sie {{ parameter_name }}, um Werte aus dem Gespräch einzufügen:

https://api.yourcompany.com/v1/warranty/{{ serial_number }}

Die URL muss HTTPS verwenden, muss ein Hostname (kein IP-Adresse) sein und darf nicht auf localhost oder private Netzwerke zeigen.

Authentifizierung — Wählen Sie, wie Ihre API Anfragen authentifiziert:

  • Keine — Keine Authentifizierung

  • Bearer Token — Sendet Ihr Token im Authorization-Header

  • Basic Auth — Sendet einen Benutzernamen und ein Passwort

  • API Key — Sendet einen eigenen Header-Namen und Wert (z. B. X-API-Key)

Authentifizierungsdaten sind nur für Kontoadministratoren sichtbar.


Parameter — Definieren Sie, was Captain aus der Nachricht des Kunden extrahieren soll. Jeder Parameter benötigt einen Namen, Typ und eine Beschreibung. Beispiel: serial_number (String) — „Die Seriennummer des Produkts, auf der Rückseite des Geräts zu finden.“

Request-Template (nur POST) — Eine JSON-Body-Vorlage mit Liquid-Syntax.

Response-Template — Steuert, was Captain aus der API-Antwort sieht. Wenn leer, erhält Captain das rohe JSON.

Mit Liquid können Sie relevante Felder extrahieren, z. B.: Seriennummer {{ response.serial_number }}: {{ response.warranty_status }}. Läuft ab: {{ response.expiry_date }}.

Mit response greifen Sie auf den geparsten JSON-Body zu. Response-Templates helfen Captain, sich auf die relevanten Daten zu konzentrieren und interne Felder wie Datenbank-IDs oder Debug-Informationen zu vermeiden.

Ihr Tool testen

Klicken Sie vor dem Speichern auf Verbindung testen, um zu prüfen, ob Ihr Endpunkt erreichbar ist. Der Test meldet den HTTP-Statuscode.
Ein grünes Ergebnis (HTTP 200–299) bedeutet, dass Verbindung und Authentifizierung funktionieren. Beachten Sie, dass beim Test die URL ohne Parameterwerte gesendet wird; es wird also nur geprüft, ob Ihr Endpunkt erreichbar ist und Ihre Zugangsdaten akzeptiert werden.

Falls der Test fehlschlägt, prüfen Sie Folgendes:

  • 401 Unauthorized — Ihre Zugangsdaten sind falsch. Überprüfen Sie Ihr Bearer Token, den API Key oder Benutzernamen/Passwort.

  • 403 Forbidden — Ihre API lehnt die Anfrage ab. Wenn Identitätsprüfung nötig ist, beachten Sie, dass Testanfragen keine Kontakt-Header enthalten.

  • 404 Not Found — Die Endpunkt-URL ist falsch. Prüfen Sie den Pfad und stellen Sie sicher, dass Ihre API läuft.

  • Timeout — Ihre API hat zu lange für die Antwort gebraucht. Custom Tools haben ein Timeout von 30 Sekunden; stellen Sie sicher, dass Ihr Endpunkt innerhalb dieses Zeitraums antwortet.

Kontext, der mit jedem Tool-Aufruf gesendet wird

Wenn Captain Ihre API aufruft, sendet er Metadaten-Header mit, damit Ihr Backend den Kontext kennt:

  • X-Chatwoot-Account-Id — Ihre Account-ID

  • X-Chatwoot-Conversation-Id — Die Konversations-ID

  • X-Chatwoot-Contact-Email — Die E-Mail-Adresse des Kunden (falls verfügbar)

  • X-Chatwoot-Contact-Inbox-Verified — Ob die Identität des Kunden HMAC-verifiziert ist

  • X-Chatwoot-Assistant-Id — Die ID des Captain-Assistenten, der den Aufruf tätigt

  • X-Chatwoot-Tool-Slug — Der interne Bezeichner des Tools

  • X-Chatwoot-Contact-Id — Die Kontakt-ID des Kunden

  • X-Chatwoot-Contact-Phone — Die Telefonnummer des Kunden (falls verfügbar)

  • X-Chatwoot-Conversation-Display-Id — Die sichtbare Nummer der Konversation

Sie können diese Header nutzen, um den Kunden im eigenen System zu suchen, zu protokollieren, welche Konversationen API-Aufrufe ausgelöst haben, und die Authentizität von Anfragen zu überprüfen.

Sicherheit

Eingebaute Schutzmaßnahmen:

  • Alle Endpunkte müssen HTTPS verwenden

  • Anfragen zu privaten IP-Bereichen, localhost und .local Domains werden blockiert

  • HTTP-Weiterleitungen werden nicht verfolgt

  • Antworten sind auf 1 MB begrenzt

  • Zugangsdaten sind nur für Administratoren sichtbar

Identitätsprüfung: Wenn Ihr Tool kundenbezogene Daten zurückgibt (Bestellungen, Rechnungen, Kontoinformationen), sollte Ihre API den Header X-Chatwoot-Contact-Inbox-Verified überprüfen. Ohne aktivierte HMAC-Prüfung im Postfach könnte ein Besucher im Chat-Widget jede beliebige E-Mail-Adresse setzen. Geben Sie sensible Daten nur zurück, wenn dieser Header true ist. Bei Tools, die nur öffentliche Daten liefern, ist diese Prüfung nicht erforderlich.

Prompt Injection: Gibt Ihre API nutzergenerierte Inhalte zurück (Bewertungen, Forenbeiträge), könnte bösartiger Text Captains Verhalten beeinflussen. Verwenden Sie Response-Templates, um nur strukturierte Felder zu extrahieren, und bereinigen Sie Inhalte API-seitig.

Limits

  • Max. Tools pro Account — 15

  • Empfohlen — 10 oder weniger. Über 10 erscheint ein Warnhinweis; mehr Tools erschweren es Captain, das richtige auszuwählen.

  • Tool-Name Länge — 55 Zeichen

  • Antwortgröße — Maximal 1 MB

  • Request-Timeout — 30 Sekunden

Wann eignen sich Custom Tools?

Custom Tools eignen sich am besten für strukturierte Abfragen mit vorhersehbaren Eingaben — Systemstatus prüfen, Zeitpläne abfragen oder Datensätze anhand von IDs suchen. Wenn es für Ihren Anwendungsfall bereits eine eigene Chatwoot-Integration gibt (z. B. Shopify für E-Commerce), nutzen Sie diese – spezialisierte Integrationen unterstützen Suche, Fuzzy Matching und Datensynchronisation zuverlässiger als ein einzelner API-Aufruf.

Beispiele

Garantieprüfung

Wenn ein Kunde fragt, ob sein Produkt noch Garantie hat, kann Captain dies anhand der Seriennummer prüfen.

  • Tool-Name: Garantieprüfung

  • Beschreibung: Prüft den Garantiestatus eines Produkts anhand seiner Seriennummer. Wird verwendet, wenn ein Kunde wissen will, ob sein Produkt abgedeckt ist, wann die Garantie abläuft oder welche Art von Abdeckung besteht.

Servicegebietprüfung

Für Firmen, die nur in bestimmten Regionen tätig sind – Kunden fragen, ob Service an ihrem Standort verfügbar ist.

  • Tool-Name: Servicegebietprüfung

  • Beschreibung: Prüft, ob Service oder Lieferung in einem bestimmten Gebiet anhand der Postleitzahl oder des Stadtnamens des Kunden verfügbar ist.

Custom Tools funktionieren am besten, wenn die Eingaben eindeutig und die API-Antwort vorhersehbar ist – Statusprüfungen, Nachschlagen von Daten und andere strukturierte Abfragen sind dafür ideal geeignet.