Creare un Bot Facebook: guida passo passo

In un precedente tutorial ho spiegato come creare un bot su Telegram, ora vedremo come fare la stessa cosa sulla piattaforma Facebook utilizzando Messenger Send/Receive API presentata durante F8 2016 Facebook Developer Conference.

Prima di proseguire √® necessario evidenziare che, a differenza di Telegram, la disponibilit√† di un bot accessibile a tutti richiede di superare il processo di approvazione da parte di Facebook. Il superamento di tale step √® subordinato al rispetto della policy che √® possibile consultare all’indirizzo https://developers.facebook.com/policy/#messengerplatform

In questa guida costruiremo un bot dimostrativo che non svolge nessuna azione utile se non quella di ripetere ciò che gli scriviamo. Esso ha lo scopo di farci prendere confidenza con le API di Facebook, ma non è idoneo per poter essere pubblicato.

Questa guida è rivolta a chi ha dimestichezza con il linguaggio PHP e dispone di un account Dropbox.

Inziamo! Per prima cosa procediamo ad attivare un account gratuito sulla piattaforma Heroku all’indirizzo https://www.heroku.com/.

Su Heroku selezioniamo sign up e compiliamo il form di iscrizione con i campi obbligatori (first name, last name, email). Selezioniamo come primary language PHP e facciamo click su create free account.

Riceveremo una email con un link di conferma. Attraverso quest’ultimo link completiamo la creazione del nostro account Heroku impostando la password dell’account. Per impostare la password scegliamo una stringa di almeno 8 caratteri che contenga lettere e numeri, almeno una lettera maiuscola ed una minuscola e almeno un carattere speciale. Siamo pronti a fare il primo login su Heroku.

Il passo immediatamente successivo √® quello di creare un’applicazione su Heroku. Selezioniamo create new app (simbolo +)

Create app

Impostiamo:

App Name: il nome della nostra applicazione, es. facebook-echo-bot
Region: Europe

Per completare facciamo click su create app.

create_app_step1

Non ci resta che impostare Dropbox come metodo di deployment delle applicazioni su Heroku. Facciamo click su Dropbox nella sezione deployment method. Si aprir√† una finestra del browser che ci chiede di autenticarci su Dropbox e facendo click su consenti, autorizziamo il dialogo tra Heroku e Dropbox. Al termine di questa fase sar√† creata una cartella sul nostro account Dropbox denominata Applicazioni/Heroku/{APP NAME} dove {APP NAME} corrisponde al nome dell’applicazione impostata precedentemente.

heroku1

Scarichiamo da questo link gli script PHP necessari per il funzionamento del nostro bot.

Modifichiamo il file config.php con un editor di testo, al suo interno sono presenti le seguenti 4 righe:

<?php
define("FACEBOOK_PAGE_ACCESS_TOKEN", "Insert here");
define("FACEBOOK_PAGE_ID", "Insert here");
define("FACEBOOK_VALIDATION_TOKEN", "Insert here");

Sostituiamo in corrispondenza di FACEBOOK_VALIDATION_TOKEN il testo Insert here con una stringa casuale, ad esempio 123456.

edit_config_1

Carichiamo nella cartella appena creata su Dropbox i file:

  • index.php
  • Procfile
  • composer.json
  • FacebookBot.php
  • config.php
  • webhook.php

heroku2

Torniamo su Heroku e facciamo click su deploy nella sezione deploy changes. Se tutto è andato bene riceveremo come messaggio: Your app was successfully deployed. Facendo click su view avremo lo url della nostra applicazione PHP. Nel caso di esempio lo url è https://facebook-echo-bot.herokuapp.com/.

heroku_deploy_success

Prima di proseguire dobbiamo recuperare il Page ID di una nostra pagina alla quale associare il bot, se non siamo in possesso di una pagina Facebook √® possibile crearne una. Il mio consiglio √® di creare in ogni caso una pagina Facebook da utilizzare per test, tale pagina dopo essere stata creata pu√≤ essere resa non pubblica. L’immagine di profilo e il nome della pagina saranno l’identit√† del bot nelle conversazioni con gli utenti.

