Webhook di Meta per la Piattaforma Messenger

Webhooks di Meta ti consente di ricevere notifiche HTTP in tempo reale relative a modifiche a oggetti specifici nel social graph di Meta. Ad esempio, potremmo inviarti una notifica quando una persona invia un messaggio alla tua Pagina Facebook o al tuo account Instagram per professionisti. Le notifiche webhook ti consentono di monitorare i messaggi in arrivo e gli aggiornamenti di stato dei messaggi. Le notifiche webhook ti consentono inoltre di evitare i rate limiting che si verificherebbero se eseguissi query sugli endpoint della Piattaforma Messenger per il monitoraggio di queste modifiche.

Per implementare correttamente i webhook per le conversazioni su Messenger o Instagram dovrai eseguire le seguenti operazioni:

1. Creazione di un endpoint sul server per ricevere ed elaborare le notifiche webhook e degli oggetti JSON
2. Configurazione del prodotto Webhooks di Meta nella Dashboard gestione app della tua app
3. Attivazione dell'iscrizione alle notifiche di Webhooks di Meta che desideri ricevere
4. Installazione dell'app di messaggistica sulla Pagina Facebook collegata alla tua azienda o al tuo account Instagram per professionisti

Prima di iniziare

Prima di iniziare, presupponiamo che tu abbia effettuato la seguente operazione:

• Lettura e implementazione dei componenti necessari per lo sviluppo con Meta nella Panoramica sulla piattaforma Messenger

Configurazione del server Node.js

Il server deve essere in grado di elaborare due tipi di richieste HTTPS: Richieste di verifica e Notifiche per l'evento. Poiché entrambe le richieste utilizzano HTTPS, il server deve disporre di un certificato TLS o SSL valido configurato e installato in modo corretto. I certificati autofirmati non sono supportati.

Le sezioni seguenti spiegano quali elementi saranno inclusi in ogni tipo di richiesta e come rispondere.

Gli esempi di codice mostrati in questa pagina provengono dalla nostra app di esempio su GitHub . Visita GitHub per vedere l'esempio completo e trovare ulteriori informazioni sulla configurazione del server per i webhook.

Creazione di un endpoint

Per creare un endpoint con cui ricevere le notifiche dei webhook dalla Piattaforma Messenger, il file app.js dovrebbe avere un aspetto simile al seguente:

// Create the endpoint for your webhook

app.post("/webhook", (req, res) => {
  let body = req.body;

  console.log(`\u{1F7EA} Received webhook:`);
  console.dir(body, { depth: null });
    
...
   

Il codice crea un endpoint /webhook che accetta richieste POST e verifica che siano notifiche dei webhook.

Restituzione di una risposta 200 OK

L'endpoint deve restituire una risposta 200 OK, che indica alla Piattaforma Messenger che l'evento è stato ricevuto e non deve essere inviato nuovamente. Di solito, non invierai questa risposta fino al completamento dell'elaborazione della notifica.

Risposta a notifiche per l'evento

L'endpoint dovrebbe rispondere a tutte le notifiche:

• con una risposta 200 OK HTTPS;
• entro al massimo 5 secondi.

In app.post all'interno del file app.js dovresti trovare un codice simile al seguente:

...
  // Send a 200 OK response if this is a page webhook

  if (body.object === "page") {
    // Returns a '200 OK' response to all requests
    res.status(200).send("EVENT_RECEIVED");
...
    // Determine which webhooks were triggered and get sender PSIDs and locale, message content and more.
...
  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
}); 

Richieste di verifica

Ogni volta che configuri il prodotto Webhooks nella Dashboard gestione app, verrà inviata una richiesta GET all'URL dell'endpoint. Le richieste di verifica includono i seguenti parametri della stringa della query, aggiunti alla fine dell'URL dell'endpoint. Tali parametri saranno simili ai seguenti:

Esempio di richiesta di verifica

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444

Convalida delle richieste di verifica

Ogni volta che l'endpoint riceve una richiesta di verifica, deve:

• verificare che il valore hub.verify_token corrisponda alla stringa impostata nel campo Token di verifica quando configuri il prodotto Webhooks nella Dashboard gestione app (non hai ancora impostato questa stringa del token);
• rispondere con il valore hub.challenge.

Il file app.js dovrebbe essere simile al seguente:

// Add support for GET requests to our webhook
app.get("/messaging-webhook", (req, res) => {
  
// Parse the query params
  let mode = req.query["hub.mode"];
  let token = req.query["hub.verify_token"];
  let challenge = req.query["hub.challenge"];

  // Check if a token and mode is in the query string of the request
  if (mode && token) {
    // Check the mode and token sent is correct
    if (mode === "subscribe" && token === config.verifyToken) {
      // Respond with the challenge token from the request
      console.log("WEBHOOK_VERIFIED");
      res.status(200).send(challenge);
    } else {
      // Respond with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
});

Nota:PHP converte i punti (.) in trattini bassi (_) nei nomi dei parametri .

Se ti trovi nella Dashboard gestione app e stai configurando il prodotto Webhooks (e quindi attivi una richiesta di verifica), la dashboard indicherà se l'endpoint ha convalidato la richiesta in modo corretto. Se stai utilizzando l'endpoint /app/subscriptions dell'API Graph per la configurazione del prodotto Webhooks, l'API indicherà con una risposta se l'azione è stata eseguita correttamente o meno.

Notifiche per l'evento

Quando configuri il tuo prodotto Webhooks, attiverai l'iscrizione a fields specifici su un tipo di object (ad esempio, il campo messages sull'oggetto page). Ogni volta che modifichi uno di questi campi, invieremo all'endpoint una richiesta POST con un payload JSON che descrive la modifica.

Ad esempio, se hai attivato l'iscrizione per il campo message_reactions dell'oggetto page e un cliente ha aggiunto una reazione a un messaggio inviato dall'app, ti verrà inviata una richiesta POST simile alla seguente:

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },

          ...
        }
      ]
    }
  ]
}

