Tutoriel de démarrage rapide

Si vous ne l’avez pas encore fait, suivez notre guide de configuration des applications pour configurer votre application Facebook afin de l’utiliser avec la plateforme Messenger.

Toutes les requêtes destinées aux API de la plateforme Messenger sont authentifiées grâce à l’ajout d’un token d’accès de niveau page au paramètre access_token de la chaîne de requête.

Si vous ne l’avez pas déjà fait lorsque vous avez configuré votre application Facebook, générez un token d’accès de Page en procédant comme suit :

Il est conseillé de protéger les informations confidentielles comme votre token d’accès de Page en évitant de les coder en dur dans votre webhook.

Pour ce faire, ajoutez le code suivant à vos variables d’environnement, où <PAGE_ACCESS_TOKEN> représente le token d’accès que vous venez de générer et <VERIFY_TOKEN> une chaîne de votre choix servant à vérifier votre webhook :

PAGE_ACCESS_TOKEN="

Il ne vous reste plus qu’à ajouter votre token d’accès de Page et votre token de vérification en haut du fichier app.js afin de les utiliser dans la logique de votre webhook :

const PAGE_ACCESS_TOKEN = process.env.PAGE_ACCESS_TOKEN;
const VERIFY_TOKEN = process.env.VERIFY_TOKEN;

Pour commencer, nous allons définir trois fonctions qui géreront les types d’évènement webhook entrants que nous souhaitons prendre en charge ainsi que l’envoi de réponses via l’API Send. Pour ce faire, ajoutez le code suivant à votre fichier app.js :

// Handles messages events
function handleMessage(sender_psid, received_message) {

}

// Handles messaging_postbacks events
function handlePostback(sender_psid, received_postback) {

}

// Sends response messages via the Send API
function callSendAPI(sender_psid, response) {
  
}

Pour répondre aux personnes sur Messenger, il est d’abord nécessaire de savoir qui elles sont. Dans Messenger, l’opération s’effectue en obtenant l’ID de Page (PSID) de l’expéditeur·trice du message à partir de l’évènement webhook entrant.

Qu’est-ce qu’un PSID ?

Un ID de Page (PSID) unique est attribué à une personne pour chaque Page Facebook avec laquelle elle démarre une conversation. Le PSID permet d’identifier une personne lorsqu’elle envoie des messages.

Si vous avez suivi l’une des procédures de la section Projet de départ ci-dessus, vous devez avoir un point de terminaison /webhook de base qui accepte les requêtes POST et consigne le corps des évènements webhook reçus ressemblant à ceci :

app.post('/webhook', (req, res) => {  

  // Parse the request body from the POST
  let body = req.body;

  // Check the webhook event is from a Page subscription
  if (body.object === 'page') {

    // Iterate over each entry - there may be multiple if batched
    body.entry.forEach(function(entry) {

      // Get the webhook event. entry.messaging is an array, but 
      // will only ever contain one event, so we get index 0
      let webhook_event = entry.messaging[0];
      console.log(webhook_event);
      
    });

    // Return a '200 OK' response to all events
    res.status(200).send('EVENT_RECEIVED');

  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }

});

Pour obtenir le PSID de l’expéditeur·trice, mettez à jour le bloc body.entry.forEach en utilisant le code suivant afin d’extraire le PSID de la propriété sender.id de l’évènement :

Nous voulons que notre expérience puisse gérer deux types d’évènements webhook : messages et messaging_postback. Le nom du type d’évènement ne figure pas dans le corps de l’évènement, mais nous pouvons l’identifier en vérifiant certaines propriétés d’objet.

En quoi consistent les évènements webhook ?

La plateforme Messenger envoie des évènements webhook pour vous avertir des actions qui se produisent dans Messenger. Les évènements sont envoyés au format JSON sous forme de requêtes POST à votre webhook. Pour en savoir plus, consultez la page Évènements webhook.

Pour ce faire, mettez à jour le bloc body.entry.forEach de votre webhook à l’aide d’une instruction conditionnelle qui vérifie si l’évènement reçu contient une propriété message ou postback. Nous ajouterons aussi des appels aux fonctions handleMessage() et handlePostback() que nous avons définies plus tôt :

body.entry.forEach(function(entry) {

  // Gets the body of the webhook event
  let webhook_event = entry.messaging[0];
  console.log(webhook_event);


  // Get the sender PSID
  let sender_psid = webhook_event.sender.id;
  console.log('Sender PSID: ' + sender_psid);

  // Check if the event is a message or postback and
  // pass the event to the appropriate handler function
  if (webhook_event.message) {
    handleMessage(sender_psid, webhook_event.message);        
  } else if (webhook_event.postback) {
    handlePostback(sender_psid, webhook_event.postback);
  }
  
});

Maintenant que nos messages entrants sont transférés à la fonction appropriée du gestionnaire, nous allons mettre à jour handleMessage() pour gérer les textos de base et y répondre. Pour ce faire, mettez à jour le code pour définir la charge utile de notre réponse et transférer ces données à callSendAPI(). Nous voulons répondre par un texto de base et, pour ce faire, nous définissons un objet JSON avec une propriété "text" :

