Chatwoot ist eine hervorragende Open-Source-Alternative zu Zendesk und Intercom: Multi-Channel-Postfach, saubere Konversations-Ansicht, API für alles. Was Chatwoot von Haus aus nicht kann: eingehende Nachrichten selbst klassifizieren und darauf reagieren. Genau das lässt sich mit einem KI-Agent nachrüsten — ohne Chatwoot zu forken.

Dieser Artikel zeigt das Muster, mit dem wir Chatwoot für yaico Inbox aufbohren: ein schlanker Agent hängt per Webhook an Chatwoot, klassifiziert jede Mail per LLM und löst konkrete Aktionen aus. Die Code-Basis ist das Open-Source-Framework pocketagent.

Das Prinzip: vier Stufen

Vom eingehenden Event bis zur Aktion durchläuft jede Nachricht vier Stufen:

1. Listen — Chatwoot-Webhook ruft einen eigenen Endpoint auf.
2. Guardrails — nur verarbeitenswerte Events kommen durch (kein Loop, kein Spam an den Agent).
3. Route — ein LLM klassifiziert die Nachricht in einen Intent.
4. Act — pro Intent laufen ein oder mehrere Action-Tools.

Schritt 1 — Den Webhook einrichten

In Chatwoot unter Settings → Integrations → Webhooks einen Webhook anlegen:

Feld	Wert
URL	https://<agent-host>/chatwootcb
Events	message_created

Ab jetzt bekommt der Agent jede neue Nachricht als POST-Request.

Schritt 2 — Guardrails, damit nichts entgleist

Der häufigste Fehler bei Chatwoot-Bots: Endlosschleifen (der Bot reagiert auf seine eigene Antwort) und Reaktionen auf Maschinen-Mails. Deshalb filtert der Endpoint vor jeder LLM-Klassifikation:

• Nur incoming-Nachrichten — Antworten des Agents selbst werden ignoriert (verhindert Loops).
• Nur E-Mail-Kanal — API-, Widget- und Social-Events fallen raus.
• Nur menschliche Absender (sender.type == "contact") — keine Agents/Bots.
• Cooldown (z. B. 30 s) pro Konversation nach einer Bot-Aktion.
• Outgoing-Check — war die letzte Nachricht schon vom Bot, passiert nichts.

Diese deterministische Kette ist der Grund, warum der Agent auch im Mittelstands-Postfach kein Spam-/Loop-Risiko ist.

Schritt 3 — Intent-Routing per LLM

Was durch die Guardrails kommt, klassifiziert ein LLM (mit Keyword-Fallback, falls das Modell mal nicht erreichbar ist) in einen klar definierten Intent. Für einen Shopify-Customer-Service z. B.:

Intent	Bedeutung
spam	Werbung, SEO-Angebote, Kooperationsanfragen
frustrated	Kunde ist verärgert, beschwert sich
return_request	Retoure / Rücksendung / Umtausch
refund_request	Explizite Geld-zurück-Forderung
shipping_status	Frage nach Versand-/Lieferstatus
ignore	Alles andere — keine Aktion

Schritt 4 — Intent auf Aktionen mappen

Das Herzstück ist ein deklaratives Mapping von Intent auf Aktionen. So bleibt die Logik lesbar und erweiterbar:

INTENT_ACTIONS = {
    "spam":            [{"type": "resolve"}],
    "frustrated":      [{"type": "notify_discord"}, {"type": "add_label", "label": "frustrated"}],
    "return_request":  [{"type": "send_return_link"}, {"type": "add_label", "label": "return_request"}],
    "refund_request":  [{"type": "notify_discord"}, {"type": "add_label", "label": "refund_request"}],
    "shipping_status": [{"type": "notify_discord"}, {"type": "add_label", "label": "shipping_status"}],
}

Die Action-Tools selbst sprechen die Chatwoot-API (bzw. Discord) an:

Action	Wirkung
resolve	Konversation in Chatwoot als erledigt markieren
add_label	Label an die Konversation hängen
notify_discord	Eskalation an einen Discord-Channel
send_return_link	Self-Service-Retouren-Link an den Kunden senden
send_message	Beliebige Textantwort an den Kunden

Erweitern: ein neuer Intent in 4 Zeilen

Weil das Mapping deklarativ ist, kostet ein neuer Anwendungsfall kaum Code. Beispiel Garantiefall:

INTENT_ACTIONS["warranty_claim"] = [
    {"type": "add_label", "label": "warranty"},
    {"type": "notify_discord"},
    {"type": "send_message", "content": "Vielen Dank, wir prüfen Ihren Garantiefall."},
]

Die Aktionen laufen in der angegebenen Reihenfolge. Sendet eine davon eine Nachricht, wird automatisch der Cooldown gesetzt — die Guardrails aus Schritt 2 greifen also auch hier.

Betrieb: als Sidecar neben Chatwoot

In Produktion läuft der Agent als eigener Container — bei uns als Sidecar-Deployment neben Chatwoot im Kubernetes-Cluster, ausgerollt per GitOps. Chatwoot und Agent teilen sich das Netzwerk, der Webhook zeigt cluster-intern auf den Agent. Updates an den Intents gehen damit denselben PR-/Rollout-Weg wie jeder andere Code.

Selbst bauen — oder bauen lassen

Das Muster ist bewusst einfach: Webhook, Guardrails, ein LLM-Router, ein paar Action-Tools. Wer mag, baut es auf Basis von pocketagent selbst.

Wenn ihr es lieber fertig betrieben wollt — gehostetes Chatwoot in Deutschland (DSGVO-konform) plus diesen KI-Agent als Triage — dann ist das genau yaico Inbox. Den Hosting-Teil beschreibt unsere Seite Chatwoot Hosting Deutschland.

→ Chatwoot gemanagt aus Deutschland

---