WhatsApp-Vorlagen und Business API

WhatsApp verlangt, dass geschäftliche Nachrichten mit Regeln funktionieren, vorab genehmigte Vorlagen für die erste Nachricht, ein 24-Stunden-Fenster für freie Nachrichten und Begrenzungen für Anhänge. So funktioniert es in Tesoro über Twilio.

WhatsApp-Einstellungen — Vorlagen-Einstellungen auf dem persönlichen Einstellungsbildschirm.

Wann ist dies relevant?

Erste Nachricht an einen Kontakt schlägt fehl, Sie suchen die Vorlagenregel
Das 24-Stunden-Fenster ist abgelaufen und Sie verstehen nicht, warum Sie nicht mehr senden dürfen
Sie möchten wissen, was es kostet

Wie die Integration funktioniert

Tesoro spricht nicht direkt mit WhatsApp:

Tesoro → Nachricht an Twilio API
Twilio → Weiterleitung an WhatsApp Business API (whatsapp:-Präfix)
WhatsApp → Zustellung beim Empfänger
Statusaktualisierungen (delivered, read, failed) zurück via Twilio-Webhooks
Eingehende Nachrichten → in Echtzeit an alle Teammitglieder

Was Sie benötigen

Komponente	Was
Twilio-Konto	Aktiv, mit Guthaben
WhatsApp Business-Profil	Von Meta über Twilio genehmigt
Registrierte WhatsApp-Nummer	Speziell für WhatsApp Business API; eingerichtet unter Settings → Company Settings → Call Settings
Twilio SID + Token	API-Anmeldedaten, durch Systemadministrator konfiguriert

Nachrichtenvorlagen: was und warum

Vorab genehmigte Nachrichtenformate. Erforderlich für die erste Nachricht an einen Kontakt.

In Tesoro hat jede Vorlage:

Feld	Was	Validierung
Title	Name zur Erkennung	3, 100 Zeichen
Description	Der Inhalt, der gesendet wird	3, 100 Zeichen

Vorlagen anzeigen

Automatisch geladen, wenn Sie den WhatsApp-Tab auf einem Datensatz öffnen. Verfügbar für Admin und Employee.

Eine Vorlage senden

WhatsApp-Tab des Kontakts/Deals/Leads/der Relation.
Keine Gesprächshistorie? → System fordert Vorlagenauswahl.
Aus Dropdown auswählen (Titel sichtbar).
Get Started → description wird als Nachrichtentext gesendet.
Nachricht registriert mit Zustellstatus, Twilio SID und Richtung.

Genehmigungsprozess (Meta)

Vorlage erstellen: in Twilio oder Meta Business Manager. Text + Kategorie (Marketing, Transaktional, Authentifizierung) + Variablen.
Prüfung durch Meta: Minuten bis Tage.
Genehmigung/Ablehnung: Twilio-Dashboard oder Meta Business Manager zeigt Status.
Registrierung in Tesoro: genehmigte Vorlagen erscheinen im Dropdown.

Häufige Ablehnungsgründe

Grund	Erläuterung
Irreführender Inhalt	Falsche oder irreführende Informationen
Keine Opt-Out-Möglichkeit	Keine Abmeldemöglichkeit für den Empfänger
Verbotener Inhalt	Glücksspiel, Alkohol, etc.
Falsche Formatierung	Variablen oder Formatierung entsprechen nicht den technischen Anforderungen

Wann: erste Nachricht oder nach Ablauf des 24-Stunden-Fensters
Wie: Vorlage auswählen, System sendet description
Anhänge: nicht unterstützt

Vergleich:

Merkmal	Vorlage	Frei
Erste Nachricht	✅ erforderlich	❌
Inhalt	Vordefiniert	Frei
Maximale Länge	100 Zeichen (Vorlagenlimit)	1.600 Zeichen
Dateianhänge	❌	✅ (bis zu 10)
Genehmigung erforderlich	✅ (Meta)	❌

Das 24-Stunden-Gesprächsfenster

