WhatsApp-Webhooks: Nachrichten direkt an Ihren Server weiterleiten

Was sendet Meta tatsächlich an einen Webhook?

Ereignisse in Kategorien. Die Unterscheidung zwischen ihnen bestimmt Ihre Architektur.

Der Nachrichtenpfad enthält, was Kunden senden, und bei einer Coexistence-Nummer auch Echos dessen, was Ihr Team über die WhatsApp Business App sendet. Das sind die Felder messages und smb_message_echoes. Sie enthalten den Gesprächsinhalt.

Der operative Pfad enthält alles andere: account_update, wenn sich ein Verbindungsstatus ändert, phone_number_quality_update, wenn sich Qualität oder Durchsatz ändern, account_alerts, account_review_update, business_capability_update und phone_number_name_update. Diese enthalten keinen Gesprächsinhalt und bilden die Grundlage für das Monitoring.

Ein Anbieter, der sich in den Nachrichtenpfad einfügt, erhält die erste Gruppe. Einer, der das nicht tut, erhält sie nicht.

Wie verifiziert Meta einen Endpoint?

Mit einer GET-Anfrage, bevor Meta irgendetwas zustellt. Das Scheitern daran ist der häufigste Grund, warum eine scheinbar fertige Einrichtung niemals eine Nachricht erhält.

Meta ruft Ihre URL mit hub.mode auf subscribe, Ihrem hub.verify_token und einem hub.challenge-Wert auf. Ihr Endpoint muss diese Challenge als unveränderten Antworttext zurückgeben, nicht in JSON verpackt und ohne zusätzliche Inhalte. Andernfalls beginnt Meta nie mit der Zustellung, und kein Dashboard weist darauf hin.

Der Endpoint muss außerdem HTTPS verwenden. Ein Endpoint, der stillschweigend 404 zurückgibt, oder einer hinter einer Authentifizierungsschicht, die Meta abweist, sieht bis zum Ausbleiben der ersten Nachricht wie eine funktionierende Einrichtung aus.

Kann das Ziel auf Ihren eigenen Server zeigen?

Ja. Genau darin unterscheiden sich die Anbieter.

Meta erlaubt einer App, zu überschreiben, wohin ein bestimmtes WhatsApp Business Account seine Webhooks zustellt. Wir setzen diese Überschreibung auf Ihre URL. Dadurch werden die Ereignisse des Nachrichtenpfads von unserem Callback an Ihren Endpoint verschoben. Die operativen Ereignisse behalten wir, weil Dashboard und Alarmierung daraus bestehen.

Die Folge ist architektonischer Natur und keine von uns veröffentlichte Richtlinie. Gesprächsinhalte können auf unserer Seite nicht gespeichert werden, weil sie uns nie zugestellt werden. Bei einem Konto ohne gesetzte Überschreibung greift unser Standard-Callback, dessen Handler diese Ereignisse verwirft, ohne sie zu speichern.

Was passiert mit dem Ziel, wenn eine Nummer erneut verbunden wird?

Es wird entfernt. Das ist der Fehler, den fast niemand einplant.

Das Ziel ist keine Eigenschaft der Telefonnummer. Es ist eine Überschreibung des Abonnements unserer App für das WhatsApp Business Account. Wenn eine Verbindung entfernt wird, aufgrund der vierzehntägigen Inaktivitätsregel von Meta oder aus einem anderen Grund, wird die App aus diesem Konto deinstalliert und die Überschreibung entfernt.

Eine erneute Verbindung stellt das Senden und das Monitoring wieder her. Sie stellt die Zustellung an Ihren Server jedoch nicht wieder her, und kein Fehler wird gemeldet. Das erste Anzeichen ist daher oft ein Kunde, der sagt, dass niemand geantwortet hat. Wir wenden die Überschreibung bei jeder erneuten Verbindung erneut an, weil genau das bei einer echten Nummer passiert ist, die sauber wieder verbunden wurde und anschließend stumm blieb.

Häufige Fehler

• Beim Verifizierungs-GET JSON zurückgeben. Meta erwartet den unveränderten Wert von hub.challenge und nichts anderes.
• Eine vorübergehende oder Test-URL verwenden. Meta sendet weiterhin dorthin, nachdem das Tool, das sie erzeugt hat, nicht mehr zuhört.
• Annehmen, dass das Ziel eine erneute Verbindung übersteht. Es gehört zu einem App-Abonnement und wird mit diesem deinstalliert.
• Den Endpoint hinter eine Authentifizierung setzen, die Metas Anfrage abweist.

Häufig gestellte Fragen

Weiterlesen