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.

47 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 🙂

  11. Ciao,
    Sto eseguendo la procedura e sono arrivata a inserire la url per il webhook, ho seguito passo per passo le tue istruzioni.
    Cosa potrebbe essere?

  12. Ciao e anzitutto grazie della guida.
    Ho trovato qualche shermata leggermente differente (forse perche’ e’ cambiata l’interfaccia di FB) ma i passi sono stati gli stessi ed ora ho un webhook che dice di dialoare con la pagina.
    Quando pero’ digito qualcosa nel messanger non mi risponde nulla il bot. C’e’ la possibilita’ di vedere da qualche parte un log cosi’ da capire cosa succede?
    Grazie
    M

    1. Ciao Massimo,
      dovresti provare a modificare il file webhook.php per fare in modo che scriva, ad esempio su un file di testo, ogni messaggio ricevuto.
      Purtroppo non è possibile implementare questa soluzione su Heroku in modo semplice, su un tuo hosting sarebbe tutto più semplice.

      A presto,
      Salvatore

  13. Ho seguito le info del tutorial e sembra funzionare tutto bene!
    il problema è che il bot funziona solo con me che sono l’admin! se scrive un altro utente non risponde… come mai? dove sbaglio?

    1. Ciao Luciano,
      quanto scrivi è corretto. Se rileggi la primissima parte del tutorial scoprirai che per rendere il bot accessibile a tutti,
      è necessario superare uno step di approvazione del bot da parte di Facebook.

      A presto,
      Salva

  14. Ciao Salvatore, ottima guida! 🙂
    Avrei bisogno di un’informazione, vorrei che il messaggio inviato dal bot venga inviato solo una volta ogni TOT tempo, ad esempio max. 1 al giorno.
    Mi spiego meglio, se l’utente mi scrive “segnala un problema” io farò dire al bot “Ok, ho segnalato al reparto tecnico” e invierò i miei dati al db di competenza… Quest’operazione può essere svolta MAX 1 volta al giorno utente ciò significa che se dopo 10 minuti lo stesso utente scrive nuovamente “segnala un problema” io agirò in maniera diversa ad esempio rispondendo “Hai già segnalato il problema!”

    Sicuramente dovrò usare un Database per registrare le richiesta però non so come reperire il dato “utente” esiste una variabile che mi permette di ricevere l’ID utente (univoco)?

    Grazie Mille,
    A presto

    1. Ciao Riccardo,
      quanto dici è corretto.

      Nel codice dimostrativo allegato al tutorial trovi il campo senderId dell’oggetto $message.
      Quella è l’informazione di cui hai bisogno.

      A presto,
      Salvatore

  15. Salve, non so se la domanda sia pertinente, ma provo a spiegare.

    Ho mandato di recente un messaggio sulla pagina Facebook di un noto quotidiano nazionale. Da quel momento, ogni volta che sulla pagina veniva pubblicato un nuovo post, ricevevo un messaggio su Facebook con il riepilogo della notizia appena pubblicata.

    E’ questo che che fa un bot?

    Grazie.

  16. Ciao,
    complimenti per la tua guida. Sei stato veramente utile e preciso!
    Ho dovuto solo modificare la setWelcomeMessage.php e deleteWelcomeMessage.php in quanto le API di facebook sono modificate da quando hai scritto l’articolo.

    Grazie!!

  17. Ciao Salvatore,
    ho provato la tua guida ma il file setwelcomemessage.php non mi rimanda nessun testo quando apro la chat.
    Come faccio?
    Grazie

  18. Ciao Salvatore e grazie per la guida!

    Avendo uno spazio hosting HTTPS ho pubblicato i file sul mio server modificando il file config.php con i valori indicati e testata la Webhook. Il test di FB è andato a buon fine, ho sottoscritto l’App alla pagina di riferimento, ma quando provo a inviare un messaggio non accade nulla, non vedo nemmeno log di chiamate alla pagina.

  19. Ciao Salvatore e complimenti per questo articolo.

    ho lo stesso problema di Dario Papetti e ho già cancellato e reinserito l’app.

    Ciao Salvatore, non riesco a configurare i webhooks.
    ho inserito l’url:
    https://dp-facebook-echo-bot.herokuapp.com/webhook.php ma fb mi dice:

    Non è stato possibile convalidare l’URL. Response does not match challenge, expected value=”52591643″, received=””

    Il nome della app è facebook-echo-bot-san

    Mi potresti aiutare?

    1. Ciao!
      Puoi controllare se il file config.php è stato correttamente aggiornato nel campo FACEBOOK_VALIDATION_TOKEN.
      Facebook si aspetta di verificare il codice che hai inserito in questo campo.

      A presto,
      Salvatore

  20. messaggio di errore:

    Non è stato possibile convalidare l’URL. Response does not match challenge, expected value=”1965372425″, received=””

Leave a Reply

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