page_info

Per recuperare l’ID della nostra pagina Facebook √® necessario andare sulla tab Informazioni e scorrere la pagina in fondo, fino a trovare la voce ID Pagina Facebook.

page_id

L’ID Pagina Facebook va inserito all’interno del file config.php, in corrispondenza della voce FACEBOOK_PAGE_ID.

Adesso è ora di creare il nostro bot su Facebook. Andiamo su Facebook for developers al link https://developers.facebook.com.

add_new_app

Dal menu My apps scegliamo Add a New App. Apparirà la seguente schermata:

add_a_new_app

Facciamo click sulla voce Website e scegliamo il nome dell’applicazione Facebook che corrisponde al nostro bot, es. Echo Bot.

quick_start_for_website

Facciamo click sul bottone Skip and Create App ID, apparirà una schermata come quella che segue.

create_a_new_app_id

Impostiamo almeno i campi obbligatori:

Display Name: il nome della nostra applicazione, es. Echo Bot
Contact Email: il tuo indirizzo email
Category: Utilità

Per completare facciamo click su Create App ID, verremo portati sulla schermata seguente.

create_a_new_app_id_2

Cerchiamo la sezione Messenger e facciamo click sul bottone Get Started.

messenger_platform

Facebook ci allerta che la piattaforma Messenger √® in beta e non deve essere usata per finalit√† di marketing¬† o per comunicazioni promozionali. Inoltre ci viene ribadito che affinch√® le applicazioni siano visibili pubblicamente √® necessario superare lo step di review da parte del team di Facebook. Finch√® l’app non √® pubblica sar√† possibile inviare messaggi solo agli sviluppatori e ai tester dell’app. Proseguiamo facendo click su Get Started.

Nella sezione Token Generation selezioniamo la nostra pagina Facebook da associare al bot.

messenger_1

Facebook ci chiede se vogliamo consentire all’applicazione di poter amministrare e gestire la pagina selezionata. Per proseguire dobbiamo accettare.

messenger_2

Se tutto è andato bene la casella Page Access Token viene popolata con una stringa.

Ricordando l’ID Pagina Facebook recuperato in precedenza e il Page Access Token appena mostrato, modifichiamo il file config.php rispettivamente in corrispondenza delle voci FACEBOOK_PAGE_ID e FACEBOOK_PAGE_ACCESS_TOKEN.

Procediamo ricaricando il file config.php nella cartella Dropbox della nostra applicazione e successivamente effettuiamo un nuovo deploy su Heroku.

Su Facebook Developers completiamo la configurazione agendo sulla sezione Webhooks e facendo click su Setup Webhooks.

webhooks

Apparirà una schermata come quella che segue.

setup_webhook

Compiliamo i seguenti campi:

Callback URL: https://facebook-echo-bot.herokuapp.com/webhook.php
Verify token: 123456
Subscription filelds: messages, messaging_postbacks

Il campo Callback URL √® formato dall’indirizzo della nostra applicazione PHP su Heroku a cui accodiamo il nome dello script che gestir√† il webhook Facebook e cio√® webhook.php.

Facciamo click su Verify and Save, se l’applicazione PHP risponde correttamente ci apparir√† la seguente schermata.

webhook_save_ok

Per completare la configurazione del nostro bot non ci rimane che sottoscrivere il webhook agli eventi della nostra pagina Facebook, in questo modo ogni qual volta la pagina Facebook riceve un messaggio, esso viene instradato al bot che altro non √® che un’applicazione Facebook. Per fare ci√≤ √® possibile utilizzare l’apposita funzione presente all’interno della sezione Webhooks, come illustrato sotto.

subscribe_weebhook

In alternativa √® possibile caricare su Dropbox lo script subscribeAppToThePage.php, effettuarne il deploy su Heroku ed eseguirlo visitando col browser la pagina corrispondente http://facebook-echo-bot/subscribeAppToThePage.php. Se l’operazione va a buon fine la pagina web visualizza App subscribed to the Page succesfully!

