InloggenGratis proefperiode starten
easyCoexistence Officiële API's

Messenger-webhook voor Facebook Pages: berichten- en vermeldingsgebeurtenissen

Het veld messages van de Page-webhooks van Facebook wordt geactiveerd wanneer iemand de Page een Messenger-bericht stuurt. Het levert een messaging-array met de Page-scoped ID van de afzender, de ID van de Page, een tijdstempel en de mid van het bericht, samen met de tekst of bijlagen. Het veld mention meldt nieuwe vermeldingen van de Page in posts en reacties, en Meta ondertekent beide met X-Hub-Signature-256.

easyCoexistence stuurt de Messenger-berichten en vermeldingen van elke verbonden Page zodra ze binnenkomen door naar je HTTPS-endpoint, ondertekend met een geheim voor die Page en zonder kopie te bewaren, en send_social_dm beantwoordt binnen het venster van 24 uur.

5 seconds

Hoe snel Meta van een Messenger-webhookendpoint verwacht dat het elke melding beantwoordt met 200 OK.

1 hour

Als leveringen zo lang mislukken, heft Meta de abonnering van de app op de webhooks van de Page op totdat je opnieuw abonneert.

PSID

De Page-scoped ID van de afzender in een messages-gebeurtenis, uniek voor elke combinatie van persoon en Page.

Workplace only

Hoe de referentie van Meta het veld sender van een mention-gebeurtenis markeert.

No history

Eerdere webhookmeldingen kunnen later niet meer worden opgevraagd, dus een ontvanger moet opslaan wat hij nodig heeft.

Wat stuurt het veld messages?

Een melding wanneer iemand de Page een Messenger-bericht stuurt. Meta stuurt tekstberichten of berichten met bijlagen, die onder andere afbeeldingen, audio, video, bestanden of stickers kunnen zijn, en een gedeelde link kan binnenkomen als terugvalbijlage. Een antwoord op een eerder bericht bevat reply_to met de mid van dat bericht, en een quick reply bevat zijn payload.

Hoe ziet een messages-gebeurtenis eruit?

Anders dan feed-wijzigingen komt een bericht binnen in een messaging-array binnen de entry van de Page. Elke gebeurtenis heeft sender, de Page-scoped ID van de persoon; recipient, de Page; een tijdstempel; en message, met zijn mid en text, of attachments met een type en een payload-URL:

A messages event, as Meta sends it
{
  "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!"
          }
        }
      ]
    }
  ]
}

Wat stuurt het veld mention?

Een wijziging met veld mention wanneer de Page wordt vermeld in een post of reactie, met post_id of comment_id, de message, eventuele link, foto of video, en item en verb. Meta waarschuwt dat sommige van die post- en reactie-ID's niet kunnen worden opgevraagd, wegens ontbrekende toestemming of privacy, en de referentie markeert het veld sender alleen voor Workplace, dus een vermelding kan binnenkomen zonder zijn auteur.

Welke Messenger-velden worden niet doorgestuurd?

easyCoexistence abonneert Pages op messages, niet op message_echoes, messaging_postbacks, message_reads of message_deliveries. Berichten die de Page verstuurt, knopklikken en lees- of bezorgbevestigingen worden dus niet doorgestuurd. Een antwoord dat je stuurt met send_social_dm geeft in plaats daarvan zijn eigen bericht-ID terug.

Hoe bereiken gebeurtenissen je endpoint?

Meta levert Page-webhooks aan de app die de Page heeft geïnstalleerd, via één callback-URL voor de hele app. easyCoexistence controleert de X-Hub-Signature-256 van Meta bij elke levering, antwoordt Meta meteen en stuurt elke entry voor een verbonden Page door naar het HTTPS-endpoint dat jij ervoor instelt, ondertekend met het eigen geheim van die Page. Stel dit in met set_social_webhook_destination vanuit Claude of ChatGPT, of met PUT /channels/:id/webhook op de Partner API; het geheim wordt één keer getoond, opnieuw instellen geeft een nieuw geheim, en een null-URL schakelt het doorsturen uit.

Hoe ziet een doorgestuurde gebeurtenis eruit?

Een POST met het platform, de account_id die list_social_accounts geeft voor de verbinding van de Page, de ID van de Page als external_id, en entry: de entry van Meta voor de Page, ongewijzigd. sender.id is de recipient_id die send_social_dm gebruikt voor een antwoord binnen het venster van 24 uur:

A forwarded messages event
{
  "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>" }
      }
    ]
  }
}

Hoe verifieer je een doorgestuurde gebeurtenis?

Elke doorgestuurde POST bevat een X-EC-Signature-header in de vorm t=<unix>,v1=<hex>, waarbij v1 de HMAC-SHA256 is van het tijdstempel, een punt en de ruwe body, gesleuteld met het ondertekeningsgeheim van de Page. Bereken hem over de body precies zoals ontvangen, vergelijk in constante tijd, en wijs een tijdstempel af dat ouder is dan 5 minuten.

Node.js: verifying X-EC-Signature
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));
}

Wordt een levering opnieuw geprobeerd?

Niet door easyCoexistence. Elke entry wordt één keer doorgestuurd, in het geheugen, zonder kopie om opnieuw van te proberen; de doorstuur wacht 8 seconden op een antwoord, volgt geen redirects en gaat alleen naar een HTTPS-adres dat naar een publiek IP-adres verwijst. Meta merkt op dat eerdere meldingen later niet meer kunnen worden opgevraagd, dus sla op wat je nodig hebt zodra het binnenkomt. Stroomopwaarts probeert Meta een mislukte levering meteen enkele keren opnieuw, dus hetzelfde bericht kan af en toe twee keer bij je aankomen: dedupliceer op de mid.

Veelgemaakte fouten

  • Het werk doen voordat je antwoordt. Doorsturen probeert niet opnieuw, dus geef meteen een 2xx terug en verwerk de gebeurtenis daarna.
  • De handtekening verifiëren op geparste JSON. Bereken de HMAC over de ruwe body precies zoals die binnenkwam.
  • Ervan uitgaan dat een bericht altijd tekst heeft. Een sticker, afbeelding of gedeelde link komt binnen als attachments, zonder tekstveld.
  • Deduplicatie overslaan. Meta kan een gebeurtenis na een fout opnieuw leveren, dus sleutel op de mid van het bericht voordat je handelt.
Dit doen met EasyCoexistence

Zet doorsturen aan met set_social_webhook_destination of de Partner API. US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met de eerste 3 dagen gratis.

Veelgestelde vragen

Welke webhookvelden abonneert easyCoexistence een Page op?

messages voor Messenger en mention voor vermeldingen, naast feed voor de posts en reacties van de Page.

Komt een Messenger-sticker of afbeelding met tekst?

Nee. Een sticker, afbeelding of gedeelde link komt binnen in attachments, elk met een type en een payload-URL, en het bericht heeft geen tekstveld.

Hoe snel moet een Messenger-webhookendpoint antwoorden?

Met 200 OK binnen 5 seconden. Na 1 uur met mislukte leveringen heft Meta de koppeling van de app met de webhooks van de Page op.

Hoe beantwoord ik een doorgestuurd bericht?

Roep send_social_dm aan met de sender.id uit de gebeurtenis als recipient_id, binnen 24 uur na het bericht van de persoon.

Lees verder

Koppel je eerste kanaal in twee minuten.

Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.

  • 3 dagen gratis
  • Op elk moment opzegbaar
  • Alleen officiële API's
  • 24/7 bewaakt

Geverifieerd op