Welche WhatsApp-Webhook-Events sendet TextMeFlow? Ein Überblick
Du hast eine Webhook-URL eingerichtet und TextMeFlow sendet Daten an deinen Server – aber welche Events genau, und was steckt in jeder Payload? Dieser Überblick hilft dir zu entscheiden, welche Events du abfangen und welche du ignorieren kannst.
Warum Events (und nicht nur „Nachricht eingegangen")
Die meisten Integrationen denken nur an eingehende Nachrichten, aber eine WhatsApp-Anbindung erzeugt mehr Signale als das: Zustellstatus, Sitzungsstatus des gekoppelten Geräts und Fehlermeldungen. Wenn du nur auf eingehende Nachrichten reagierst, übersiehst du zum Beispiel, dass deine Nummer die Verbindung verloren hat und ausgehende Nachrichten schon eine Weile nicht mehr ankommen.
Jeder Webhook-Aufruf ist ein POST mit JSON-Body und einem event-Feld, das den Typ angibt. Wie du die HMAC-Signatur bei jedem Aufruf korrekt verifizierst, steht in unserer separaten Anleitung zum Verifizieren von Webhook-Signaturen – dieser Artikel konzentriert sich auf die Events selbst.
message.received
Das am häufigsten genutzte Event: Jemand sendet eine WhatsApp-Nachricht an deine gekoppelte Nummer. Die Payload enthält die Absendernummer, den Nachrichtentyp (Text, Bild, Dokument, Standort, …), den Inhalt oder die Medien-URL und einen Zeitstempel. Auf diesem Event baust du Chatbots, Auto-Replies und Ticket-Routing auf.
Beachte: Medien (Fotos, PDFs, Sprachnachrichten) kommen nicht inline in der Payload, sondern als temporäre Download-URL. Hole die Datei sofort ab – die URL ist nicht unbegrenzt gültig.
message.delivered und message.read
Für ausgehende Nachrichten, die du selbst über die API gesendet hast, erhältst du Statusupdates zurück:
message.delivered– die Nachricht ist auf dem Gerät des Empfängers angekommen.message.read– der Empfänger hat die Nachricht geöffnet (blauer Haken), sofern er diese Funktion auf seiner Seite nicht deaktiviert hat.
Diese Events eignen sich ideal, um Zustell-Dashboards zu bauen oder zu erkennen, dass eine bestimmte Nummer systematisch nicht erreicht wird – oft ein Zeichen für eine falsche oder stillgelegte Nummer, nicht für ein Problem auf deiner Seite.
message.failed
Eine ausgehende Nachricht konnte nicht zugestellt werden. Die Payload enthält einen Fehlercode und eine Beschreibung. Meist handelt es sich um eine ungültige oder nicht bei WhatsApp registrierte Nummer, einen Empfänger, der dich blockiert hat, oder einen vorübergehenden Zustellfehler bei WhatsApp selbst. Baue hier Retry-Logik mit Maß auf: Blindes erneutes Senden nach einem failed erhöht deinen Risikowert in der Anti-Spam-Pipeline.
session.connected und session.disconnected
Diese beiden Events betreffen nicht Nachrichten, sondern den Status des gekoppelten WhatsApp-Geräts selbst:
session.connected– das Gerät ist (wieder) gekoppelt und aktiv. Dieses Event feuert auch bei einer erneuten Verbindung, nicht nur bei der ersten Kopplung.session.disconnected– die Kopplung ist unterbrochen (Gerät offline, WhatsApp abgemeldet, Netzwerkproblem). Ab diesem Moment werden keine Nachrichten mehr gesendet oder empfangen, bis neu gekoppelt wird.
Für jede Produktivumgebung empfiehlt es sich, bei session.disconnected einen Alarm auszulösen (Slack, E-Mail, Monitoring-Tool) – das ist das Event, das du am schnellsten wissen willst, denn ohne aktive Sitzung steht dein gesamter WhatsApp-Kanal still.
In der Praxis: ein Endpunkt, ein Switch
Die meisten Teams verarbeiten alle Events an einem Webhook-Endpunkt und routen intern anhand des event-Felds:
app.post('/webhooks/textmeflow', (req, res) => {
const { event, data } = req.body;
switch (event) {
case 'message.received':
handleIncoming(data);
break;
case 'message.delivered':
case 'message.read':
updateDeliveryStatus(data);
break;
case 'message.failed':
logFailure(data);
break;
case 'session.disconnected':
alertTeam(data);
break;
}
res.sendStatus(200);
});
Antworte immer schnell mit einem 2xx-Status, auch wenn deine Verarbeitung asynchron läuft – sonst wertet TextMeFlow den Aufruf als fehlgeschlagen und es folgt ein Retry, was bei fehlender Idempotenz zu doppelter Verarbeitung führen kann.
Loslegen
Lege deine Webhook-URL im Dashboard fest und teste mit einer Nachricht an dich selbst: Du siehst sofort message.received eingehen, gefolgt von message.delivered, sobald WhatsApp es bestätigt. Noch kein Konto? Starte kostenlos mit 50 Nachrichten pro Monat, für immer – hier registrieren.
Selbst WhatsApp-Nachrichten per API senden?
Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.
Für immer gratis