Messenger webhook za Facebook stranice: poruke i spominjanja
Polje messages u Facebook webhookovima stranica pokreće se kad osoba pošalje stranici Messenger poruku i isporučuje messaging niz s ID-om pošiljatelja vezanim uz stranicu, ID-om stranice, vremenskom oznakom i mid-om poruke s njezinim tekstom ili privitcima. Polje mention javlja nova spominjanja stranice u objavama i komentarima, a Meta oba potpisuje zaglavljem X-Hub-Signature-256.
easyCoexistence prosljeđuje Messenger poruke i spominjanja svake povezane stranice na vaš HTTPS endpoint čim stignu, potpisane tajnom za tu stranicu i bez čuvanja kopije, a send_social_dm odgovara unutar 24-satnog prozora.
Koliko brzo Meta traži od Messenger webhook endpointa da odgovori na svaku obavijest sa 200 OK.
Ako isporuke ne uspiju toliko dugo, Meta odjavljuje aplikaciju s webhookova stranice dok se ponovno ne pretplati.
ID pošiljatelja vezan uz stranicu u događaju messages, jedinstven za svaki par osobe i stranice.
Kako Metina referenca označava polje pošiljatelja u događaju spominjanja.
Prošle webhook obavijesti kasnije se ne mogu dohvatiti, pa primatelj mora pohraniti što mu treba.
Što šalje polje messages?
Obavijest kad osoba pošalje stranici Messenger poruku. Meta šalje tekstualne poruke ili poruke s privitcima, koji mogu biti slike, audio, video, datoteke ili naljepnice, među ostalim vrstama, a podijeljena poveznica može stići kao privitak zamjenskog tipa. Odgovor na raniju poruku nosi reply_to s mid-om te poruke, a brzi odgovor nosi svoj payload.
Kako izgleda događaj messages?
Za razliku od promjena feeda, poruka stiže u messaging nizu unutar entryja stranice. Svaki događaj ima sender, ID osobe vezan uz stranicu; recipient, stranicu; vremensku oznaku; i message, s mid-om i tekstom ili privitcima s tipom i URL-om payloada:
{
"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!"
}
}
]
}
]
}Što šalje polje mention?
Promjenu s poljem mention kad se stranica spomene u objavi ili komentaru, s post_id ili comment_id, porukom, eventualnom poveznicom, fotografijom ili videom te item i verb. Meta upozorava da se neki ID-ovi objava i komentara ne mogu dohvatiti zbog nedostatka dopuštenja ili privatnosti, a njezina referenca označava polje sender samo za Workplace, pa spominjanje može stići bez autora.
Koja Messenger polja se ne prosljeđuju?
easyCoexistence pretplaćuje stranice na messages, a ne na message_echoes, messaging_postbacks, message_reads ni message_deliveries, pa se poruke koje stranica šalje, pritisci na gumbe te potvrde čitanja i isporuke ne prosljeđuju. Odgovor poslan putem send_social_dm vraća vlastiti ID poruke.
Kako događaji stižu do vašeg endpointa?
Meta isporučuje webhookove stranica aplikaciji koju je stranica instalirala, kroz jedan callback URL za cijelu aplikaciju. easyCoexistence provjerava Metin X-Hub-Signature-256 na svakoj isporuci, odmah odgovara Meti i prosljeđuje svaki entry povezane stranice na HTTPS endpoint koji ste za nju postavili, potpisan vlastitom tajnom te stranice. Postavite ga funkcijom set_social_webhook_destination iz Claudea ili ChatGPT-ja, ili putem PUT /channels/:id/webhook na Partner API-ju; tajna se prikazuje jednom, ponovno postavljanje izdaje novu, a null URL isključuje prosljeđivanje.
Kako izgleda prosljeđeni događaj?
POST koji sadrži platform, account_id koji list_social_accounts daje vezi stranice, ID stranice kao external_id te entry: Metin entry za stranicu, nepromijenjen. sender.id je recipient_id koji send_social_dm uzima za odgovor unutar 24-satnog prozora:
{
"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>" }
}
]
}
}Kako provjeriti prosljeđeni događaj?
Svaki prosljeđeni POST nosi zaglavlje X-EC-Signature u obliku t=<unix>,v1=<hex>, gdje je v1 HMAC-SHA256 vremenske oznake, točke i sirovog tijela zahtjeva, ključem koji je tajna potpisivanja te stranice. Izračunajte ga nad tijelom točno onako kako je primljeno, usporedite u stalnom vremenu i odbijte vremensku oznaku stariju od 5 minuta.
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));
}Ponavlja li se isporuka?
Ne u easyCoexistence. Svaki entry se prosljeđuje jednom, u memoriji, bez kopije iz koje bi se ponovno mogao poslati; prosljeđivanje čeka odgovor 8 sekundi, ne slijedi preusmjeravanja i ide samo na HTTPS adresu koja se razrješava na javnu IP adresu. Meta napominje da se prošle obavijesti kasnije ne mogu dohvatiti, pa pohranite što vam treba čim stigne. Uzvodno Meta neuspjelu isporuku ponovi nekoliko puta odmah, pa ista poruka može povremeno doći dvaput: deduplicirajte je po njezinom mid-u.
Uobičajene pogreške
- Rad prije odgovora. Prosljeđivanje se ne ponavlja, pa vratite 2xx odmah i obradite događaj poslije.
- Provjera potpisa na parsiranom JSON-u. HMAC izračunajte nad sirovim tijelom točno onako kako je stiglo.
- Pretpostavka da poruka uvijek ima tekst. Naljepnica, slika ili podijeljena poveznica stižu kao privitci, bez polja text.
- Preskakanje deduplikacije. Meta može ponovno isporučiti događaj nakon neuspjeha, pa mid poruke upotrijebite kao ključ prije bilo kakve radnje.
Uključite prosljeđivanje funkcijom set_social_webhook_destination ili Partner API-jem. US$ 9 do US$ 0,75 po vezi mjesečno, uz to da cijena pada kako dodajete veze, a prvih 3 dana su besplatna.
Često postavljana pitanja
Koja webhook polja easyCoexistence pretplaćuje stranicu?
messages za Messenger i mention za spominjanja, uz feed za objave i komentare stranice.
Dolazi li Messenger naljepnica ili slika s tekstom?
Ne. Naljepnica, slika ili podijeljena poveznica stiže u privitcima, svaki s tipom i URL-om payloada, a poruka nema polje text.
Koliko brzo Messenger webhook endpoint mora odgovoriti?
Sa 200 OK unutar 5 sekundi. Nakon 1 sata neuspjelih isporuka Meta odjavljuje aplikaciju s webhookova stranice.
Kako odgovoriti na prosljeđenu poruku?
Pozovite send_social_dm sa sender.id iz događaja kao recipient_id, unutar 24 sata od poruke te osobe.
Nastavite čitati
Povežite svoj prvi kanal u dvije minute.
Bez čekanja na provjere platformi. Povežite WhatsApp, Instagram, TikTok ili drugi kanal, zatim zamolite svoju umjetnu inteligenciju da objavi, odgovori ili izradi izvješće i gledajte kako radi.
- 3 dana besplatno
- Otkažite bilo kada
- Samo službeni API-ji
- Nadzor 24/7
Provjereno na