Templates

Kanal-spezifische Templates mit Branding — von WhatsApp HSM bis Email-Signaturen.

Jeder Channel hat seine eigenen Formvorgaben: WhatsApp will Pre-approved Templates für proaktive Nachrichten, Email braucht Signatur und HTML-Layout, Instagram darf nur ein Bild plus Text, Facebook Comments bekommen entweder einen Public Reply oder einen Private Reply. Die Inbox bündelt das als Template-System pro Channel, mit deinem Branding und mit Variablen-Substitution.

#Aufbau eines Templates

Templates liegen in config/tenants/<code>/inbox/templates/{channel}/{name}.php. Beispiel für eine Bestellbestätigungs-Antwort per Email:

return [
    'name' => 'order_status_reply',
    'channel' => 'email',
    'subject' => 'Ihre Bestellung {{order_number}} — Status-Update',
    'body_text' => <<<TXT
Hallo {{customer_first_name}},

Ihre Bestellung {{order_number}} wurde am {{shipped_at}} an die Adresse
{{shipping_address}} versendet. Tracking: {{tracking_link}}

Voraussichtliche Lieferung: {{eta}}

Viele Grüße
{{agent_name}}
TXT,
    'body_html' => null, // optional — wenn null, wird aus body_text generiert
    'required_vars' => ['order_number', 'customer_first_name', 'shipped_at', 'shipping_address', 'tracking_link', 'eta'],
    'optional_vars' => ['agent_name'],
];

Variablen in doppelten geschweiften Klammern werden zur Sendezeit ersetzt. Fehlt eine required Variable, wirft das Template einen Fehler — der Agent muss die Daten zuerst beschaffen (Tool-Call gegen ERP) bevor er das Template nutzt.

#WhatsApp HSM-Templates

WhatsApp ist der strengste Channel. Für alle proaktiven Nachrichten — und alle Antworten außerhalb des 24-Stunden-Fensters — brauchst du Pre-approved Templates im Meta Business Manager.

Die Plattform mappt das so:

return [
    'name' => 'shipping_notification',
    'channel' => 'whatsapp',
    'whatsapp_template_name' => 'shipping_notification_de', // muss exakt so im Meta BM heißen
    'whatsapp_language_code' => 'de',
    'whatsapp_category' => 'UTILITY',
    'body_components' => [
        [
            'type' => 'body',
            'parameters' => [
                ['type' => 'text', 'var' => 'customer_first_name'],
                ['type' => 'text', 'var' => 'order_number'],
                ['type' => 'text', 'var' => 'tracking_link'],
            ],
        ],
    ],
    'required_vars' => ['customer_first_name', 'order_number', 'tracking_link'],
];

Wichtig:

• Der whatsapp_template_name muss exakt dem im Meta Business Manager registrierten Namen entsprechen, sonst gibt Meta einen 400-Fehler zurück
• Templates dürfen erst genutzt werden, nachdem sie von Meta freigegeben sind (kann 24–48h dauern)
• Templates haben eine Kategorie (UTILITY, MARKETING, AUTHENTICATION) — die Kategorie bestimmt das Pricing pro Konversation

#Facebook Comments — Public/Private-Split

Bei Comments ist der Antwort-Modus eine Template-Eigenschaft:

return [
    'name' => 'product_question_public_reply',
    'channel' => 'facebook_comment',
    'reply_mode' => 'public', // 'public' oder 'private'
    'body_text' => 'Hallo {{first_name}}, wir helfen dir gerne — schick uns kurz deine Anfrage per PN, dann können wir individuell antworten 🙏',
    'required_vars' => ['first_name'],
];

// oder als Private Reply:
return [
    'name' => 'product_question_private_reply',
    'channel' => 'facebook_comment',
    'reply_mode' => 'private',
    'body_text' => 'Hallo {{first_name}}! Du hattest unter unserem Post {{post_excerpt}} gefragt — gerne hier privat: …',
    'required_vars' => ['first_name', 'post_excerpt'],
];

Private Replies sind pro Comment nur einmal möglich, danach verweigert Meta die API. Die Plattform protokolliert das — beim zweiten Versuch siehst du einen Hinweis im UI.

#Email-Templates mit HTML

Email-Templates können sowohl body_text als auch body_html enthalten. Wenn body_html gesetzt ist, wird ein Multi-Part-Mail mit beiden Varianten verschickt. Wenn nur body_text da ist, generiert die Plattform automatisch eine HTML-Version (mit der Tenant-Email-Signatur und dem Branding-Theme).

Du kannst pro Tenant ein Email-Layout definieren (config/tenants/<code>/email.php), das als Wrapper um alle Email-Templates gelegt wird — mit Logo, Footer, Adresszeile.

#Variablen-Quellen

Templates bekommen ihre Variablen aus:

1. Thread-Kontext (customer_first_name, email, phone, current_channel)
2. Backend-Tools (Tool-Calls vorm Template-Render — getOrderByNumber, getCustomerByEmail)
3. Manuelle Eingaben im UI, wenn der Mitarbeiter das Template aus der Sidebar wählt
4. Konstanten aus der Tenant-Config (agent_name, support_phone, eu_repository_url)

Der Agent wählt das Template automatisch, wenn er glaubt, dass es passt. Du als Mensch kannst Templates auch direkt anwenden — Klick in der Sidebar, Variablen werden ausgefüllt, du prüfst, schickst.

#Versionierung

Templates liegen in Git — jede Änderung ist nachvollziehbar. Bei WhatsApp-Templates musst du nach jeder Änderung am Body wieder ein neues Approval im Meta Business Manager beantragen (Meta-API-Vorgabe, nicht Plattform-Eigenheit).

#Best Practice

• Mit wenigen Templates starten: die fünf häufigsten Fälle pro Channel reichen für die ersten Wochen
• Variablen sparsam: je weniger Variablen, desto leichter ist es, das Template korrekt anzuwenden. Bei mehr als 5 Variablen wird's für den Agent (und Mensch) fehleranfällig
• WhatsApp-Templates konservativ: Meta lehnt Marketing-lastige Templates ab — bleib bei sachlichem, hilfreichem Ton. Bei Ablehnung kommt das Template in den Status REJECTED und ist nicht nutzbar
• A/B-Testing auf Channel-Ebene: gleicher Inhalt, zwei Formulierungen, beide eine Woche parallel — schauen, welche höhere Antwortrate liefert