Webhook Messengera na Facebooku: wiadomości i zdarzenia wzmianek
Pole messages w webhookach stron na Facebooku uruchamia się, gdy osoba wysyła stronie wiadomość w Messengerze. Dostarcza tablicę messaging z identyfikatorem nadawcy ograniczonym do strony, identyfikatorem strony, znacznikiem czasu oraz mid wiadomości z jej tekstem lub załącznikami. Pole mention zgłasza nowe wzmianki o stronie w postach i komentarzach. Meta podpisuje oba typy nagłówkiem X-Hub-Signature-256.
easyCoexistence przekazuje wiadomości Messengera i wzmianki każdej połączonej strony na Twój endpoint HTTPS w miarę ich nadejścia, podpisane sekretem dla tej strony i bez zachowywania kopii, a send_social_dm wysyła odpowiedzi w ramach 24-godzinnego okna.
Jak szybko Meta oczekuje od endpointu webhooka Messengera odpowiedzi 200 OK na każde powiadomienie.
Po tak długim czasie nieudanych dostarczeń Meta wypisuje aplikację z webhooków strony, dopóki ta ich ponownie nie zasubskrybuje.
Identyfikator nadawcy ograniczony do strony w zdarzeniu messages, unikalny dla każdej pary osoby i strony.
Jak dokumentacja firmy Meta opisuje pole sender w zdarzeniu mention.
Minionych powiadomień webhooków nie da się pobrać później, więc odbiorca musi zapisać to, czego potrzebuje.
Co wysyła pole messages?
Powiadomienie, gdy osoba wysyła stronie wiadomość w Messengerze. Meta przesyła wiadomości tekstowe oraz wiadomości z załącznikami, którymi mogą być m.in. obrazy, nagrania audio, wideo, pliki lub naklejki, a udostępniony link może dotrzeć jako załącznik zastępczy. Odpowiedź na wcześniejszą wiadomość zawiera reply_to z jej mid, a szybka odpowiedź zawiera swój payload.
Jak wygląda zdarzenie messages?
W przeciwieństwie do zmian w feedzie wiadomość trafia do tablicy messaging wewnątrz entry strony. Każde zdarzenie ma sender, czyli identyfikator nadawcy ograniczony do strony; recipient, czyli strona; timestamp; oraz message z jego mid i tekstem albo attachments z typem i adresem URL payloadu:
{
"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!"
}
}
]
}
]
}Co wysyła pole mention?
Zmianę z polem mention, gdy strona zostanie wspomniana w poście lub komentarzu. Zawiera post_id lub comment_id, treść wiadomości, ewentualny link, zdjęcie lub wideo oraz item i verb. Meta ostrzega, że części tych identyfikatorów postów i komentarzy nie da się pobrać z powodu braku uprawnień lub względów prywatności, a jej dokumentacja oznacza pole sender wyłącznie dla Workplace, więc wzmianka może dotrzeć bez autora.
Które pola Messengera nie są przekazywane?
easyCoexistence subskrybuje strony na messages, a nie na message_echoes, messaging_postbacks, message_reads ani message_deliveries, więc wiadomości wysłane przez stronę, kliknięcia przycisków oraz potwierdzenia odczytania i dostarczenia nie są przekazywane. Odpowiedź wysłana przez send_social_dm zwraca natomiast własny identyfikator wiadomości.
Jak zdarzenia docierają do Twojego endpointu?
Meta dostarcza webhooki stron do aplikacji, którą strona zainstalowała, przez jeden adres callback dla całej aplikacji. easyCoexistence sprawdza podpis X-Hub-Signature-256 przy każdym dostarczeniu, od razu odpowiada firmie Meta i przekazuje każdy wpis dotyczący połączonej strony na endpoint HTTPS, który dla niej podajesz, podpisany sekretem tej strony. Ustaw go poleceniem set_social_webhook_destination z poziomu Claude lub ChatGPT albo przez PUT /channels/:id/webhook w Partner API. Sekret jest pokazywany jednorazowo, ponowne ustawienie generuje nowy, a wartość null dla adresu URL wyłącza przekazywanie.
Jak wygląda przekazane zdarzenie?
Żądanie POST zawierające platform, account_id, który zwraca list_social_accounts dla połączenia strony, identyfikator strony jako external_id oraz entry: wpis firmy Meta dla strony, bez zmian. sender.id to recipient_id, którego używa send_social_dm przy odpowiedzi w ramach 24-godzinnego okna:
{
"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>" }
}
]
}
}Jak zweryfikować przekazane zdarzenie?
Każde przekazane żądanie POST zawiera nagłówek X-EC-Signature w postaci t=<unix>,v1=<hex>, gdzie v1 to HMAC-SHA256 liczony z połączenia znacznika czasu, kropki i surowego ciała, z kluczem będącym sekretem podpisu strony. Oblicz go na ciele dokładnie w takiej postaci, w jakiej przyszło, porównaj w stałym czasie i odrzuć znacznik czasu starszy niż 5 minut.
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));
}Czy dostarczenie jest ponawiane?
Nie przez easyCoexistence. Każdy wpis jest przekazywany jednokrotnie, w pamięci, bez kopii, z której można by ponowić próbę; przekazanie czeka 8 sekund na odpowiedź, nie podąża za przekierowaniami i trafia wyłącznie na adres HTTPS rozwiązujący się do publicznego IP. Meta zauważa, że minionych powiadomień nie da się pobrać później, więc zapisuj to, czego potrzebujesz, w momencie jego nadejścia. Po stronie firmy Meta nieudane dostarczenie jest ponawiane kilka razy od razu, więc ta sama wiadomość może sporadycznie dotrzeć dwukrotnie: deduplikuj ją po jej mid.
Typowe błędy
- Wykonywanie pracy przed odpowiedzią. Przekazywanie nie ponawia prób, więc zwróć od razu 2xx i przetwarzaj zdarzenie później.
- Weryfikowanie podpisu na sparsowanym JSON. Oblicz HMAC na surowym ciele dokładnie w takim kształcie, w jakim przyszło.
- Zakładanie, że wiadomość zawsze ma tekst. Naklejka, obraz lub udostępniony link przychodzi jako attachments, bez pola text.
- Pominięcie deduplikacji. Meta może ponownie dostarczyć zdarzenie po awarii, więc przed działaniem kluczuj je po mid wiadomości.
Przekazywanie włączysz poleceniem set_social_webhook_destination lub przez Partner API. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z dodawaniem połączeń, z 3-dniowym bezpłatnym okresem próbnym.
Najczęściej zadawane pytania
Które pola webhooków easyCoexistence subskrybuje dla strony?
messages dla Messengera i mention dla wzmianek, obok feed dla postów i komentarzy strony.
Czy naklejka lub obraz z Messengera ma tekst?
Nie. Naklejka, obraz lub udostępniony link przychodzi w attachments, każdy z typem i adresem URL payloadu, a wiadomość nie zawiera pola text.
Jak szybko endpoint webhooka Messengera musi odpowiedzieć?
Odpowiedzią 200 OK w ciągu 5 sekund. Po 1 godzinie nieudanych dostarczeń Meta wypisuje aplikację z webhooków strony.
Jak odpowiedzieć na przekazaną wiadomość?
Wywołaj send_social_dm, podając sender.id ze zdarzenia jako recipient_id, w ciągu 24 godzin od wiadomości osoby.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w