Messenger-Webhook für Facebook-Seiten: Nachrichten und Erwähnungen
Das Feld messages der Facebook-Seiten-Webhooks wird ausgelöst, wenn eine Person der Seite eine Messenger-Nachricht sendet. Es liefert ein messaging-Array mit der seitenspezifischen ID des Absenders, der ID der Seite, einem Zeitstempel und der mid der Nachricht mit ihrem Text oder ihren Anhängen. Das Feld mention meldet neue Erwähnungen der Seite in Beiträgen und Kommentaren. Meta signiert beide mit X-Hub-Signature-256.
easyCoexistence leitet die Messenger-Nachrichten und Erwähnungen jeder verbundenen Seite sobald sie eintreffen an Ihren HTTPS-Endpoint weiter, signiert mit einem Secret für diese Seite und ohne gespeicherte Kopie.
Wie schnell Meta von einem Messenger-Webhook-Endpoint verlangt, jede Benachrichtigung mit 200 OK zu beantworten.
Schlagen Zustellungen so lange fehl, hebt Meta das Abo der App für die Webhooks der Seite auf, bis die App wieder abonniert.
Die seitenspezifische ID des Absenders in einem messages-Ereignis, eindeutig für jedes Paar aus Person und Seite.
Wie die Referenz von Meta das Feld sender eines mention-Ereignisses kennzeichnet.
Vergangene Webhook-Benachrichtigungen lassen sich später nicht abfragen, daher muss der Empfänger speichern, was er braucht.
Was sendet das Feld messages?
Eine Benachrichtigung, wenn eine Person der Seite eine Messenger-Nachricht schickt. Meta sendet Textnachrichten oder Nachrichten mit Anhängen, die unter anderem Bilder, Audio, Videos, Dateien oder Sticker sein können. Ein geteilter Link kann als Ersatzanhang eintreffen. Eine Antwort auf eine frühere Nachricht enthält reply_to mit der mid dieser Nachricht, und eine Schnellantwort enthält ihren payload.
Wie sieht ein messages-Ereignis aus?
Anders als Feed-Änderungen kommt eine Nachricht in einem messaging-Array innerhalb des entry der Seite an. Jedes Ereignis hat sender, die seitenspezifische ID der Person; recipient, die Seite; einen Zeitstempel; und message mit ihrer mid und text oder attachments mit einem type und einer payload-URL:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}Was sendet das Feld mention?
Eine change mit dem Feld mention, wenn die Seite in einem Beitrag oder Kommentar erwähnt wird. Sie enthält post_id oder comment_id, die message, einen etwaigen Link, ein Foto oder Video sowie item und verb. Meta warnt, dass sich einige dieser Beitrags- und Kommentar-IDs aus Gründen fehlender Berechtigung oder des Datenschutzes nicht abfragen lassen. Außerdem kennzeichnet die Referenz von Meta das Feld sender nur bei Workplace, sodass eine Erwähnung ohne ihren Autor eintreffen kann.
Welche Messenger-Felder werden nicht weitergeleitet?
easyCoexistence abonniert Seiten für messages, nicht für message_echoes, messaging_postbacks, message_reads oder message_deliveries. Daher werden von der Seite gesendete Nachrichten, Button-Klicks sowie Lese- und Zustellbestätigungen nicht weitergeleitet. Eine mit send_social_dm gesendete Antwort gibt stattdessen ihre eigene Nachrichten-ID zurück.
Wie gelangen Ereignisse an Ihren Endpoint?
Meta stellt Seiten-Webhooks an die App zu, die die Seite installiert hat, über eine einzige Callback-URL für die gesamte App. easyCoexistence prüft bei jeder Zustellung Metas X-Hub-Signature-256, antwortet Meta sofort und leitet jeden entry einer verbundenen Seite an den HTTPS-Endpoint weiter, den Sie dafür festlegen, signiert mit dem eigenen Signing-Secret dieser Seite. Festlegen können Sie ihn mit set_social_webhook_destination aus Claude oder ChatGPT oder mit PUT /channels/:id/webhook über die Partner API. Das Secret wird nur einmal angezeigt; erneutes Festlegen stellt ein neues aus, und eine URL mit dem Wert null schaltet die Weiterleitung ab.
Wie sieht ein weitergeleitetes Ereignis aus?
Ein POST mit der platform, der account_id, die list_social_accounts für die Verbindung der Seite liefert, der ID der Seite als external_id und entry: Metas entry für die Seite, unverändert. sender.id ist die recipient_id, die send_social_dm für eine Antwort innerhalb des 24-Stunden-Fensters erwartet:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}Wie verifizieren Sie ein weitergeleitetes Ereignis?
Jeder weitergeleitete POST trägt einen X-EC-Signature-Header in der Form t=<unix>,v1=<hex>. Dabei ist v1 der HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem rohen Body, geschlüsselt mit dem Signing-Secret der Seite. Berechnen Sie ihn über den Body genau so, wie er empfangen wurde, vergleichen Sie zeitkonstant und lehnen Sie einen Zeitstempel ab, der älter als 5 Minuten ist.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}Wird eine Zustellung wiederholt?
Nicht durch easyCoexistence. Jeder Eintrag wird einmal im Arbeitsspeicher weitergeleitet, ohne Kopie, von der aus wiederholt werden könnte. Die Weiterleitung wartet 8 Sekunden auf eine Antwort, folgt keinen HTTP-Weiterleitungen und geht nur an eine HTTPS-Adresse, die auf eine öffentliche IP aufgelöst wird. Meta weist darauf hin, dass sich vergangene Benachrichtigungen später nicht abfragen lassen. Speichern Sie daher, was Sie brauchen, sobald es eintrifft. Vorgelagert wiederholt Meta eine fehlgeschlagene Zustellung einige Male kurz hintereinander, sodass dieselbe Nachricht gelegentlich zweimal bei Ihnen ankommen kann. Deduplizieren Sie deshalb anhand ihrer mid.
Häufige Fehler
- Die Arbeit vor der Antwort erledigen. Die Weiterleitung wiederholt nichts, geben Sie daher sofort ein 2xx zurück und verarbeiten Sie das Ereignis danach.
- Die Signatur am geparsten JSON prüfen. Berechnen Sie den HMAC über den rohen Body genau so, wie er eingetroffen ist.
- Annehmen, dass eine Nachricht immer Text hat. Ein Sticker, ein Bild oder ein geteilter Link kommt als attachments an, ohne text-Feld.
- Auf Deduplizierung verzichten. Meta kann ein Ereignis nach einem Fehler erneut liefern, daher prüfen Sie vor jeder Aktion die mid der Nachricht.
send_social_dm antwortet innerhalb des 24-Stunden-Fensters. Aktivieren Sie die Weiterleitung mit set_social_webhook_destination oder der Partner API. US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit jeder weiteren Verbindung, mit 3 Tagen kostenloser Testphase.
Häufig gestellte Fragen
Welche Webhook-Felder abonniert easyCoexistence für eine Seite?
messages für Messenger und mention für Erwähnungen, neben feed für Beiträge und Kommentare der Seite.
Kommt ein Messenger-Sticker oder ein Bild mit Text?
Nein. Ein Sticker, ein Bild oder ein geteilter Link kommt in attachments an, jeweils mit einem type und einer payload-URL, und die Nachricht enthält kein text-Feld.
Wie schnell muss ein Messenger-Webhook-Endpoint antworten?
Mit 200 OK innerhalb von 5 Sekunden. Nach 1 Stunde fehlgeschlagener Zustellungen hebt Meta das Abo der App für die Webhooks der Seite auf.
Wie antworte ich auf eine weitergeleitete Nachricht?
Rufen Sie send_social_dm mit der sender.id aus dem Ereignis als recipient_id auf, innerhalb von 24 Stunden nach der Nachricht der Person.
Weiterlesen
Verbinden Sie Ihren ersten Kanal in zwei Minuten.
Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.
- 3 Tage kostenlos
- Jederzeit kündbar
- Nur offizielle APIs
- Überwacht rund um die Uhr (24/7)
Verifiziert am