Contenuto del payload

I payload conterranno un oggetto che descrive la modifica. Quando configuri il prodotto Webhooks, puoi indicare se i payload devono contenere solo i nomi dei campi modificati o se i payload devono includere anche i nuovi valori.

Tutti i payload vengono formattati con JSON, quindi puoi analizzare il payload utilizzando i metodi o i pacchetti di analisi comuni JSON.

Convalida dei payload

Tutti i payload di notifica per l'evento vengono firmati con una firma SHA256 e includono la firma nell'intestazione "X-Hub-Signature-256" della richiesta, preceduta da "sha256=". Non è necessaria la convalida del payload, ma dovresti eseguirla e te lo consigliamo vivamente.

Per convalidare il payload:

1. Genera una firma SHA1 utilizzando il payload e la chiave segreta dell'app.
2. Confronta la tua firma con quella presente nell'intestazione X-Hub-Signature-256 (tutto ciò che si trova dopo sha256=). Se le firme corrispondono, il payload è autentico.

Il file app.js dovrebbe essere simile al seguente:

// Import dependencies and set up http server
const express = require("express"),
  bodyParser = require("body-parser"),
  { urlencoded, json } = require("body-parser"),
  app = express().use(bodyParser.json());
    
    ...


// Verify that the callback came from Facebook.
function verifyRequestSignature(req, res, buf) {
  var signature = req.headers["x-hub-signature-256"];

  if (!signature) {
    console.warn(`Couldn't find "x-hub-signature-256" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.appSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Couldn't validate the request signature.");
    }
  }
}

Nuovo tentativo di consegna dei webhook

Se una notifica inviata al server non va a buon fine, proveremo immediatamente altre volte. In questi casi, il tuo server deve gestire la deduplicazione. Se, dopo 15 minuti, non siamo ancora in grado di consegnare le notifiche, viene inviato un avviso al tuo account sviluppatore.

Se la consegna di una notifica continua a non andare a buon fine per 1 ora, riceverai un avviso che indica Iscrizione Webhooks disabilitata e per l'app verrà annullata l'iscrizione al webhook per la Pagina o per l'account Instagram per professionisti. Dopo aver corretto i problemi, dovrai attivare nuovamente l'iscrizione per i webhook.

Test dei webhook

Per testare la verifica dei webhook, esegui la seguente richiesta cURL con il token di verifica:

curl -X GET "localhost:1337/webhook?hub.verify_token=YOUR-VERIFY-TOKEN&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

Se la verifica del token funziona come previsto, dovresti visualizzare quanto segue:

• WEBHOOK_VERIFIED registrato nella riga di comando in cui è in esecuzione il processo del nodo.
• CHALLENGE_ACCEPTED registrato nella riga di comando in cui hai inviato la richiesta cURL.

Testa il webhook inviando la seguente richiesta cURL:

curl -H "Content-Type: application/json" -X POST "localhost:1337/webhook" -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

Se il webhook funziona come previsto, dovresti visualizzare quanto segue:

• TEST_MESSAGE registrato nella riga di comando in cui è in esecuzione il processo del nodo.
• EVENT RECEIVED registrato nella riga di comando in cui hai inviato la richiesta cURL.

Iscrizione a Webhooks di Meta

Quando l'endpoint del server dei webhook o l'app di esempio saranno pronti, utilizza la Dashboard gestione app della tua app per effettuare l'iscrizione a Webhooks di Meta.

In questo esempio, utilizzeremo la dashboard per configurare un webhook e attivare l'iscrizione al campo messages. Ogni volta che un cliente invia un messaggio all'app, verrà inviata una notifica all'endpoint webhooks.

1. Nella Dashboard gestione app, accedi a Prodotti > Messenger > Impostazioni.
   • Alcuni webhook della Piattaforma Messenger non sono disponibili per i messaggi di Instagram. Se implementi solo webhook per Instagram e conosci i webhook disponibili per i messaggi di Instagram, puoi effettuare l'iscrizione ai webhook qui. Per visualizzare e iscriverti solo ai webhook per i messaggi di Instagram, vai alle impostazioni di Instagram.

2. Inserisci l'URL dell'endpoint nel campo URL di callback e aggiungi un token di verifica al campo Token di verifica. Questa stringa verrà inclusa in tutte le richieste di verifica. Se stai usando una delle nostre app di esempio, questa dovrebbe essere la stessa stringa utilizzata per la variabile di configurazione TOKEN dell'app.

3. Attiva l'iscrizione per i campi per cui vorresti inviare notifiche e clicca su Salva.

4. L'ultimo passaggio consiste nell'attivare l'iscrizione per i singoli campi. Attiva l'iscrizione per il campo messages e invia una notifica per l'evento di prova.

   Se l'endpoint è stato configurato correttamente, dovrebbe convalidare il payload ed eseguire qualsiasi codice configurato in caso di convalida eseguita correttamente. Se stai utilizzando la nostra app di esempio, carica l'URL dell'app nel browser web. Dovrebbe visualizzare i contenuti del payload.

Puoi modificare le iscrizioni per i webhook, il token di verifica o la versione dell'API in qualsiasi momento utilizzando la Dashboard gestione app.

Nota: consigliamo di usare l'ultima versione dell'API per ricevere tutte le informazioni disponibili per ciascun webhook.

Puoi anche eseguire la stessa operazione in modo programmatico usando l'endpoint /app/subscriptions.

Campi della Piattaforma Messenger disponibili

Collegamento dell'app

Dovrai collegare l'app dei webhook alla Pagina e attivare l'iscrizione per la Pagina alle notifiche dei webhook che desideri ricevere.

Aggiunta dell'app

Puoi collegare un'app a una Pagina in Meta Business Suite > Risorse business > Tutti gli strumenti > App business

Nota: dovrai attivare l'iscrizione ai webhook dei messaggi per tutte le app di messaggistica della tua azienda.

Attivazione dell'iscrizione per la Pagina

Dovrai attivare l'iscrizione per la Pagina alle notifiche dei webhook che desideri ricevere.

Requisiti

• Un token d'accesso della Pagina richiesto da una persona che può eseguire l'attività MODERATE sulla Pagina interrogata
• Le autorizzazioni pages_messaging e pages_manage_metadata

Per attivare l'iscrizione a un campo Webhooks, invia una richiesta POST al segmento subscribed_apps della Pagina usando il token d'accesso della Pagina.

curl -i -X POST "https://graph.facebook.com/PAGE-ID/subscribed_apps
  ?subscribed_fields=messages
  &access_token=PAGE-ACCESS-TOKEN"

Esempio di risposta

{
  "success": "true"
}

Per vedere quale app è stata installata dalla tua Pagina, invia una richiesta GET:

Esempio di richiesta

curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps
  &access_token=PAGE-ACCESS-TOKEN"

Esempio di risposta

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "APP-ID"
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

Se la tua Pagina non ha installato nessuna app, l'API restituirà un set di dati vuoto.

Tool di esplorazione per la API Graph

Puoi usare anche il Tool di esplorazione per la API Graph per inviare la richiesta di attivazione dell'iscrizione per la tua Pagina a un campo Webhooks.

1. Seleziona la tua app nel menu a discesa App.
2. Clicca sul menu a discesa Ricevi token e seleziona Ricevi token d'accesso dell'utente, quindi scegli l'autorizzazione pages_manage_metadata. Questa operazione sostituirà il tuo token dell'app con un token d'accesso utente che dispone dell'autorizzazione pages_manage_metadata.
3. Clicca di nuovo su Ricevi token e seleziona la tua Pagina. Questa operazione sostituirà il tuo token d'accesso utente con un token d'accesso della Pagina.
4. Modifica il metodo di funzionamento cliccando sul menu a discesa GET e selezionando POST.
5. Sostituisci la query me?fields=id,name predefinita con l'id della Pagina seguito da /subscribed_apps, quindi invia la query.

Requisiti di l'accesso

Per ricevere notifiche dalle persone che ricoprono un ruolo nella tua app, come gli amministratori, gli sviluppatori o i tester, l'app necessita solo dell'accesso standard. Per ricevere notifiche dai clienti, ovvero persone che non ricoprono un ruolo nella tua app, l'app necessita dell'accesso avanzato.

Scopri di più sull' accesso standard e avanzato , sui dati accessibili con ciascuno e sui requisiti per l'implementazione.

Passaggi successivi

Visita la nostra app di esempio - Scarica il codice per la nostra app di esempio per scoprire di più sulle funzionalità disponibili sulla Piattaforma Messenger.

Altri contenuti da consultare

• Scopri come ricevere notifiche quando una conversazione viene passata da un'app all'altra utilizzando il protocollo di consegna di Messenger.
• Scopri di più sul prodotto Webhooks di Meta per l'API Graph.