Richte benutzerdefinierte Werkzeuge für Captain ein

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 prüfen, anstatt weiterzuleiten.

Plan & Zugriff: Business oder Enterprise (Preise & Pläne). Im Startups-Tarif zeigt Tools meist Upgrade, um Tools mit Captain zu nutzen. 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 starten

• 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 1 MB oder weniger.

• Dessen 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:

   • Tool-Name: kurz, zum Beispiel „Bestellung suchen“ (55 Zeichen oder weniger).

   • Beschreibung: wann der Assistent es verwenden soll, geschrieben wie eine Einweisung für einen neuen Agenten. Das entscheidet, ob der Assistent das Tool auswählt.

   • Methode: GET zum Auslesen von Daten; POST, PUT oder PATCH zum Senden oder Ändern von Daten; DELETE zum Entfernen.

   • Endpunkt-URL: verwenden Sie {{ parameter_name }} für Werte, die der Assistent einfügt, zum Beispiel https://api.example.com/orders/``{{ order_id }}.

   • Authentifizierungstyp: Keine, Bearer Token, Basic Auth oder API-Schlüssel (mit Header-Name und Header-Wert). Dies wird für Zugangsdaten genutzt.

   • 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 Mandanten-ID (bis zu 16). Werte werden genau wie eingegeben gesendet. Chatwoot setzt Authorization, Host, Content-Length, Content-Type und jeden Header, der mit X-Chatwoot beginnt, selbst — diese können daher nicht hinzugefügt werden.

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

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

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

     

   

3. Klicken Sie auf Verbindung testen, dann Erstellen.

   

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

Testen Sie es

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

Mehrwert

• Benutzerdefinierte Tools eignen sich am besten für Abfragen mit klaren Eingaben, etwa einen Bestellstatus, eine Buchung oder einen Datensatz nach ID.

• Jeder Assistent kann bis zu 50 Tools haben. Halten Sie die Liste dennoch kurz: Bei vielen Tools nimmt der Assistent mit größerer Wahrscheinlichkeit das falsche.

• Hinzufügen, Bearbeiten, Deaktivieren oder Löschen eines Tools wirkt sich nur auf den aktuellen Assistenten aus. Tools, die vor der Umstellung auf Assistenten-spezifische Tools existierten, wurden für alle kopiert – prüfen Sie daher jeden einzelnen.

• Betreiben Sie mehrere Assistenten? Geben Sie jedem nur die Tools, die er braucht.

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

• Chatwoot sendet mit jedem Aufruf Header, sodass Ihr System Konto, Konversation, Kontakt-E-Mail und -Telefonnummer, Assistent und ob der Kontakt verifiziert ist, kennt. Für private Daten prüfen Sie den Header X-Chatwoot-Contact-Inbox-Verified, bevor Sie antworten. Ohne Identitätsvalidierung kann ein Besucher jede beliebige E-Mail im Widget eingeben. Tools, die ausschließlich öffentliche Daten liefern, benötigen diese Überprüfung nicht. Siehe Wie aktiviere ich Identitätsvalidierung in Chatwoot?.

• Gibt Ihre API Texte zurück, die von Kunden geschrieben wurden, geben Sie nur die strukturierten Felder zurück, die Sie brauchen. Captain liest die Antwort wie sie ist, daher kann Freitext Anweisungen enthalten, denen er eventuell folgt.

Fehlerbehebung

Weitere Ursachen: Captain Fehlerbehebung.