WhatsApp-Regel zur Spam-Vermeidung.

Sie senden eine Vorlagennachricht → Gespräch geöffnet.
Der Kontakt antwortet → 24-Stunden-Fenster startet.
24 Stunden lang → Sie können freie Nachrichten ohne Vorlage senden.
Keine Antwort innerhalb von 24 Stunden → Fenster schließt. Neue Vorlage erforderlich, um das Gespräch wieder zu öffnen.

Was tun bei abgelaufenem Fenster

Wenn Sie nach 24 Stunden eine freie Nachricht versuchen? WhatsApp lehnt ab.

Gehen Sie zurück zur Vorlagenauswahl.
Wählen Sie eine genehmigte Vorlage.
Senden Sie, das Fenster öffnet sich erneut.
Warten Sie auf Antwort für freie Nachrichten.

Mediennachrichten: Dateien senden

Nur bei freien Nachrichten, nicht bei Vorlagen.

Wie Tesoro es verarbeitet:

Jede Datei = separate WhatsApp-Nachricht über Twilio mit mediaUrl
Text = separate Nachricht
Dateien werden in Tesoro gespeichert und mit dem Nachrichtendatensatz verknüpft

Unterstützte Typen

Typ	Beispiele
Dokumente	PDF, Word, Excel
Bilder	JPEG, PNG, GIF, WebP
Audio	MP3, OGG
Video	MP4
Archive	ZIP, RAR

Grenzen: max. 10 Dateien pro Nachricht, 1,5 MB pro Stück.

Dateien empfangen

Kontakt sendet Datei → Tesoro:

Erkennt via Twilio NumMedia-Webhook
Lädt herunter von der Twilio-Medien-URL
Speichert in Tesoro mit der richtigen Erweiterung (aus dem MIME-Typ)
Verknüpft mit Nachrichtendatensatz + Kontakt

Zustellstatus und Echtzeit-Updates

Status

Status	Was
queued	Warteschlange bei Twilio
sent	An WhatsApp gesendet
delivered	Auf dem Gerät des Empfängers
read	Empfänger hat gelesen
failed	Nicht zugestellt

Echtzeit-Updates

Eingehende Nachricht → Benachrichtigung an alle Benutzer
Statusänderung → Live-Update in der Chatansicht (keine Seitenaktualisierung)

Kosten

Komponente	Erläuterung
Twilio-Nachrichtentarif	Pro Nachricht (ein- + ausgehend), je nach Land unterschiedlich
WhatsApp-Gesprächst arif	Pro 24-Stunden-Fenster, Unterschied zwischen unternehmensgestartet (Vorlage) und nutzergestartet (Antwort)
Vorlagenkategorie	Marketing > Transaktional > Authentifizierung
Mediennachrichten	Zusätzliche Kosten je nach Typ + Größe

Rechte

Aktion	Wer
Nachrichten senden (frei)	Admin, Employee
Nachrichten senden (Vorlage)	Admin, Employee
Nachrichten lesen	Admin, Employee
Vorlagen anzeigen	Admin, Employee

Häufige Fehler

Vorlage erscheint nicht: Prüfen Sie Titel + Description (beide 3, 100 Zeichen). Möglicherweise nicht in Twilio registriert.
“The selected template doesn’t match our records”: Vorlagen-ID existiert nicht mehr (gelöscht?).
Nachricht nach 24 Stunden abgelehnt: Fenster abgelaufen. Neue Vorlage senden.
Anhänge bei Vorlage nicht möglich: Verwenden Sie eine freie Nachricht (nach Antwort des Kontakts).
“Company with Twilio WhatsApp number attached not found”: Die Nummer im Twilio-Webhook stimmt mit keinem Unternehmen überein. Prüfen Sie Settings → Company Settings → Call Settings.

Nächste Schritte

WhatsApp und SMS GrundlagenWie Sie senden + empfangen und welches Setup nötig ist.

TelefongesprächePlanen + anrufen über Twilio.