function handleMessage(sender_psid, received_message) {

  let response;

  // Check if the message contains text
  if (received_message.text) {    

    // Create the payload for a basic text message
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an image!`
    }
  }  
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Le moment est venu d’envoyer votre premier message avec l’API Send de la plateforme Messenger !

Dans handleMessage(), nous appelons callSendAPI(). Nous devons donc le mettre à jour pour créer le corps de la requête en entier et l’envoyer à la plateforme Messenger. Une requête envoyée à l’API Send contient deux propriétés :

• recipient : définit le ou la destinataire du message. Dans ce cas, nous identifions la personne grâce à son PSID.
• message : définit les détails du message à envoyer. Dans cet exemple, nous le définissons dans l’objet du message, que nous avons récupéré à partir de notre fonction handleMessage().

Pour créer le corps de la requête, mettez à jour le stub de callSendAPI() en utilisant le code suivant :

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }
}

Tout ce qu’il nous reste à faire est d’envoyer le message en envoyant une requête POST à l’API Send sur https://graph.facebook.com/v2.6/me/messages.

Notez que vous devez ajouter votre PAGE_ACCESS_TOKEN dans le paramètre access_token de la chaîne de requête de l’URL.

const request = require('request');

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }

  // Send the HTTP request to the Messenger Platform
  request({
    "uri": "https://graph.facebook.com/v2.6/me/messages",
    "qs": { "access_token": process.env.PAGE_ACCESS_TOKEN },
    "method": "POST",
    "json": request_body
  }, (err, res, body) => {
    if (!err) {
      console.log('message sent!')
    } else {
      console.error("Unable to send message:" + err);
    }
  }); 
}

Testez-le !

Dans Messenger, envoyez un autre texto à votre Page Facebook. Vous devriez recevoir une réponse automatique de votre expérience Messenger qui reprend votre message et vous invite à envoyer une image.

Étant donné que notre réponse invite le ou la destinataire du message à envoyer une image, l’étape suivante consiste à mettre à jour le code pour gérer une pièce jointe. Les pièces jointes envoyées sont automatiquement enregistrées par la plateforme Messenger et accessibles via une URL dans la propriété payload.url de chaque index de l’ensemble attachments. Nous devons donc également l’extraire de l’évènement.

Quels types de pièces jointes sont pris en charge ?

Votre expérience Messenger peut envoyer et recevoir la plupart des types d’éléments, notamment des images, de l’audio, des vidéos et des fichiers. Le contenu multimédia s’affiche et peut même être lu dans la conversation, vous permettant de créer des expériences enrichies.

Afin de déterminer si le message est une pièce jointe, mettez à jour l’instruction conditionnelle dans votre fonction handleMessage() pour vérifier le received_message d’une propriété attachments, puis extrayez l’URL. Dans un véritable bot, nous répéterions l’ensemble pour rechercher des pièces jointes multiples, mais pour les besoins de ce tutoriel de démarrage rapide, nous nous concentrons sur la première pièce jointe.

function handleMessage(sender_psid, received_message) {

  let response;

  // Checks if the message contains text
  if (received_message.text) {
    
    // Creates the payload for a basic text message, which
    // will be added to the body of our request to the Send API
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an attachment!`
    }

  } else if (received_message.attachments) {
  
    // Gets the URL of the message attachment
    let attachment_url = received_message.attachments[0].payload.url;
  
  } 
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Ensuite, nous répondons à l’image par un modèle générique de message. Le modèle générique est le type de message structuré le plus utilisé. Il vous permet d’envoyer une image, du texte et des boutons dans un message.

Existe-t-il d’autres modèles de message ?

Oui ! La plateforme Messenger fournit un ensemble de modèles de message utiles, chacun ayant été conçu pour prendre en charge un message structuré courant spécifique, comme les listes, les reçus, les boutons et bien plus encore. Pour des détails complets, consultez la page Modèles.

Les modèles de message sont définis dans la propriété attachment du message, qui contient les propriétés type et payload. C’est dans payload que nous configurons les détails de notre modèle générique, dans les propriétés suivantes :

• template_type : définit le type de modèle utilisé pour le message. Nous utilisons le modèle générique, de ce fait, la valeur est « generic ».
• elements : définit les propriétés personnalisées de notre modèle. Pour le modèle générique, nous précisons un titre, un sous-titre, une image et deux boutons de renvoi.

Pour notre message structuré, nous utilisons l’attachment_url qui nous a été envoyé comme image_url à afficher dans notre modèle et ajoutons quelques boutons de renvoi pour permettre au ou à la destinataire du message de répondre. Pour concevoir la charge utile du message et envoyer le modèle générique, mettez à jour handleMessage() en utilisant le code suivant :

La dernière étape consiste à gérer l’évènement webhook messaging_postbacks qui sera envoyé lorsque le ou la destinataire du message appuiera sur l’un des boutons de renvoi dans notre modèle générique.

Que puis-je faire avec les renvois ?

Le bouton de renvoi envoie à votre webhook un évènement webhook messaging_postbacks comprenant une chaîne personnalisée de 1 000 caractères maximum dans la propriété payload. Cela vous permet d’implémenter facilement différentes charges utiles de renvoi que vous pouvez analyser et auxquelles vous pouvez répondre avec des comportements précis.

Puisque notre modèle générique permet au ou à la destinataire du message de choisir entre deux boutons de renvoi, nous répondrons en fonction de la valeur de la propriété payload de l’évènement de renvoi. Pour ce faire, mettez à jour votre stub handlePostback() en utilisant le code suivant :