Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Webhook Messenger pour les Pages Facebook : messages et événements de mention

Le champ messages des webhooks de Pages Facebook se déclenche lorsqu'une personne envoie un message Messenger à la Page. Il livre un tableau messaging contenant l'ID de l'expéditeur propre à la Page, l'ID de la Page, un horodatage et le mid du message, avec son texte ou ses pièces jointes. Le champ mention signale les nouvelles mentions de la Page dans les publications et les commentaires, et Meta signe les deux avec X-Hub-Signature-256.

easyCoexistence transmet les messages Messenger et les mentions de chaque Page connectée vers votre endpoint HTTPS dès leur arrivée, signés avec un secret propre à cette Page et sans copie conservée, et send_social_dm répond dans la fenêtre de 24 heures.

5 seconds

Le délai dans lequel Meta attend d'un endpoint webhook Messenger une réponse 200 OK à chaque notification.

1 hour

Après un échec de livraison prolongé pendant cette durée, Meta désabonne l'application des webhooks de la Page jusqu'à un nouvel abonnement.

PSID

L'ID propre à la Page de l'expéditeur dans un événement messages, unique pour chaque couple personne et Page.

Workplace only

La façon dont la référence de Meta marque le champ sender d'un événement mention.

No history

Les notifications webhook passées ne peuvent pas être interrogées ensuite, donc le récepteur doit stocker ce dont il a besoin.

Que transmet le champ messages ?

Une notification lorsqu'une personne envoie un message Messenger à la Page. Meta envoie des messages texte ou des messages avec pièces jointes, qui peuvent être des images, des fichiers audio, des vidéos, des fichiers ou des stickers, entre autres types, et un lien partagé peut arriver sous forme de pièce jointe de secours. Une réponse à un message précédent contient reply_to avec le mid de ce message, et une réponse rapide contient son payload.

À quoi ressemble un événement messages ?

Contrairement aux modifications de feed, un message arrive dans un tableau messaging à l'intérieur de l'entry de la Page. Chaque événement contient sender, l'ID propre à la Page de la personne ; recipient, la Page ; un horodatage ; et message, avec son mid et son text, ou des attachments avec un type et une URL de payload :

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!"
          }
        }
      ]
    }
  ]
}

Que transmet le champ mention ?

Un changement dont le field est mention lorsque la Page est mentionnée dans une publication ou un commentaire, avec post_id ou comment_id, le message, tout lien, photo ou vidéo, ainsi que item et verb. Meta prévient que certains de ces ID de publication et de commentaire ne peuvent pas être interrogés, faute d'autorisation ou pour des raisons de confidentialité, et sa référence indique que le champ sender ne concerne que Workplace uniquement ; une mention peut donc arriver sans son auteur.

Quels champs Messenger ne sont pas transmis ?

easyCoexistence abonne les Pages à messages, et non à message_echoes, messaging_postbacks, message_reads ou message_deliveries ; les messages envoyés par la Page, les clics sur les boutons et les accusés de lecture ou de livraison ne sont donc pas transmis. Une réponse envoyée avec send_social_dm renvoie à la place son propre ID de message.

Comment les événements atteignent-ils votre endpoint ?

Meta livre les webhooks de Page à l'application que la Page a installée, par une seule URL de callback pour toute l'application. easyCoexistence vérifie le X-Hub-Signature-256 de Meta sur chaque livraison, répond immédiatement à Meta, et transmet chaque entry d'une Page connectée à l'endpoint HTTPS que vous avez défini pour elle, signé avec le secret propre à cette Page. Définissez-le avec set_social_webhook_destination depuis Claude ou ChatGPT, ou avec PUT /channels/:id/webhook sur la Partner API ; le secret n'est affiché qu'une fois, le redéfinir en génère un nouveau, et une URL null désactive la transmission.

À quoi ressemble un événement transmis ?

Un POST contenant platform, le account_id que list_social_accounts attribue à la connexion de la Page, l'ID de la Page comme external_id, et entry : l'entry de Meta pour la Page, inchangée. sender.id est le recipient_id que send_social_dm prend pour une réponse dans la fenêtre de 24 heures :

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>" }
      }
    ]
  }
}

Comment vérifier un événement transmis ?

Chaque POST transmis porte un en-tête X-EC-Signature au format t=<unix>,v1=<hex>, où v1 est le HMAC-SHA256 de l'horodatage, d'un point et du corps brut, avec pour clé le secret de signature de la Page. Calculez-le sur le corps exactement tel que reçu, comparez en temps constant, et rejetez tout horodatage vieux de plus de 5 minutes.

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));
}

Une livraison est-elle réessayée ?

Non, pas par easyCoexistence. Chaque entry est transmise une seule fois, en mémoire, sans copie conservée pour une nouvelle tentative ; la transmission attend 8 secondes une réponse, ne suit pas les redirections et ne va qu'à une adresse HTTPS qui résout vers une IP publique. Meta indique que les notifications passées ne peuvent pas être interrogées plus tard, donc stockez ce dont vous avez besoin dès réception. En amont, Meta réessaie une livraison en échec plusieurs fois de suite, si bien qu'un même message peut parfois vous parvenir deux fois : dédupliquez sur son mid.

Erreurs courantes

  • Faire le travail avant de répondre. La transmission ne réessaie pas, donc renvoyez immédiatement un 2xx et traitez l'événement ensuite.
  • Vérifier la signature sur du JSON déjà parsé. Calculez le HMAC sur le corps brut exactement tel qu'il est arrivé.
  • Supposer qu'un message contient toujours du texte. Un sticker, une image ou un lien partagé arrive dans attachments, sans champ text.
  • Ignorer la déduplication. Meta peut renvoyer un événement après un échec, donc indexez sur le mid du message avant d'agir.
Faire cela avec EasyCoexistence

Activez la transmission avec set_social_webhook_destination ou la Partner API. De US$ 9 à US$ 0,75 par connexion et par mois, en baisse à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.

Questions fréquemment posées

Quels champs webhook easyCoexistence abonne-t-il une Page ?

messages pour Messenger et mention pour les mentions, en plus de feed pour les publications et les commentaires de la Page.

Un sticker ou une image Messenger arrive-t-il avec du texte ?

Non. Un sticker, une image ou un lien partagé arrive dans attachments, chacun avec un type et une URL de payload, et le message ne contient pas de champ text.

En combien de temps un endpoint webhook Messenger doit-il répondre ?

Avec 200 OK dans un délai de 5 secondes. Après 1 heure d'échecs de livraison, Meta désabonne l'application des webhooks de la Page.

Comment répondre à un message transmis ?

Appelez send_social_dm avec le sender.id de l'événement comme recipient_id, dans les 24 heures suivant le message de la personne.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le