Richte benutzerdefinierte Tools für Captain ein.

Entdecken

Mit benutzerdefinierten Tools kann der Assistent während eines Gesprächs auf Ihre eigenen Systeme zugreifen, beispielsweise um eine Bestellung, eine Garantie oder eine Buchung zu prüfen, anstatt das Gespräch weiterzugeben.

Plan und Zugriff: Business oder Enterprise (Preise und Pläne). Bei Startups wird unter Tools normalerweise Upgrade to use tools with Captain angezeigt. Jeder Assistent hat eine eigene Tool-Liste. Administratoren erstellen Tools, und nur Administratoren können die gespeicherten Anmeldedaten einsehen. Bei selbst gehosteten Installationen aktiviert der Super Admin Custom Tools für das Konto.

Einrichten und ausprobieren

Bevor Sie beginnen

• Ein HTTPS-Endpunkt unter 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. Die Antwort darf höchstens 1 MB groß sein.

• Die Anmeldedaten, falls erforderlich.

Ein Tool erstellen

1. Gehen Sie zu Captain > Tools und klicken Sie auf Create a new tool. Wählen Sie zuerst über den Assistenten-Umschalter oben den Assistenten aus, für den das Tool bestimmt ist. Das Formular wird in einem Seitenbereich geöffnet.

   

2. Füllen Sie die Felder aus:

   • Tool Name: eine kurze Bezeichnung, zum Beispiel „Bestellabfrage“ (höchstens 55 Zeichen).

   • Description: Beschreiben Sie, wann der Assistent das Tool verwenden soll, als würden Sie einen neuen Agenten einweisen. Diese Beschreibung entscheidet, ob der Assistent das Tool auswählt.

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

   • Endpoint URL: Verwenden Sie {{ parameter_name }} für Werte, die der Assistent einsetzt, zum Beispiel https://api.example.com/orders/``{{ order_id }}.

   • Authentication Type: None, Bearer Token, Basic Auth oder API Key (mit Header Name und Header Value). Verwenden Sie dies für Anmeldedaten.

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

   • Parameters: Klicken Sie für jeden Wert, den der Assistent beim Kunden erfragen soll, auf Add Parameter. Geben Sie einen Namen, Typ und eine Beschreibung an und markieren Sie bei Bedarf Required.

   • Add verified email: Fügt einen Parameter hinzu. Chatwoot trägt in diesen Parameter die E-Mail-Adresse ein, die der Kunde mit einem Einmalcode bestätigt hat. In Kundengesprächen kann Captain sie weder sehen noch ändern. Verwenden Sie diesen Parameter, wenn Ihre API den Kunden anhand der E-Mail-Adresse sucht, zum Beispiel https://api.example.com/orders?email={{ email }}. Ein Tool kann einen Parameter für eine bestätigte E-Mail-Adresse haben.

   • Require email verification: Captain kann das Tool erst verwenden, nachdem der Kunde seine E-Mail-Adresse mit einem Einmalcode bestätigt hat. Wenn das Tool einen Parameter für eine bestätigte E-Mail-Adresse hat, ist diese Einstellung immer aktiviert.

   • Request Body Template (Optional): Für POST, PUT oder PATCH. Diese Vorlage und die Antwortvorlage befinden sich unter Templates. Die Anfragevorlage ist ein JSON-Body. Sie unterstützt Liquid, zum Beispiel {{ order_id }} für einen Parameter.

   • Response Template (Optional): Wählen Sie die Felder aus, die der Assistent benötigt, zum Beispiel Bestellung {{ response.order_id }} Status: {{ response.status }}. Greifen Sie über response auf die API-Antwort zu, zum Beispiel {{ response.status }}. Lassen Sie die Vorlage leer, um Captain das rohe JSON zu senden.

     

   

3. Klicken Sie auf Test connection und anschließend auf Create.

   

Test connection funktioniert nur bei Endpunkten ohne Vorlagen oder Request-Body. Testen Sie andere Endpunkte im Playground. Ein grünes Ergebnis bedeutet, dass Ihr Endpunkt einen 2xx-Status zurückgegeben hat: Er ist erreichbar und hat die Anmeldedaten akzeptiert.

Testen

Stellen Sie im Playground eine Frage, für deren Beantwortung das Tool benötigt wird, zum Beispiel „Wo ist Bestellung 1234?“. Prüfen Sie, ob die Antwort auf echten Daten basiert.

Kundendaten schützen

