Tutorial di avvio rapido

Se non l'hai già fatto, segui la nostra guida alla configurazione dell'app per configurare la tua app Facebook per l'uso con la Piattaforma Messenger.

Tutte le richieste alle API Messenger Platform sono autenticate includendo un token di accesso a livello di pagina nel parametro access_token della stringa della query.

Se non l'hai ancora fatto durante la configurazione dell'app Facebook, genera un token d'accesso della Pagina come segue:

Consigliamo di tenere al sicuro le informazioni sensibili, come il token d'accesso della Pagina, non effettuandone l'hardcoding nel webhook.

Per farlo, aggiungi le seguenti variabili ambientali. <PAGE_ACCESS_TOKEN> è il token d'accesso appena generato e <VERIFY_TOKEN> è una stringa casuale usata per verificare il webhook.

PAGE_ACCESS_TOKEN="

Ora tutto quello che devi fare è aggiungere il token d'accesso della Pagina e verificare il token all'inizio del file app.js, per poterlo usare nella logica del webhook:

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

Per iniziare, abbozziamo tre funzioni che gestiranno i tipi di eventi webhook in ingresso che vogliamo supportare e a cui risponderanno tramite l'API Send. Per farlo, aggiungi quanto segue al file 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) {
  
}

Per rispondere agli utenti su Messenger, dobbiamo prima sapere chi sono. Per farlo, in Messenger, bisogna recuperare l'ID della singola Pagina del mittente (PSID) dall'evento webhook in ingresso.

Cos'è un PSID?

Agli utenti viene assegnato un ID della singola Pagina (PSID) per ciascuna Pagina Facebook con cui avviano una conversazione. Il PSID permette di identificare l'utente quando invia dei messaggi.

Se hai completato una delle opzioni nella sezione precedente Progetto iniziale, dovresti avere un endpoint /webhook di base che accetta le richieste POST e registra il corpo degli eventi webhook che riceve. Dovrebbe avere un aspetto simile al seguente:

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

});

Per recuperare il PSID del mittente, estraendolo dalla proprietà sender.id dell'evento, aggiorna il blocco body.entry.forEach con il codice seguente:

Vogliamo che la nostra esperienza sia in grado di gestire due tipi di eventi webhook: messages e messaging_postback. Il nome del tipo di evento non è incluso nel corpo dell'evento, ma possiamo determinarlo controllando certe proprietà degli oggetti.

Cosa sono gli eventi webhook?

La Piattaforma Messenger invia eventi webhook per fornirti delle notifiche delle azioni che avvengono su Messenger. Gli eventi vengono inviati in formato JSON come richieste POST al tuo webhook. Per ulteriori informazioni, consulta Eventi webhook.

Per renderlo possibile, aggiorna il blocco body.entry.forEach del webhook con una condizionale che verifica se l'evento ricevuto contiene una proprietà message o postback. Aggiungeremo anche delle chiamate alle funzioni handleMessage() e handlePostback() che avevamo abbozzato poco fa:

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

Ora che i messaggi in arrivo vengono indirizzati alla funzione handler corretta, possiamo aggiornare handleMessage() in modo che gestisca e risponda ai messaggi di testo di base. Per farlo, aggiorna il codice per definire il payload del messaggio della risposta, quindi passa quel payload a callSendAPI(). Vogliamo rispondere con un messaggio di testo di base, quindi dobbiamo definire un oggetto JSON con una proprietà "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);    
}

È arrivato il momento di inviare il primo messaggio con l'API Send della Piattaforma Messenger.

In handleMessage(), effettuiamo una chiamata a callSendAPI(), quindi ora dobbiamo aggiornarlo per costruire il corpo completo della richiesta e inviarlo alla Piattaforma Messenger. Le richieste all'API Send hanno due proprietà:

