Webhooks Meta pour la plateforme Messenger

Les webhooks Meta vous permettent de recevoir des notifications HTTP en temps réel relatives aux modifications apportées à des objets spécifiques du graphe social de Meta. Par exemple, nous pouvons vous envoyer une notification lorsqu’une personne envoie un message à votre page Facebook ou à votre compte professionnel Instagram. Les notifications de webhooks vous permet de suivre les messages entrants et les mises à jour apportées au statut des messages. Les notifications de webhooks vous permettent également d’éviter les plafonds susceptibles de s’appliquer lorsque vous interrogez les points de terminaison de la plateforme Messenger pour suivre ces modifications.

Pour réussir à implémenter des webhooks pour les conversations Messenger ou Instagram, vous devez :

1. Créer des objets JSON et un point de terminaison sur votre serveur pour recevoir et traiter les notifications de webhooks
2. Configurer le produit Webhooks Meta dans votre Espace App
3. Vous abonner aux notifications de Webhooks Meta que vous souhaitez recevoir
4. Installer votre application de messagerie sur la Page Facebook associée à votre compte business ou à votre compte professionnel Instagram

Avant de commencer

Avant toute chose, nous supposons que vous avez :

• pris connaissance et implémenté les composants nécessaires au développement sous Meta décrits dans la rubrique Présentation de la plateforme Messenger

Configurer votre serveur Node.JS

Votre serveur doit être capable de traiter deux types de requêtes HTTPS : Demandes de vérification et Notifications d’évènement. Comme les deux requêtes utilisent le protocole HTTPS, votre serveur doit disposer d’un certificat TLS ou SSL valide, correctement configuré et installé. Les certificats auto-signés ne sont pas pris en charge.

Les sections ci-dessous expliquent le contenu de chaque type de requête et comment y répondre.

Les exemples de codes présentés ici sont extraits de notre exemple d’application disponible sur GitHub . Accédez à GitHub si vous souhaitez consulter l’exemple complet et en savoir plus sur la configuration de votre serveur de webhooks.

Créer un point de terminaison

Pour créer un point de terminaison permettant de recevoir des notifications de webhooks de la plateforme Messenger, le fichier app.js doit ressembler à ceci :

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

Ce code crée un point de terminaison /webhook qui accepte les requêtes POST, vérifie que la requête correspond à un évènement webhook, puis analyse le message.

Renvoyer une réponse 200 OK

Notez que le point de terminaison doit renvoyer une réponse 200 OK pour indiquer à la plateforme Messenger que l’évènement a été reçu et n’a pas besoin d’être renvoyé. Normalement, vous n’enverrez pas cette réponse tant que vous n’aurez pas fini de traiter la notification.

Réponse à des notifications d’évènement

Votre point de terminaison doit répondre à toutes les notifications :

• avec une réponse 200 OK HTTPS ;
• en 5 secondes maximum.

Un code similaire au suivant se trouvera dans la section app.post de votre fichier app.js :

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

Demandes de vérification

À chaque fois que vous configurerez le produit Webhooks dans votre Espace App, nous enverrons une demande GET à l’URL de votre point de terminaison. Les demandes de vérification comprennent les paramètres de chaîne de requêtes suivants, ajoutés à la fin de votre URL de point de terminaison. Ils ressembleront à ceci :

Exemple de demande de vérification

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

Validation des demandes de vérification

Chaque fois que votre point de terminaison reçoit une demande de vérification, il doit :

• vérifier que la valeur hub.verify_token correspond à la chaîne que vous avez définie dans le champ Vérifier le token lorsque vous configurez le produit Webhooks dans votre Espace App (vous n’avez pas encore configuré cette chaîne de tokens) ;
• répondre avec la valeur hub.challenge.

Votre fichier app.js pourra ressembler à ce qui suit :

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

Remarque : PHP convertit les points (.) en traits de soulignement (_) dans les noms de paramètre .

Si vous êtes sur votre Espace App et que vous configurez votre produit Webhooks (et, par conséquent, déclenchez une demande de vérification), le tableau de bord indiquera si votre point de terminaison a validé la demande correctement. Si vous utilisez le point de terminaison /app/subscriptions de l’API Graph pour configurer le produit Webhooks, l’API indiquera la réussite ou l’échec avec une réponse.

