AccediInizia la prova gratuita
easyCoexistence API ufficiali

Webhook Messenger per le Pagine Facebook: messaggi ed eventi di menzione

Il campo messages dei webhook di Pagina di Facebook si attiva quando una persona invia alla Pagina un messaggio Messenger, consegnando un array messaging con l'ID con ambito Pagina del mittente, l'ID della Pagina, un timestamp e il mid del messaggio con il suo testo o i suoi allegati. Il campo mention segnala le nuove menzioni della Pagina in post e commenti, e Meta firma entrambi con X-Hub-Signature-256.

easyCoexistence inoltra i messaggi e le menzioni Messenger di ogni Pagina connessa al tuo endpoint HTTPS appena arrivano, firmati con un segreto per quella Pagina e senza conservare copie, e send_social_dm risponde entro la finestra di 24 ore.

5 seconds

Quanto rapidamente Meta chiede a un endpoint webhook di Messenger di rispondere con 200 OK a ogni notifica.

1 hour

Se le consegne falliscono per questo periodo, Meta annulla l'iscrizione dell'app ai webhook della Pagina finché non si iscrive di nuovo.

PSID

L'ID con ambito Pagina del mittente in un evento messages, unico per ogni coppia persona e Pagina.

Workplace only

Come il riferimento di Meta indica il campo sender di un evento mention.

No history

Le notifiche webhook passate non possono essere interrogate in seguito, quindi chi riceve deve memorizzare ciò che serve.

Cosa invia il campo messages?

Una notifica quando una persona invia alla Pagina un messaggio Messenger. Meta invia messaggi di testo o messaggi con allegati, che possono essere immagini, audio, video, file o sticker, tra altri tipi, e un link condiviso può arrivare come allegato di ripiego. Una risposta a un messaggio precedente contiene reply_to con il mid di quel messaggio, e una risposta rapida contiene il suo payload.

Come appare un evento messages?

A differenza delle modifiche al feed, un messaggio arriva in un array messaging all'interno di entry della Pagina. Ogni evento ha sender, l'ID con ambito Pagina della persona; recipient, la Pagina; un timestamp; e message, con il suo mid e testo, oppure attachments con un type e un URL di 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!"
          }
        }
      ]
    }
  ]
}

Cosa invia il campo mention?

Una modifica con field mention quando la Pagina viene menzionata in un post o in un commento, con post_id o comment_id, il campo message, eventuali link, foto o video, e item e verb. Meta avverte che alcuni di quegli ID di post e commento non possono essere interrogati, per mancanza di autorizzazione o per motivi di privacy, e il suo riferimento indica che il campo sender vale solo per Workplace, quindi una menzione può arrivare senza il suo autore.

Quali campi Messenger non vengono inoltrati?

easyCoexistence iscrive le Pagine a messages, non a message_echoes, messaging_postbacks, message_reads o message_deliveries, quindi i messaggi inviati dalla Pagina, i tocchi sui pulsanti e le ricevute di lettura o consegna non vengono inoltrati. Una risposta inviata con send_social_dm restituisce invece il proprio ID messaggio.

Come arrivano gli eventi al tuo endpoint?

Meta consegna i webhook di Pagina all'app che la Pagina ha installato, attraverso un unico URL di callback per l'intera app. easyCoexistence verifica X-Hub-Signature-256 di Meta su ogni consegna, risponde subito a Meta e inoltra ogni entry di una Pagina connessa all'endpoint HTTPS che hai impostato per essa, firmato con il segreto proprio di quella Pagina. Impostalo con set_social_webhook_destination da Claude o ChatGPT, oppure con PUT /channels/:id/webhook sulla Partner API; il segreto viene mostrato una sola volta, reimpostarlo ne emette uno nuovo, e un URL null disattiva l'inoltro.

Come appare un evento inoltrato?

Un POST che contiene la piattaforma, l'account_id che list_social_accounts restituisce per la connessione della Pagina, l'ID della Pagina come external_id, e l'entry: l'entry di Meta per la Pagina, invariata. sender.id è il recipient_id che send_social_dm richiede per una risposta entro la finestra di 24 ore:

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

Come verifichi un evento inoltrato?

Ogni POST inoltrato contiene l'intestazione X-EC-Signature nella forma t=<unix>,v1=<hex>, dove v1 è l'HMAC-SHA256 del timestamp, di un punto e del corpo grezzo, con chiave il segreto di firma della Pagina. Calcolalo sul corpo grezzo esattamente come ricevuto, confronta in tempo costante e rifiuta un timestamp più vecchio di 5 minuti.

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

Una consegna viene ritentata?

Non da easyCoexistence. Ogni entry viene inoltrata una sola volta, in memoria, senza copia da cui riprovare; l'inoltro attende 8 secondi una risposta, non segue i reindirizzamenti e va solo a un indirizzo HTTPS che risolve in un IP pubblico. Meta fa notare che le notifiche passate non possono essere interrogate in seguito, quindi memorizza ciò che ti serve appena arriva. A monte, Meta ritenta una consegna fallita più volte di seguito, quindi lo stesso messaggio può occasionalmente arrivarti due volte: deduplica in base al suo mid.

Errori comuni

  • Fare il lavoro prima di rispondere. L'inoltro non ritenta, quindi restituisci subito un 2xx ed elabora l'evento dopo.
  • Verificare la firma su JSON già analizzato. Calcola l'HMAC sul corpo grezzo esattamente come è arrivato.
  • Presumere che un messaggio abbia sempre un testo. Uno sticker, un'immagine o un link condiviso arriva come attachments, senza campo text.
  • Saltare la deduplicazione. Meta può consegnare di nuovo un evento dopo un errore, quindi usa il mid del messaggio come chiave prima di agire.
Farlo con EasyCoexistence

Attiva l'inoltro con set_social_webhook_destination o con la Partner API. Da US$ 9 a US$ 0,75 per connessione al mese, con calo man mano che aggiungi connessioni, e i primi 3 giorni di prova gratuita.

Domande frequenti

Quali campi webhook easyCoexistence iscrive una Pagina?

messages per Messenger e mention per le menzioni, insieme a feed per i post e i commenti della Pagina.

Uno sticker o un'immagine Messenger arriva con un testo?

No. Uno sticker, un'immagine o un link condiviso arriva in attachments, ciascuno con un type e un URL di payload, e il messaggio non contiene un campo text.

Con quale rapidità un endpoint webhook Messenger deve rispondere?

Con 200 OK entro 5 secondi. Dopo 1 ora di consegne fallite, Meta annulla l'iscrizione dell'app ai webhook della Pagina.

Come rispondo a un messaggio inoltrato?

Chiama send_social_dm con il sender.id dell'evento come recipient_id, entro 24 ore dal messaggio della persona.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il