Kunden können im Widget oder im Vor-Chat-Formular eine beliebige E-Mail-Adresse eingeben. Manche Tools geben Daten eines einzelnen Kunden zurück oder ändern sie, etwa Bestellungen, Rechnungen oder Buchungen. Aktivieren Sie für solche Tools die E-Mail-Verifizierung.

Wenn Captain eines dieser Tools aufruft, bittet es den Kunden um seine E-Mail-Adresse. Chatwoot sendet einen 6-stelligen Code an diese Adresse, den der Kunde im Gespräch eingibt. Das Tool wird erst ausgeführt, nachdem Chatwoot überprüft hat, dass der Code korrekt ist.

• Die Verifizierung gilt nur für ein Gespräch. Sie ist bis zu 1 Stunde gültig, in E-Mail-Gesprächen bis zu 3 Stunden. Ein neues Gespräch beginnt ohne Verifizierung.

• Ein Code läuft nach 30 Minuten ab. Der Kunde kann einen Code 5-mal eingeben. Chatwoot sendet einem Kunden höchstens 5 Codes pro Stunde.

• Require email verification legt nicht fest, an welche E-Mail-Adresse das Tool sendet. Wenn Ihre API die E-Mail-Adresse aus einem normalen Parameter erhält, kann Captain jede beliebige E-Mail-Adresse senden. Damit das Tool nur die bestätigte E-Mail-Adresse sendet, verwenden Sie Add verified email.

• Chatwoot kann Anzeichen dafür erkennen, dass ein Tool Kundendaten verwendet. Wenn solche Anzeichen erkannt werden und für das Tool keine E-Mail-Verifizierung aktiviert ist, zeigt Chatwoot vor dem Speichern die Meldung Save without email verification? an. Klicken Sie auf Go back oder Save anyway.

• Im Playground und in Antwortvorschlägen ist der Benutzer ein Teammitglied. Captain füllt den Parameter für die bestätigte E-Mail-Adresse aus. Das Ergebnis zeigt Ihnen, ob Chatwoot diese E-Mail-Adresse verifiziert hat.

• Bei installierten Toolsets können Administratoren Require email verification ein- oder ausschalten.

Mehr herausholen

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

• Jeder Assistent kann bis zu 50 Tools haben. Halten Sie die Liste trotzdem kurz: Bei vielen Tools ist es wahrscheinlicher, dass der Assistent das falsche auswählt.

• Wenn Sie ein Tool hinzufügen, bearbeiten, deaktivieren oder löschen, wirkt sich das nur auf den Assistenten aus, den Sie gerade ansehen. Tools, die bereits vor der Aufteilung der Tools nach Assistenten vorhanden waren, wurden in alle Assistenten kopiert. Prüfen Sie daher jeden einzelnen.

• Wenn Sie mehrere Assistenten einsetzen, geben Sie jedem nur die Tools, die er benötigt.

• Deaktivieren Sie ein Tool über den Schalter, statt es zu löschen. Wenn ein Szenario das Tool verwendet, warnt Chatwoot Sie vorher. Siehe Leitplanken, Richtlinien und Szenarien für Captain festlegen.

• Chatwoot sendet bei jeder Anfrage Header mit. Sie teilen Ihrem System mit, welches Konto, Gespräch, welcher Kontakt, Assistent und Posteingang betroffen sind.

  • X-Chatwoot-Verified-Email enthält die E-Mail-Adresse, die der Kunde mit einem Einmalcode bestätigt hat. Wenn der Kunde die Adresse nicht bestätigt hat, sendet Chatwoot diesen Header nicht.

  • X-Chatwoot-Contact-Email enthält die E-Mail-Adresse im Kontaktdatensatz. Jede Person kann diese Adresse eingeben. Verwenden Sie sie nicht, um private Daten zurückzugeben.

  • X-Chatwoot-Contact-Inbox-Verified ist true, wenn die Identitätsprüfung (HMAC) den Kontakt bestätigt hat. Dieser Header verifiziert nicht die E-Mail-Adresse.

  Wenn Ihr System private Daten zurückgibt, prüfen Sie X-Chatwoot-Verified-Email oder aktivieren Sie die E-Mail-Verifizierung für das Tool. Siehe Wie aktiviere ich die Identitätsprüfung in Chatwoot?.

• Wenn Ihre API von Kunden verfasste Texte zurückgibt, geben Sie nur die benötigten strukturierten Felder zurück. Captain liest die Antwort unverändert aus. Freitext kann daher Anweisungen enthalten, denen Captain möglicherweise folgt.

Fehlerbehebung

Weitere Ursachen: Fehlerbehebung bei Captain.