Notifications d’évènement

Lorsque vous configurez votre produit Webhooks, vous vous abonnez à des fields spécifiques d’un type object (par exemple, le champ messages de l’objet page). À chaque modification de l’un de ces champs, nous enverrons à votre point de terminaison une demande POST avec une charge utile JSON décrivant la modification.

Par exemple, si vous vous abonnez au champ message_reactions de l’objet page et que l’un·e des utilisateurs ou utilisatrices de votre application a publié une photo, nous vous enverrons une demande POST qui ressemblerait à ceci :

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

          ...
        }
      ]
    }
  ]
}

Contenu de la charge utile

Les charges utiles contiendront un objet décrivant la modification. Lorsque vous configurez le produit Webhooks, vous pouvez indiquer si les charges utiles doivent uniquement contenir le nom des champs modifiés ou inclure aussi les nouvelles valeurs.

Nous formatons toutes les charges utiles avec JSON, afin que vous puissiez analyser la charge utile en utilisant des méthodes ou des packages d’analyse JSON courants.

Validation des charges utiles

Nous signons toutes les charges utiles de notification d’évènement avec une signature SHA256 et incluons cette signature dans l’en-tête « X-Hub-Signature-256 » de la demande, précédée de « sha256= ». La validation de la charge utile n’est pas obligatoire. Toutefois, nous vous recommandons vivement de le faire.

Pour valider la charge utile :

1. Générez une signature SHA256 utilisant la charge utile et la clé secrète de votre application.
2. Comparez votre signature à la signature dans l’en-tête X-Hub-Signature-256 (après sha256=). Si les signatures correspondent, la charge utile est authentique.

Votre fichier app.js pourra ressembler à ce qui suit :

// 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.");
    }
  }
}

Nouvelle tentative de distribution des webhooks

Si une notification envoyée à votre serveur échoue, nous effectuerons immédiatement d’autres tentatives. Dans de tels cas de figure, votre serveur devrait être capable de gérer la déduplication. Si après 15 minutes, nous ne parvenons toujours pas à distribuer des notifications, une alerte est envoyée à votre compte de développement.

Si la notification n’est toujours pas distribuée au bout d’une heure, vous recevrez une alerte Webhooks désactivé et votre application ne recevra plus d’évènements webhook pour la Page ou pour le compte professionnel Instagram. Une fois les problèmes résolus, vous devrez vous abonner de nouveau aux Webhooks.

Tester vos webhooks

Pour tester la vérification de votre webhook, exécutez la requête cURL suivante avec votre token de vérification :

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

Si la vérification de votre webhook fonctionne comme prévu, vous devriez voir les éléments suivants :

• WEBHOOK_VERIFIED consigné dans l’invite de commande où votre processus node s’exécute.
• CHALLENGE_ACCEPTED consigné dans l’invite de commande où vous avez envoyé la requête cURL.

Pour tester votre webhook, envoyez la requête cURL suivante :

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

Si votre webhook fonctionne comme prévu, vous devriez voir les éléments suivants :

• TEST_MESSAGE consigné dans l’invite de commande où votre processus node s’exécute.
• EVENT RECEIVED consigné dans l’invite de commande où vous avez envoyé la requête cURL.

S’abonner aux webhooks Meta

Une fois que le point de terminaison de votre serveur webhooks ou l’exemple d’application est prêt, allez dans le tableau de bord de votre application pour vous abonner aux webhooks Meta.

Dans cet exemple, nous utiliserons le tableau de bord pour configurer un webhook et nous abonner au champ messages. Chaque fois qu’un client ou une cliente envoie un message à votre application, une notification est envoyée à votre point de terminaison Webhooks.

1. Dans l’Espace App, accédez à Produits > Messenger > Paramètres.
   • Certains webhooks de la plateforme Messenger ne sont pas disponibles pour les messages Instagram. Si vous implémentez uniquement des webhooks pour Instagram et si vous connaissez les webhooks disponibles pour les messages Instagram, vous pouvez vous abonner aux webhooks ici. Si vous souhaitez uniquement visualiser les webhooks pour les messages Instagram et vous y abonner, accédez aux paramètres d’Instagram.

