Benutzerdefinierte Werkzeuge für Captain einrichten

Entdecken

Mit benutzerdefinierten Tools kann der Assistent während eines Gesprächs auf Ihre eigenen Systeme zugreifen, zum Beispiel um eine Bestellung, eine Garantie oder eine Buchung zu überprüfen, anstatt weiterzuleiten.

Plan & Zugang: Business oder Enterprise (Preise & Pläne). Bei Startups erscheint bei Tools normalerweise Upgrade, um Tools mit Captain zu verwenden. Jeder Assistent hat seine eigene Liste von Tools. Administratoren erstellen Tools und nur Administratoren können die gespeicherten Zugangsdaten sehen. Selbst-gehostet: Der Super-Admin aktiviert Benutzerdefinierte Tools für das Konto.

Einrichten & Ausprobieren

Bevor Sie loslegen

• Ein HTTPS-Endpunkt auf einem öffentlichen Hostnamen. Chatwoot blockiert einfaches HTTP, IP-Adressen, localhost, private Netzwerke und .local-Adressen.

• Der Endpunkt muss die Verbindung innerhalb von 2 Sekunden annehmen und innerhalb von 20 Sekunden antworten, mit einer Antwort von maximal 1 MB.

• Die Zugangsdaten, falls benötigt.

Ein Tool erstellen

1. Gehen Sie zu Captain > Tools und klicken Sie auf Neues Tool erstellen. Verwenden Sie zuerst den Assistenten-Umschalter oben, um den Assistenten auszuwählen, für den das Tool gedacht ist. Das Formular öffnet sich in einem Seitenpanel.

   

2. Füllen Sie aus:

   • Toolname: kurz, zum Beispiel "Bestellung suchen" (55 Zeichen oder weniger).

   • Beschreibung: wann der Assistent es nutzen soll, formuliert wie eine Einweisung für einen neuen Mitarbeitenden. Dadurch entscheidet der Assistent, ob er das Tool auswählt.

   • Methode: GET, um Daten zu lesen; POST, PUT oder PATCH, um Daten zu senden oder zu ändern; DELETE, um etwas zu entfernen.

   • Endpunkt-URL: verwenden Sie {{ parameter_name }} für Werte, die der Assistent ausfüllt, z. B. https://api.example.com/orders/``{{ order_id }}.

   • Authentifizierungstyp: Keine, Bearer Token, Basic Auth oder API-Schlüssel (mit Header Name und Header Value). Nutzen Sie dies für Zugangsdaten.

   • Header: Klicken Sie auf Header hinzufügen für feste Header, die Ihre API bei jedem Aufruf benötigt, wie z.B. eine API-Version oder eine Mandanten-ID (bis zu 16). Werte werden exakt wie eingegeben gesendet. Chatwoot setzt Authorization, Host, Content-Length, Content-Type und alle Header, die mit X-Chatwoot beginnen, selbst – diese können Sie daher nicht hinzufügen.

   • Parameter: Klicken Sie auf Parameter hinzufügen für jeden Wert, den der Assistent vom Kunden erhalten soll. Geben Sie einen Namen, Typ, Beschreibung an und markieren Sie Erforderlich, falls nötig.

   • Vorlage für Anfragekörper (optional): Für POST, PUT oder PATCH. Diese und die Antwortvorlage finden Sie unter Vorlagen. Die Anfragevorlage ist ein JSON-Body. Sie unterstützt Liquid, z. B. {{ order_id }} für einen Parameter.

   • Antwortvorlage (optional): Wählen Sie die Felder aus, die der Assistent benötigt, z. B. Bestellung {{ response.order_id }} Status: {{ response.status }}. Lesen Sie die API-Antwort über response, z. B. {{ response.status }}. Lassen Sie die Vorlage leer, um Captain das rohe JSON zu senden.

     

   

3. Klicken Sie auf Verbindung testen, dann auf Erstellen.

   

Verbindung testen funktioniert nur für Endpunkte ohne Vorlagen oder Anfragekörper. Für andere testen Sie im Playground. Ein grünes Ergebnis bedeutet, Ihr Endpunkt hat einen 2xx-Status zurückgegeben: Er ist erreichbar und akzeptiert die Zugangsdaten.

Testen

Stellen Sie im Playground eine Frage, die das Tool benötigt, z. B. „Wo ist Bestellung 1234?“. Prüfen Sie, ob die Antwort echte Daten nutzt.

Wert erhalten

• Benutzerdefinierte Tools funktionieren am besten für Abfragen mit klaren Eingaben, wie ein Bestellstatus, eine Buchung oder ein Datensatz nach ID.

• Jeder Assistent kann bis zu 50 Tools haben. Halten Sie die Liste trotzdem kurz: Bei vielen Tools wählt der Assistent eher das falsche aus.

• Das Hinzufügen, Bearbeiten, Deaktivieren oder Löschen eines Tools ändert es nur für den Assistenten, den Sie gerade ansehen. Tools, die vor der Umstellung pro Assistent existierten, wurden zu jedem Assistenten kopiert – prüfen Sie jeden einzelnen.

• Verwenden Sie mehrere Assistenten? Geben Sie jedem nur die Tools, die er benötigt.

• Deaktivieren Sie ein Tool mit dem Schalter, statt es zu löschen. Wenn ein Szenario es verwendet, warnt Chatwoot Sie zuerst. Siehe Captain's Guardrails, Richtlinien und Szenarien festlegen.

• Chatwoot sendet bei jedem Aufruf Header, damit Ihr System weiß, welches Konto, welche Unterhaltung, E-Mail und Telefonnummer des Kontakts, Assistent und ob der Kontakt verifiziert ist. Bei privaten Daten prüfen Sie den Header X-Chatwoot-Contact-Inbox-Verified, bevor Sie antworten. Ohne Identitätsprüfung kann ein Besucher beliebige E-Mails ins Widget eingeben. Tools, die nur öffentliche Daten liefern, brauchen diese Prüfung nicht. Siehe Wie Identitätsprüfung in Chatwoot aktivieren?.

• Gibt Ihre API Texte zurück, die von Kunden geschrieben wurden, geben Sie nur die strukturierten Felder zurück, die Sie benötigen. Captain liest die Antwort eins zu eins – Freitext kann Anweisungen enthalten, denen er folgt.

Fehlerbehebung

Weitere Ursachen: Fehlerbehebung Captain.