La configurazione del bot è terminata. Non ci rimane che iniziare ad utilizzarlo.

Andiamo sulla nostra pagina Facebook e facciamo click su Messaggio.

page_message

Iniziamo a scrivere al bot e attendiamo le risposte.

test_echo_bot

Se vuoi approfondire le potenzialità della Facebook Messenger API puoi consultare la documentazione ufficiale qui.

Al link http://poncho.is trovi, invece, un esempio di bot Facebook con cui iniziare a prendere confidenza.

Aggiornamento del 16/05/2016

  • Se vuoi realizzare un bot che risponde a specifiche richieste testuali, qui trovi un esempio.

Questions?

Have a question about this post or anything else? Ask away on Twitter or in my AMA repo.

22 thoughts on “Creare un Bot Facebook: guida passo passo”

  1. Guida completa e ben fatto, complimenti!
    TI volevo chiedere invece come poter aumentare le funzioni del bot, facendo si che risponda alle domande, ecc..

    Grazie

  2. Guida molto utile e bene fatta, complimenti!
    Ti volevo chiedere invece come programmare il bot affinché risponda alle domande, ecc..
    Grazie

  3. Grazie Salvatore per il tuo aiuto, è stato fondamentale.
    Una domanda:
    oltre alle variabili entryId,senderId,timestamp… dove posso vedere e come faccio a leggere altre informazioni?

  4. Ciao Salvatore, complimenti per il tutorial. Un’altra domanda, come faccio ad impostare il messaggio di benvenuto? Ovvero, come faccio a far comparire un messaggio non appena un utente apre la chat? Ho provato con setWelcomeMessage ma nulla, mi da sempre errore.

    Grazie

    1. Ciao!
      Per visualizzare i messaggi ricevuti dal Bot potresti, ad esempio, modificare lo script webhook.php intorno alla riga 9 per far si che ad ogni messaggio ricevuto si scriva su un file di testo. Leggendo il file di testo avrai la possibilità di visualizzare i messaggi ricevuti.
      Ti ricordo che su Heroku, utilizzando il piano free, non è possibile fare quanto sopra ipotizzato.

      A presto,
      Salvatore

  5. Salve, guida eccellente, ma ho una domanda, ho necessità di inviare un messaggio di benvenuto a chiunque mi contatti per la prima volta nella pagina, come posso fare ?

    inoltre, posso inviare un messaggio a tutti coloro che già mi hanno contattato in pagina in automatico ?

    1. Ciao Ernesto,
      la risposta al primo messaggio (get started) la puoi impostare usando lo script setWelcomeMessage.php che trovi su GitHub.

      Per inviare un messaggio a tutti coloro che ti hanno scritto dovresti memorizzare gli id degli utenti (intendo il $recipientId di ciascuno) e inviare un messaggio ad esempio utilizzando il metodo $bot->sendTextMessage($recipientId, $message->text);.

      A presto,
      ^SC

  6. Ciao Salvatore!

    Ti ringrazio per l’interessante ed esaustiva guida che hai postato!

    Sto cercando di capire se è possibile inserire sulla pagina Facebook due bottoni differenti per iniziare una conversazione:
    1. Far iniziare una conversazione standard dal tasto invia messaggio.
    2. Far partire il bot da un tasto inserito all’interno delle informazioni.

    Sostanzialmente differenziare i due sistemi

    Ho visto che alcune pagine estere lo fanno. Sai se è possibile farlo?

    Ti ringrazio,

    Molly

  7. Complimenti per la guida Salvatore!
    Avrei una domanda da farti.. Vorrei che quando qualcuno apre la chat appaia un pulsante “get started”. Ho seguito la documentazione di facebook ma essendo poco esperto nel linguaggio php non ho idea di dove inserire il codice che facebook propone in questa pagina: https://developers.facebook.com/docs/messenger-platform/thread-settings/get-started-button.
    Ho visto che nel file zip contenente i vari file ce ne √® uno che si chiama “setWelcomeMessage” ma anche se inserito su dropbox non invia alcun messaggio nella chat.
    Grazie per l’aiuto!

  8. Ciao e complimenti per l’ottimo lavoro! Ho consultato la documentazione di Facebook per lavorare un po’ sul tuo codice, ma con qualche difficolt√†. Ho modificato FacebookBot.php in questo modo:
    public function sendImageMessage($recipientId, $text)
    {
    $url = “https://graph.facebook.com/v2.6/me/messages?access_token=%s”;
    $url = sprintf($url, $this->getPageAccessToken());
    $recipient = new \stdClass();
    $recipient->id = $recipientId;
    $message = new \stdClass();
    $message->attachment = $text;
    $parameters = [‘recipient’ => $recipient, ‘message’ => $message];
    $response = self::executePost($url, $parameters, true);
    if($response)
    {
    $responseObject = json_decode($response);
    return is_object($responseObject) && isset($responseObject->recipient_id) && isset($responseObject->message_id);
    }
    return false;
    }
    Sostanzialmente la propriet√† passa da “text” ad “attachment”. Poi nel webhook:
    $data = ‘”attachment”:{
    “type”:”image”,
    “payload”:{
    “url”:”https://petersapparel.parseapp.com/img/shirt.png”,
    “is_reusable”:true
    }
    }”;’;
    $bot->sendImageMessage($recipientId, $data);
    Ma non arriva nessuna risposta. Qualche idea? La domanda √® rivolta anche agli altri lettori! ūüôā

  9. Con un metodo poco elegante ma efficace ho risolto così:
    public function sendImageMessage($recipientId, $text)
    {
    $url = “https://graph.facebook.com/v2.6/me/messages?access_token=%s”;
    $url = sprintf($url, $this->getPageAccessToken());
    //Initiate cURL.
    $ch = curl_init($url);

    //The JSON data.
    $jsonData = ‘{
    “recipient”:{
    “id”:”‘.$recipientId.'”
    },
    “message”:{
    “attachment”:{
    “type”:”image”,
    “payload”:{
    “url”:”‘. $text . ‘”,
    “is_reusable”:true
    }
    }
    }
    }’;
    //Encode the array into JSON.
    $jsonDataEncoded = $jsonData;

    //Tell cURL that we want to send a POST request.
    curl_setopt($ch, CURLOPT_POST, 1);

    //Attach our encoded JSON string to the POST fields.
    curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);

    //Set the content type to application/json
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(‘Content-Type: application/json’));
    //curl_setopt($ch, CURLOPT_HTTPHEADER, array(‘Content-Type: application/x-www-form-urlencoded’));

    //Execute the request
    $result = curl_exec($ch);

    }

    Passo l’url al posto del testo…

    1. Ciao Pierluigi,
      il codice del tutorial non √® gi√† di suo di buona qualit√†. √ą stato scritto nel modo pi√Ļ semplice possibile solo per
      fini didattici. Per la tua necessità di gestire non solo testo ti consiglio di utilizzare le librerie che trovi su GitHub.

      A presto,
      Salvatore

  10. Buonasera Salvatore e complimenti per la tua guida! Mi sto addentrando da qualche mese nel mondo della programmazione visto che finalmente essendo in terza itis abbiamo iniziato il vero e proprio corso di informatica ma php e gli altri linguaggi del web purtroppo li studieremo fra 2 anni ma vorrei portarmi un po’ avanti visto che il php ad esempio fin’ora mi √® sembrato abbastanza simile al c++. Vorrei far inviare dal bot oltre messaggi di testo, anche immagini e audio sempre in base al testo che viene inviato dall’utente. Hai per caso qualche esempio semplice come nei tutorial da mostrarmi? Perch√® ho guardato nella documentazione di facebook ma tra json e curl non ho capito molto, inoltre ho controllato anche su github ma anche l√¨ ho avuto qualche problema perch√® il codice √® scritto giustamente in modo pi√Ļ “professionale”/complesso rispetto al tuo tutorial.. Grazie ūüôā

Leave a Reply

Your email address will not be published. Required fields are marked *