2. Saisissez l’URL de votre point de terminaison dans le champ URL de rappel et ajoutez votre token de vérification dans le champ Vérifier le token. Nous inclurons cette chaîne dans toutes les demandes de vérification. Si vous utilisez l’un de nos exemples d’application, il doit s’agir de la même chaîne que vous avez utilisée pour la variable de configuration TOKEN de votre application.

3. Abonnez-vous aux champs pour lesquels vous souhaitez recevoir des notifications, puis cliquez sur Enregistrer.

4. La dernière étape consiste à vous abonner à des champs individuels. Abonnez-vous au champ messages et envoyez une notification d’évènement de test.

   Si votre point de terminaison est configuré correctement, il devrait valider la charge utile et exécuter le code que vous avez défini lors de la validation. Si vous utilisez notre exemple d’application, chargez l’URL de l’application dans votre navigateur Web. Il devrait afficher le contenu de la charge utile.

Vous pouvez à tout moment modifier vos abonnements Webhooks, vérifier le token ou la version d’API à l’aide de l’Espace App.

Remarque : il est recommandé d’utiliser la dernière version d’API pour recevoir toutes les informations disponibles sur chaque webhook.

Vous pouvez aussi le faire dans le cadre d’un programme en utilisant le point de terminaison /app/subscriptions.

Champs disponibles sur la plateforme Messenger

Connecter votre application

Vous devrez connecter votre application Webhooks à votre Page et abonner votre Page aux notifications Webhooks que vous voulez recevoir.

Ajouter l’application

Vous pouvez connecter une application à une Page dans Meta Business Suite > Tous les outils > Applications Business

Remarque : vous devrez abonner toutes les applications de messagerie de votre entreprise aux webhooks de messages.

Abonner votre Page

Vous devrez abonner votre Page aux notifications Webhooks que vous voulez recevoir.

Conditions requises

• Un token d’accès de Page demandé par une personne autorisée à effectuer la tâche MODERATE sur la Page ciblée par la requête
• Les autorisations pages_messaging et pages_manage_metadata

Pour vous abonner à un champ Webhooks, envoyez une requête POST à l’arête subscribed_apps de la Page via le token d’accès de la Page.

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

Exemple de réponse

{
  "success": "true"
}

Pour connaître les applications installées sur votre Page, envoyez plutôt une requête GET :

Exemple de requête

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

Exemple de réponse

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

Si votre Page n’a installé aucune application, l’API renvoie un ensemble de données vide.

Explorateur de l’API Graph

Vous pouvez également utiliser l’Explorateur de l’API Graph pour envoyer la requête d’abonnement de votre Page à un champ Webhooks.

1. Sélectionnez votre application dans le menu déroulant Application.
2. Cliquez sur le menu déroulant Obtenir le token et sélectionnez Obtenir le token d’accès utilisateur·ice, puis choisissez l’autorisation pages_manage_metadata. Le token de votre application sera remplacé par un token d’accès utilisateur·ice avec l’autorisation pages_manage_metadata.
3. Cliquez à nouveau sur Obtenir le token et sélectionnez votre Page. Le token d’accès utilisateur·ice sera remplacé par un token d’accès de Page.
4. Cliquez sur le menu déroulant GET et sélectionnez POST pour changer de méthode de fonctionnement.
5. Remplacez la requête par défaut me?fields=id,name par l’ID de la Page, ajoutez /subscribed_apps, puis envoyez la requête.

Conditions d’accès

Pour recevoir des notifications de personnes qui ont un rôle sur votre application, telles que les admins, développeur·ses ou testeur·ses, votre application a besoin uniquement d’un accès de type Standard. Pour recevoir des notifications de vos client·es, de personnes qui n’ont aucun rôle sur votre application, cette dernière a besoin d’un accès de type Advanced Access.

En savoir plus sur les accès de type Standard et Advanced Access , les données accessibles avec chacun d’eux et les conditions d’implémentation.

Étapes suivantes

Découvrir notre exemple d’application  : téléchargez le code de notre exemple d’application pour en savoir plus sur les fonctionnalités offertes par la plateforme Messenger.

Voir aussi

• Découvrez comment recevoir des notifications lorsqu’une conversation est transmise d’une application à une autre grâce au protocole de transfert Messenger.
• En savoir plus sur Meta Webhooks pour l’API Graph