• recipient: definisce il destinatario del messaggio. In questo caso, identifichiamo l'utente tramite il suo PSID.
• message: definisce i dettagli del messaggio da inviare. In questo caso, useremo l'oggetto messaggio che abbiamo passato dalla funzione handleMessage().

Per costruire il corpo della richiesta, aggiorna la bozza per callSendAPI() come segue:

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

Ora dobbiamo solo inviare il messaggio con una richiesta POST all'API Send all'indirizzo https://graph.facebook.com/v2.6/me/messages.

Ricorda di aggiungere il PAGE_ACCESS_TOKEN al parametro access_token della stringa di query dell'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);
    }
  }); 
}

Fai un test!

Su Messenger, invia un altro messaggio di testo alla Pagina Facebook. Dovresti ricevere una risposta automatica dall'esperienza Messenger che ripete il messaggio e ti chiede di inviare un'immagine.

Dal momento che la nostra risposta richiede al destinatario del messaggio di inviare un'immagine, il passaggio successivo è aggiornare il codice in modo che possa gestire gli allegati. Gli allegati inviati vengono automaticamente salvati dalla Piattaforma Messenger e resi disponibili con un URL nella proprietà payload.url di ciascun indice nell'array attachments, quindi estrarremo anche queste informazioni dall'evento.

Che tipo di allegati sono supportati?

L'esperienza Messenger può inviare e ricevere la maggior parte dei tipi di risorse, inclusi immagini, audio, video e file. I contenuti multimediali vengono visualizzati e possono anche essere riprodotti nella conversazione, permettendoti di creare esperienze rich media.

Per determinare se il messaggio è un allegato, aggiorna la condizionale nella funzione handleMessage() per verificare la presenza di una proprietà attachments nel received_message e quindi estrarne l'URL. Per un bot da usare in produzione, dovremmo ripetere l'array per controllare la presenza di più allegati, ma per questa guida introduttiva ci limiteremo al primo allegato.

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

Ora risponderemo all'immagine con un modello generico di messaggio. I modelli generici sono il tipo di messaggio strutturato più comunemente usato e permettono di inviare un'immagine, del testo e dei pulsanti in un singolo messaggio.

Sono disponibili altri modelli di messaggi?

Sì. La Piattaforma Messenger offre un set di utili modelli di messaggio, ciascuno progettato per supportare una struttura comune dei messaggi diversa, tra cui elenchi, ricevute, pulsanti e altro ancora. Per tutti i dettagli, consulta Modelli.

I modelli dei messaggi sono definiti nella proprietà attachment del messaggio, che contiene le proprietà type e payload. La proprietà payload è quella in cui definiremo le seguenti proprietà del nostro modello generico:

• template_type: definisce il tipo di modello usato per il messaggio. Usiamo il modello generico, quindi il valore è "generic".
• elements: definisce le proprietà personalizzate del modello. Per il modello generico, definiremo un titolo, un sottotitolo, un'immagine e due pulsanti di postback.

Per il messaggio strutturato, useremo l'attachment_url che ci è stato inviato come l'image_url da visualizzare nel modello e includeremo dei pulsanti di postback per consentire al destinatario di rispondere. Per costruire il payload del messaggio e inviare il modello generico, aggiorna handleMessage() come segue:

L'ultimo passaggio è gestire il webhook messaging_postbacks che verrà inviato quando il destinatario del messaggio seleziona uno dei pulsanti di postback nel nostro modello generico.

Cosa posso fare con i postback?

Il pulsante con postback invia un evento webhook messaging_postbacks al webhook che include una stringa personalizzata di massimo 1000 caratteri nella proprietà payload. In questo modo, puoi facilmente implementare diversi payload di postback da analizzare a cui rispondere con comportamenti specifici.

Dal momento che il nostro modello generico permette al destinatario di scegliere tra due pulsanti con postback, risponderemo in base al valore della proprietà payload dell'evento di postback. Per farlo, aggiorna la bozza handlePostback() come segue: