Mit benutzerdefinierten Tools kann Captain während Gesprächen Ihre externen APIs aufrufen – so kann er den Systemstatus überprüfen, Fahrpläne abfragen 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, setzt sie in Ihre API-Anfrage ein und verwendet die Antwort, um seine Antwort zu formulieren.

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

## Ein Tool erstellen

Navigieren Sie zu **Captain -> Tools** und klicken Sie auf **Neues Tool erstellen**.

\
![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQ1FZM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cb577b7e950815be109f2925cac60ce4b25305ac/CleanShot%202026-04-01%20at%2015.53.06@2x.png)

Füllen Sie die folgenden Felder aus:

**Toolname** — Ein kurzer Name wie „Systemstatus“ oder „Vorstellungen abfragen“ (max. 55 Zeichen).

**Beschreibung** — Geben Sie Captain an, wann dieses Tool zu verwenden ist. Dies ist das wichtigste Feld. Schreiben Sie es so, als würden Sie einen Support-Mitarbeiter einweisen: „Prüft den aktuellen Systemstatus einschließlich laufender Vorfälle oder Wartungen.“ Vage Beschreibungen wie „Status-API“ führen dazu, dass Captain das Tool möglicherweise nicht nutzt.

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

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

```
https://api.yourcompany.com/v1/showtimes?q={{ query }}
```

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

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

\
| Typ | Was Sie angeben | \
|------|-----------------| \
| Keine | Keine Authentifizierung | \
| Bearer-Token | Ein Token-String | \
| Basic Auth | Benutzername und Passwort | \
| API-Schlüssel | Ein benutzerdefinierter Headername und Wert |

Anmeldedaten für die Authentifizierung sind nur für Administratoren des Kontos sichtbar.

\
![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRDQ4M1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--dc19f2d14e08901f6921007175ffd5399064a947/CleanShot%202026-04-01%20at%2016.52.41@2x.png)

\
**Parameter** — Legen Sie fest, welche Werte Captain aus der Kundenanfrage extrahieren soll. Jeder Parameter benötigt einen Namen, Typ und eine Beschreibung. Beispiel: `query` (String) — „Der Filmtitel oder das Datum, nach dem der Kunde fragt.“

**Anfrage-Template** (nur POST) — Eine JSON-Body-Vorlage mit Liquid-Syntax:

```

{ "query": "{{ query }}", "source": "captain" }
```

**Antwort-Template** — Bestimmt, was Captain aus der API-Antwort sieht. Wenn leer, erhält Captain das rohe JSON. Verwenden Sie Liquid, um relevante Felder zu extrahieren:

```

Systemstatus: {{ response.status }}. {{ response.message }}
```

Verwenden Sie `response`, um auf das geparste JSON-Objekt zuzugreifen. Antwort-Templates helfen Captain, sich auf relevante Daten zu konzentrieren und interne Felder wie Datenbank-IDs oder Debug-Informationen auszublenden.

## Tool testen

Klicken Sie vor dem Speichern auf **Verbindung testen**, um zu prüfen, ob Ihr Endpoint erreichbar ist. Der Test gibt den HTTP-Statuscode zurück.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCREk5M1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--8a952a29edf820a845a1a3ca27072386c225eeef/image.png)

Ein grünes Ergebnis (HTTP 200–299) bedeutet, dass Verbindung und Authentifizierung funktionieren. Der Test sendet die URL ohne eingesetzte Parameterwerte, prüft also nur die Erreichbarkeit und die Korrektheit der Zugangsdaten.

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

* **401 Unauthorisiert** — Ihre Authentifizierungsdaten sind falsch. Überprüfen Sie Bearer-Token, API-Schlüssel oder Benutzername/Passwort.

* **403 Verboten** — Ihre API lehnt die Anfrage ab. Falls Identitätsprüfung erforderlich ist: Testanfragen enthalten keine Kontakt-Header.

* **404 Nicht gefunden** — Die Endpoint-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. Benutzerdefinierte Tools haben ein 30-Sekunden-Timeout; stellen Sie sicher, dass Ihre API rechtzeitig antwortet.

## Kontext, der mit jedem Tool-Aufruf gesendet wird

Wenn Captain Ihre API aufruft, werden Metadaten-Header mitgesendet, sodass Ihr Backend den Kontext kennt:

| Header | Beschreibung |

|--------|-------------|

| `X-Chatwoot-Account-Id` | Ihre Kontonummer |

| `X-Chatwoot-Conversation-Id` | Die Konversations-ID |

| `X-Chatwoot-Contact-Email` | Die E-Mail des Kunden (sofern verfügbar) |

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

\
Weitere Header sind `X-Chatwoot-Assistant-Id`, `X-Chatwoot-Tool-Slug`, `X-Chatwoot-Contact-Id`, `X-Chatwoot-Contact-Phone` und `X-Chatwoot-Conversation-Display-Id`.

Sie können diese Header nutzen, um den Kunden in Ihrem System nachzuschlagen, zu protokollieren, welche Konversationen API-Aufrufe ausgelöst haben, und die Echtheit von Anfragen zu überprüfen.

## Sicherheit

**Eingebaute Schutzmechanismen:**

* Alle Endpunkte müssen HTTPS verwenden

* Anfragen an private IP-Bereiche, localhost und `.local`-Domains werden blockiert

* HTTP-Weiterleitungen werden nicht gefolgt

* Antworten sind auf 1 MB begrenzt

* Zugangsdaten sind nur für Administratoren sichtbar

**Identitätsprüfung:** Wenn Ihr Tool kundenspezifische Daten bereitstellt (Bestellungen, Rechnungen, Kontodetails), sollte Ihre API den Header `X-Chatwoot-Contact-Inbox-Verified` prüfen. Ohne HMAC-Verifizierung im Posteingang des Kunden könnte ein Besucher jede beliebige E-Mail im Chat-Widget setzen. Geben Sie sensible Daten daher nur frei, wenn dieser Header `true` ist. Für Tools, die öffentliche Daten liefern (z. B. Pläne, Systemstatus), ist diese Prüfung nicht erforderlich.

**Prompt Injection:** Gibt Ihre API von Nutzern generierte Inhalte zurück (z. B. Bewertungen, Forenbeiträge), könnten bösartige Texte das Verhalten von Captain beeinflussen. Verwenden Sie Antwort-Templates, um ausschließlich strukturierte Felder zu extrahieren, und säubern Sie Inhalte auf API-Seite.

## Limits

| Limit | Wert |

|-------|------|

| Max. Tools pro Konto | 15 |

| Empfohlen | 10 oder weniger (Warnung bei mehr als 10) |

| Toolname Länge | 55 Zeichen |

| Antwortgröße | Max. 1 MB |

| Anfrage-Timeout | 30 Sekunden |

## Wann sollten benutzerdefinierte Tools verwendet werden?

Benutzerdefinierte Tools eignen sich am besten für strukturierte Abfragen mit vorhersehbaren Eingaben – etwa zur Systemstatusprüfung, zur Abfrage von Fahrplänen oder zum Abrufen von Datensätzen per ID. Haben Sie bereits eine dedizierte Chatwoot-Integration für Ihren Anwendungsfall (z. B. Shopify für E-Commerce), nutzen Sie diese – dedizierte Integrationen bieten zuverlässigere Suche, unscharfe Abgleiche und Datensynchronisierung als ein einzelner API-Aufruf.

## Beispiele

### Systemstatus prüfen

Ein einfaches Tool ohne Parameter – Captain ruft es auf, wenn ein Kunde fragt, ob etwas ausgefallen ist.

| Feld | Wert |

|-------|------|

| Toolname | Systemstatus |

| Beschreibung | Prüft den aktuellen Betriebsstatus des Systems einschließlich laufender Vorfälle oder geplanter Wartungen. Verwenden Sie dieses Tool, wenn ein Kunde Probleme meldet oder fragt, ob das System ausgefallen ist. |

| Methode | GET |

| Endpoint-URL | `https://status.yourcompany.com/api/v1/status` |

| Authentifizierung | Keine |

| Parameter | (keine) |

| Antwort-Template | `Systemstatus: {{ response.status }}. {{ response.message }}` |

\
![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTVViM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--243c121ad98c746cdbfb6aae317471cc2485ccad/CleanShot%202026-04-01%20at%2015.59.39@2x.png)

### Vorstellungen / Zeitpläne abfragen

Für Unternehmen mit Fahrplänen, Veranstaltungen oder Zeitlisten – Kunden fragen, was gerade läuft, und Captain holt den aktuellen Plan.

| Feld | Wert |

|-------|------|

| Toolname | Vorstellungen abfragen |

| Beschreibung | Ruft Filmvorstellungen und Vorführungszeiten ab. Verwenden Sie dieses Tool, wenn ein Kunde wissen möchte, welche Filme laufen oder wann ein bestimmter Film gezeigt wird. |

| Methode | GET |

| Endpoint-URL | `https://api.yourcinema.com/v1/showtimes?q={{ query }}` |

| Authentifizierung | Bearer-Token |

| Parameter | `query` (String, erforderlich) — „Der Filmtitel oder das Vorführdatum, nach dem der Kunde fragt“ |

| Antwort-Template | `{% for show in response.showtimes %}{{ show.title }} — {{ show.date }} um {{ show.time }}{% endfor %}` |

\
![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCREViM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2a8aaa32f6747f6cdfca6d3abcac3b62bce5060f/image.png)

Benutzerdefinierte Tools funktionieren am besten, wenn die Eingaben einfach und die API-Antworten vorhersehbar sind – Statusabfragen, Nachschlagen von Einträgen und andere strukturierte Anfragen sind ideale Anwendungsbeispiele.