Channels

Die sechs Kanäle der Inbox — Setup, Webhooks, Limits, Eigenheiten.

Die Inbox versteht heute sechs Kanäle. Jeder hat seinen eigenen Adapter (src/Service/Messaging/Adapter/...), eigene Webhook-Routen und kanalspezifische Eigenheiten — aber alle landen am Ende im selben Inbox-Thread.

#Übersicht

#Email

Der älteste und am gründlichsten getestete Adapter. Eingang läuft über IMAP-Polling (alle 60 Sekunden), Versand über tenant-spezifisches SMTP oder Resend.

Setup:

1. IMAP-Postfach (z. B. support@deine-firma.de) in config/tenants/<code>/email.php eintragen
2. SMTP-Zugang einrichten oder Resend-API-Key hinterlegen
3. Auto-Reply-Regeln + Klassifizierungs-Profil definieren (siehe Auto-Reply)

Eigenheiten:

• Threading via In-Reply-To und References Header. Bei Mailclients, die Re:-Prefix mit ihrer eigenen Konvention überschreiben, kann Threading reißen — der Adapter hat einen Fuzzy-Fallback über Subject-Normalisierung + Email-Adresse.
• Anhänge werden als Files persistiert und stehen dem Agenten als uploads zur Verfügung. Bilder werden bei Bedarf an das Vision-Modell weitergereicht.
• HTML→Text-Konvertierung entfernt Marketing-Wrapper, Signaturen mit Trennlinien (-- ), Quoting-Blöcke (> Zitate). So sieht der Agent die eigentliche Nachricht.
• Auto-Resolve für Bounces (Subject enthält „Delivery failed", X-Failed-Recipients-Header), Out-of-Office (Auto-Submitted-Header), Spam (X-Spam-Status, sender reputation).

#Facebook Messenger

Setup:

1. Facebook App im Meta-Developer-Dashboard anlegen
2. Page-Token für die Seite generieren
3. Webhook-URL https://app.taskmonkey.de/webhooks/meta/{tenant}/messenger mit dem Verify-Token aus der Tenant-Config registrieren
4. messages, messaging_postbacks, message_reactions als Events abonnieren

Eigenheiten:

• 24-Stunden-Antwortfenster: Nach 24 Stunden ohne User-Interaktion brauchst du ein Message Tag oder Human Agent Tag, um eine Nachricht zu senden, ohne dass Meta sie ablehnt. Die Plattform setzt das Tag automatisch, wenn du via Inbox-UI antwortest und das Fenster abgelaufen ist.
• PSID (Page-Scoped User ID) statt User-Profil: du siehst keinen echten Namen, sondern Vorname + Nachname, wie der User sie für Messenger eingestellt hat. Über User Profile API kannst du Profilbild + öffentliche Daten nachladen.
• Threading ist trivial: PSID = Thread.

#Instagram-DM

Setup analog Facebook Messenger, aber:

• Instagram Business Account muss mit einer Facebook-Seite verknüpft sein (sonst keine API-Permission)
• Webhook-Event: messages auf dem instagram Subscription Object
• Comments und DMs sind getrennte Webhook-Events — DMs kommen über den Instagram-Adapter, Comments über den Facebook-Adapter (Page-Feed)

Eigenheiten:

• Nur Text + ein Bild pro Nachricht
• Reactions (Herz, Lachen, …) lösen ebenfalls Webhook-Events aus — die Inbox blendet sie als Status-Update im Thread ein, aber der Agent reagiert nicht darauf
• Story-Replies werden als reguläre DM zugestellt, mit Reference auf die Story

#WhatsApp Business

Über die Meta WhatsApp Cloud API.

Setup:

1. Meta Business Account mit WhatsApp Business API aktivieren (Phone Number Verification)
2. Phone-Number-ID und Access Token in config/tenants/<code>/apis.php hinterlegen
3. Webhook auf https://app.taskmonkey.de/webhooks/meta/{tenant}/whatsapp registrieren

Eigenheiten:

• 24-Stunden-Antwortfenster wie bei Messenger. Außerhalb dieses Fensters darfst du nur HSM-Templates (Pre-approved Templates mit Variablen) senden — Freitext ist verboten und wird von Meta abgelehnt.
• Templates musst du im Meta Business Manager anlegen und genehmigen lassen. Die Plattform unterstützt das Senden via Template-Name + Variablen-Map (siehe Templates).
• Kostenmodell: Konversationsbasiert. Jede Konversation (= 24-Stunden-Fenster) kostet je nach Region 0.005–0.07 €. Die Plattform aggregiert das pro Tenant für die spätere Abrechnung.

#Facebook Comments

Kommentare unter Posts deiner Facebook-Seite. Anders als DMs sind sie öffentlich und tauchen unter dem Post auf — was ein Standard-Customer-Service-Tool damit machen kann, ist begrenzt.

Setup:

• Standard-Meta-Webhook, Subscription auf feed Event
• Filter: nur Comments auf eigenen Posts, nicht eigene Comments

Eigenheiten:

• Public Reply: öffentlicher Kommentar als Antwort. Alle sehen sie.
• Private Reply: Meta erlaubt einmal pro Comment, dem User eine private Messenger-Nachricht zu schicken (nur einmal!). Das ist nützlich für „Wir helfen dir gerne — schreib uns bitte privat".
• Threading: ein Comment-Thread wird in der Inbox als ein Thread dargestellt, mit post_id:psid als Thread-Key.
• Hide/Delete: Spam-Comments kann der Agent automatisch ausblenden (nicht löschen — Deletion ist destruktiv und nicht reversibel).

#Web-Chat-Widget

Das TaskMonkey Chat-Widget auf deiner eigenen Website. Im Gegensatz zu den Social-Channels ist es direkt mit dem Chat-System integriert — keine externen Webhooks nötig.

Setup:

• Widget per <script>-Tag einbinden (siehe Widget-Embedding)
• Public-Chat-Config mit eigenem Assistant + erlaubten Tools
• Branding via Widget-Theme

Eigenheiten:

• Anonyme Sessions: kein Login. User wird über ein gehashtes Cookie identifiziert (max. 30 Tage), Reload startet neue Session.
• Realtime via SSE: Antworten streamen direkt ohne Polling, gleicher Mechanismus wie der eingeloggte Chat.
• Lead-Erfassung optional: Wenn ein User Kontakt aufnehmen will, fragt der Agent nach Name/Email/Telefon und legt einen Lead in Supabase an.
• Cross-Channel-Bridge: Mit der gleichen Email-Adresse, mit der ein User später per Mail schreibt, wird der Web-Widget-Thread mit dem Email-Thread automatisch zusammengeführt (falls Auto-Merge aktiviert ist).

#Adapter-Architektur

Jeder Channel hat einen Adapter im Verzeichnis src/Service/Messaging/Adapter/. Der Adapter ist verantwortlich für:

• Inbound: Webhook-Payload entgegennehmen, validieren (Signature-Check), in ein generisches InboundMessage-Objekt überführen
• Outbound: Generisches Reply-Objekt entgegennehmen, kanalspezifisch (Tag, Template, Public/Private) ausliefern
• Threading: chat_id deterministisch ableiten (PSID, Email-Adresse, Phone-Number)
• Profil-Lookup: User-Daten lazy laden (Avatar, Name)

Das InboundMessage-Objekt ist generisch — ab dem Punkt, an dem es übergeben wird, kennt der nachgelagerte Code (Klassifizierung, Auto-Reply, LLM-Aufruf) den Channel nicht mehr. Das bedeutet: ein neuer Channel = neuer Adapter, der Rest funktioniert ohne Änderung.

Aktuell vorhanden:

src/Service/Messaging/Adapter/
├── EmailAdapter.php
├── FacebookAdapter.php
├── FacebookCommentAdapter.php
├── InstagramAdapter.php
├── MetaMessagingAdapter.php   # gemeinsame Basisklasse
└── WhatsAppAdapter.php

Geplante Channels (siehe Roadmap): Telegram, Slack, Microsoft Teams, LinkedIn-DMs.