Webhook Messenger pentru paginile Facebook: mesaje și evenimente de mențiune
Câmpul messages din webhook-urile paginilor Facebook se activează când o persoană trimite paginii un mesaj Messenger, livrând un array messaging cu ID-ul expeditorului, specific paginii, ID-ul paginii, un marcaj de timp și mid-ul mesajului, împreună cu textul sau atașamentele acestuia. Câmpul mention raportează mențiunile noi ale paginii în postări și comentarii, iar Meta semnează ambele cu semnătura X-Hub-Signature-256.
easyCoexistence transmite mesajele și mențiunile Messenger ale fiecărei pagini conectate către endpoint-ul dumneavoastră HTTPS pe măsură ce sosesc, semnate cu un secret pentru fiecare pagină și fără nicio copie păstrată, iar send_social_dm răspunde în fereastra de 24 de ore.
Cât de repede cere Meta unui endpoint webhook Messenger să răspundă cu 200 OK la fiecare notificare.
După ce livrările eșuează atâta timp, Meta dezabonează aplicația de la webhook-urile paginii, până când se abonează din nou.
ID-ul expeditorului, specific paginii, din evenimentul messages, unic pentru fiecare pereche persoană și pagină.
Modul în care referința Meta marchează câmpul sender al unui eveniment mention.
Notificările webhook trecute nu pot fi interogate ulterior, așa că un receptor trebuie să stocheze ce are nevoie.
Ce trimite câmpul messages?
O notificare atunci când o persoană trimite paginii un mesaj Messenger. Meta trimite mesaje text sau mesaje cu atașamente, care pot fi imagini, audio, video, fișiere sau stickere, printre alte tipuri, iar un link distribuit poate sosi ca atașament de rezervă. Un răspuns la un mesaj anterior conține reply_to cu mid-ul acelui mesaj, iar un quick reply conține payload-ul său.
Cum arată un eveniment messages?
Spre deosebire de modificările din feed, un mesaj sosește într-un array messaging din interiorul entry-ului paginii. Fiecare eveniment are sender, adică ID-ul expeditorului specific paginii; recipient, adică pagina; un marcaj de timp; și message, cu mid-ul și textul sau cu atașamente, fiecare cu un type și un 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!"
}
}
]
}
]
}Ce trimite câmpul mention?
O modificare cu câmpul mention atunci când pagina este menționată într-o postare sau un comentariu, conținând post_id sau comment_id, mesajul, orice link, fotografie sau video, precum și item și verb. Meta avertizează că unele dintre acele ID-uri de postare și comentariu nu pot fi interogate, din lipsă de permisiune sau din motive de confidențialitate, iar referința sa marchează câmpul sender doar pentru Workplace, astfel că o mențiune poate sosi fără autorul ei.
Ce câmpuri Messenger nu sunt transmise?
easyCoexistence abonează paginile doar la messages, nu la message_echoes, messaging_postbacks, message_reads sau message_deliveries, așa că mesajele trimise de pagină, apăsările pe butoane și confirmările de citire sau livrare nu sunt transmise. Un răspuns trimis cu send_social_dm returnează în schimb propriul său ID de mesaj.
Cum ajung evenimentele la endpoint-ul dumneavoastră?
Meta livrează webhook-urile paginilor aplicației instalate de pagină, printr-un singur URL de callback pentru întreaga aplicație. easyCoexistence verifică semnătura X-Hub-Signature-256 de la Meta la fiecare livrare, răspunde imediat Meta și transmite fiecare entry pentru o pagină conectată către endpoint-ul HTTPS pe care îl setați pentru ea, semnat cu propriul secret al paginii. Setați-l cu set_social_webhook_destination din Claude sau ChatGPT, ori cu PUT /channels/:id/webhook din Partner API; secretul se afișează o singură dată, reatribuirea emite un secret nou, iar un URL null oprește transmiterea.
Cum arată un eveniment transmis?
Un POST care conține platform, account_id-ul pe care îl oferă list_social_accounts pentru conexiunea paginii, ID-ul paginii drept external_id și entry: entry-ul Meta pentru pagină, neschimbat. sender.id este recipient_id pe care îl primește send_social_dm pentru un răspuns în fereastra de 24 de ore:
{
"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>" }
}
]
}
}Cum verificați un eveniment transmis?
Fiecare POST transmis poartă antetul X-EC-Signature în forma t=<unix>,v1=<hex>, unde v1 este HMAC-SHA256 al marcajului de timp, al unui punct și al corpului brut, semnat cu secretul de semnare al paginii. Calculați-l peste corpul exact cum a fost primit, comparați în timp constant și respingeți un marcaj de timp mai vechi de 5 minute.
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));
}Se reîncearcă livrarea?
Nu de către easyCoexistence. Fiecare entry este transmis o singură dată, în memorie, fără o copie păstrată pentru reluare; transmiterea așteaptă 8 secunde un răspuns, nu urmează redirecționările și merge doar către o adresă HTTPS care se rezolvă la un IP public. Meta notează că notificările trecute nu pot fi interogate ulterior, deci stocați ce vă trebuie pe măsură ce sosește. În amonte, Meta reîncearcă de câteva ori imediat o livrare eșuată, astfel că același mesaj poate ajunge ocazional la dumneavoastră de două ori: deduplicați după mid.
Greșeli frecvente
- Lucrul efectuat înainte de răspuns. Transmiterea nu reîncearcă, deci returnați imediat un 2xx și procesați evenimentul ulterior.
- Verificarea semnăturii pe JSON deja parsat. Calculați HMAC-ul peste corpul brut exact cum a sosit.
- Presupunerea că un mesaj are întotdeauna text. Un sticker, o imagine sau un link distribuit sosesc ca atașamente, fără câmp text.
- Omiterea deduplicării. Meta poate livra din nou un eveniment după o eroare, deci identificați-l după mid-ul mesajului înainte de a acționa.
Activați transmiterea cu set_social_webhook_destination sau cu Partner API. US$ 9 până la US$ 0,75 pe conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu primele 3 zile gratuite.
Întrebări frecvente
Cu ce câmpuri webhook abonează easyCoexistence o pagină?
messages pentru Messenger și mention pentru mențiuni, alături de feed pentru postările și comentariile paginii.
Un sticker sau o imagine Messenger vine cu text?
Nu. Un sticker, o imagine sau un link distribuit sosește în atașamente, fiecare cu un type și un payload URL, iar mesajul nu are câmp text.
Cât de repede trebuie să răspundă un endpoint webhook Messenger?
Cu 200 OK în 5 secunde. După 1 oră de livrări eșuate, Meta dezabonează aplicația de la webhook-urile paginii.
Cum răspund unui mesaj transmis?
Apelați send_social_dm cu sender.id din eveniment drept recipient_id, în 24 de ore de la mesajul persoanei.
Continuați să citiți
Conectați primul canal în două minute.
Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.
- 3 zile gratuit
- Anulați oricând
- Doar API-uri oficiale
- Monitorizat 24/7
Verificat la