Getting started: creare un Bot Facebook con Python

By Andres Reyes / Luglio 16, 2017 / No Comments

Sommario

Tech Stack
Step 1 - Creazione di una pagina Facebook
Step 2 - Creazione di una App Facebook
Step 3 - Creazione di un webHook con Heroku
Requirements
- URL di callback
Step 4 - API Graph
Bibliografia

Lo scopo di questa guida step by step è di realizzare un echobot che svolga la semplice funzione di ripetere ciò che gli scriviamo in modo da prendere confidenza con le API Graph di Facebook, per poi arrichire le funzionalità del nostro chatbot con servizi di elaborazione e comprensione del linguaggio naturale (NLP/NLU) come:

- Api.ai (Google)
- Wit.ai (Facebook)
- LUIS (Microsoft)
- Watson (IBM)
- Lex (Amazon)

Tech Stack

[1] Creazione di un account Heroku per il deployment del nostro progetto e utilizzo di Git per tenerlo aggiornato.
[2] Python come linguaggio di programmazione scelto, nel nostro caso 3.5 installato attraverso Anaconda per Windows.
[3] Conda per la creazione di un nuovo ambiente di lavoro pulito, in modo da avere solo le librerie necessarie al deploymento del nostro progetto.
[4] Utilizzo come IDE Visual Studio 2015 con estensione Python Developments Tools.

Step 1 - Creazione di una pagina Facebook

Per iniziare dobbiamo creare una pagina Facebook scegliendo innanzitutto se sarà dedicata a un'impresa locale, a un marchio o a un prodotto e così via.
Una volta selezionata la categoria più pertinente alle nostre necessità e scelto il nome della pagina dobbiamo iscriverci a "Facebook for developers" per associarvi l'app chatbot che andremo a creare.

Step 2 - Creazione di una App Facebook

Dalla pagina per gli sviluppatori di Facebook, facciamo click sul pulsante Crea App in alto a destra e compiliamo i campi obbligatori e infine clickiamo su Crea id app.

Dopo aver digitato anche l'eventuale captcha richiestoci, dovremmo essere reindirizzati in automatico sulla nuova pagina dell'applicazione.
Nel nostro caso andremo a realizzare un echoBot, il cui nome per motivi di praticità coinciderà sia con il nome della nostra app che con quello della pagina Facebook creata precedentemente.

Sotto la voce Prodotti clickiamo Aggiungi prodotto e selezioniamo Messenger.

Nella sezione messenger della dashboard alla voce configura webhook dovremmo inserire il callback URL e poi scegliere un Validation Token.

Il campo callback URL verrà compilato con l’indirizzo https che otterremo dalla nostra applicazione Python sfruttando il servizio gratuito di cloud PaaS (Platform as a service) Heroku. Possiamo scegliere altri servizi come: pythonanywhere, google cloud.

Step 3 - Creazione di un webHook con Heroku

Ora dobbiamo creare un account gratuito sulla piattaforma cloud Heroku selezionando in alto a destra sign up e compilando i campi obbligatori (first name, last name, email, country) del form di iscrizione. Infine impostiamo come primary language Python e facciamo click su create free account.
Il passo successivo ,dopo essersi registrati e loggati, è di creare un’applicazione su Heroku selezionando Create new app in alto a destra dalla dashboard.

Ora non ci resta che scegliere il nome della nostra applicazione,ad esempio fb-echobot, e come regione Europe.

Per completare l'operazione facciamo click su Create App.

Metodo di deployment con Heroku CLI

Non ci resta che scegliere il metodo di deployment che preferiamo per la nostra applicazione python, nel nostro caso utilizzeremo Heroku Git per poter fare il deploy usando Heroku come repository GIT. Così facendo possiamo sviluppare la nostra app in locale per poi importarla all'interno del nostro account.
Su Windows installiamo Heroku CLI e da prompt dei comandi (CMD) come amministratori digitiamo i seguenti comandi:

heroku login

1	heroku login

Inseriamo le credenziali del nostro account.

$ cd my-project/ #cartella del nostro progetto
$ git init
$ heroku git:remote -a fb-echobot

$ cd my-project/ #cartella del nostro progetto

$ git init

$ heroku git:remote -a fb-echobot

Creiamo un nuovo repository GIT e a questo punto non ci resta che aggiungervi i files del nostro progetto, farne il commit ed infine il push.

$ git add .
$ git commit -am "testing echoBot"
$ git push heroku master

$ git add .

$ git commit -am "testing echoBot"

$ git push heroku master

Il primo push non si scorda mai

Prima di poter digitare il comando git push però abbiamo bisogno di due files:

- Creazione di un Procfile (documentazione)
- Dichiarazione delle dipendenze: Requirements.txt (documentazione)

Procfile

Con un text-editor dobbiamo creare un nuovo file dal nome Procfile e salvarlo senza estensione nella cartella principale della nostra applicazione e inserirvi il seguente contenuto:

web: gunicorn echoBot:app

1	web: gunicorn echoBot:app

Questo file serve ad Heroku per inizializzare un processo web ed eseguire un'applicazione python dal nome echoBot.py utilizzando come web-server gunicorn (WSGI).

Il motivo per cui si utilizza un web-server aggiuntivo è legato al rapporto fra le prestazioni e l'impiego di risorse di calcolo (dynos) come ci viene spiegato dalla documentazione:

Gunicorn is a pure-Python HTTP server for WSGI applications. It allows you to run any Python application concurrently by running multiple Python processes within a single dyno. It provides a perfect balance of performance, flexibility, and configuration simplicity.

Dyno è l'unità di misura del quantitativo di risorse impiegate dalla nostra applicazione che utilizza Heroku per la tariffazione del servizio offerto di cloud computing . Con un account gratuito ad ogni applicazione verrà assegnato un solo dyno cioè un singolo processo, che a scelta può essere di tipo web o worker (batch).
Se la nostra applicazione resta inattiva per più di 30 mininuti andrà in sleep.

Requirements

Durante un deploy Heroku accede al file requirements.txt per installare tutti i pacchetti (dependencies) necessari all'applicazione affinché venga avviata.
Il mio consiglio è di creare un nuovo enviroment con Anaconda in modo da avere un'installazione di python pulita e isolata da quella principale, così avremmo solo le dependencies necessarie per l'esecuzione del programma e il file requirements già pronto. Infine in caso di problemi basterà solo cancellare il nuovo enviroment.
Per creare un nuovo ambiente su Windows da prompt dovremmo usare il comando:

conda create -n newenv python=3.5

1	conda create -n newenv python=3.5

avremmo così un'installazione pulita con python 3.5 e per attivarlo

activate newenv

1	activate newenv

Da questo momento dovremmo vedere alla sinistra del prompt l'indicazione del nuovo ambiente. In seguito con pip installaremo man mano i pacchetti che ci serviranno come flask, gunicorn, requests etc.
Per avere l'elenco completo dei pacchetti installati ci basterà digitare:

(newenv) C:\>pip freeze
certifi==2017.4.17
chardet==3.0.4
click==6.7
Flask==0.12.2
gunicorn==19.7.1
idna==2.5
itsdangerous==0.24
Jinja2==2.9.6
MarkupSafe==1.0
requests==2.18.1
urllib3==1.21.1
Werkzeug==0.12.2

(newenv) C:\>

(newenv) C:\>pip freeze

certifi==2017.4.17

chardet==3.0.4

click==6.7

Flask==0.12.2

gunicorn==19.7.1

idna==2.5

itsdangerous==0.24

Jinja2==2.9.6

MarkupSafe==1.0

requests==2.18.1

urllib3==1.21.1

Werkzeug==0.12.2

(newenv) C:\>

Ora che abbiamo il nostro file requirements.txt pronto nella folder del nostro progetto dovremmo avere tre files: echoBot.py, Procfile e requirements.txt
Io utilizzo come IDE Visual Studio 2015 con estensione Python Developments Tools quindi nella mia folder visualizzerò i seguenti files:

URL di callback

Dopo aver fatto il git push andiamo sulla dashboard online di Heroku e selezioniamo Open app e si aprirà in automatico una nuova tab del browser.

Dove visualizzeremo l'indirizzo https di callback che useremo come webhook per Facebook e il messaggio di verifica del webhook che abbiamo utilizzato anche nel listato python.

Step 4 - API Graph

La prima formulazione della teoria dei grafi la dobbiamo al matematico Leonhard Euler (1707-1783) che nel saggio “Soluzione di un problema di geometria dei siti” del 1736 risolse il problema dei sette ponti di Königsberg.
Oggi la cittadina è nota con il nome di Kaliningrad ed è situata sulle rive del fiume Pregel in cui furono costruiti sette ponti per connettere l’isolotto di Kneiphof chiuso tra i due rami del fiume. Euler formulò il problema nei termini di :

qualunque sia la configurazione e la distribuzione in rami del fiume e qualunque sia il numero dei ponti, si può scoprire se è possibile passare per ogni ponte una ed una sola volta?

Eulero dimostrò che il problema non era risolubile utilizzando come metodo un grafo, cioè sostituendo ad ognuna delle quattro zone di terra con dei nodi ed ad ogni ponte con un arco. Ottenendo così un grafo con quattro nodi e sette archi.
Lo scienziato Albert-László Barabási , nella sua opera "Link, La nuova scienza delle reti", ci racconta che dopo Euler la teoria dei grafi ebbe un notevole sviluppo grazie ai contributi di matematici come Augustin-Louis Cauchy, William Hamilton, Arthur Cayley, Gustav Kirchhoff e György Pólya.
Oggi alla base delle API graph c'è il l'idea di rappresentare Facebook come un grafo (Social Graph) i cui nodi sono gli oggetti (objects) come un utente, una foto, una Pagina o un commento ed i segmenti sono invece le connessioni (archi) fra gli oggetti , come le foto di una pagina o i commenti a una foto. Infine le informazioni sugli elementi come il compleanno dell'utente o il nome di una Pagina sono i campi.
Per visualizzare le connessioni di un oggetto basta andare nella sua pagina di documentazione , come ad esempio quella dell'oggetto user da cui parte la connessione friends, che collega ogni utente ad altri utenti.
Ogni oggetto del social graph ha un identificativo ID univoco , per accedere alle sue proprietà dobbiamo contattare ogni volta l’indirizzo https://graph.facebook.com/

Codice completo: echobot

# -*- coding: utf-8 -*-

import os, sys
from flask import Flask
from flask import request
import requests
import json

app = Flask(__name__)

#facebook page access data
PAT = (" ")
validationToken = ("testingEchoBot")

@app.route('/', methods=['GET'])

def verify():
    # Webhook verification
    if request.args.get("hub.mode") == "subscribe" and request.args.get("hub.challenge"):
        if not request.args.get("hub.verify_token") == validationToken:
            return ("Verification token mismatch", 403)
        return request.args["hub.challenge"], 200

    return ("webhook ok", 200)

@app.route('/', methods=['POST'])

def webhook():

    req = request.get_json()

    log(req) 

    if req['object'] == ('page'):

        for entry in req['entry']:

            for messaging_event in entry['messaging']:

                # IDs
                # the facebook ID of the person sending you the message
                sender_id = messaging_event['sender']['id']
                # the recipient's ID, which should be your page's facebook ID
                recipient_id = messaging_event['recipient']['id'] 

                if messaging_event.get('message'):

                    # Extracting text message
                    if ('text') in messaging_event['message']:
                        messaging_text = messaging_event['message']['text'] 
                        sendMessage(PAT,sender_id,messaging_text)
                    else:
                        messaging_text = ('no text')
    return ("ok", 200)

def sendMessage(token, sender_id, text):

    """
    Invio messaggio di testo
    """

    json_data = {
        "recipient": {"id": sender_id},
        "message": {"text": text }
    }
    params = {
        "access_token": token
    }

    r = requests.post('https://graph.facebook.com/v2.6/me/messages', json=json_data, params=params)
    
    if r.status_code != requests.codes.ok:
       print (r.text)

def log(message):

    print(message)
    sys.stdout.flush()

# -*- coding: utf-8 -*-

import os, sys

from flask import Flask

from flask import request

import requests

import json

app = Flask(__name__)

#facebook page access data

PAT = (" ")

validationToken = ("testingEchoBot")

@app.route('/', methods=['GET'])

def verify():

# Webhook verification

if request.args.get("hub.mode") == "subscribe" and request.args.get("hub.challenge"):

if not request.args.get("hub.verify_token") == validationToken:

return ("Verification token mismatch", 403)

return request.args["hub.challenge"], 200

return ("webhook ok", 200)

@app.route('/', methods=['POST'])

def webhook():

req = request.get_json()

log(req)

if req['object'] == ('page'):

for entry in req['entry']:

for messaging_event in entry['messaging']:

# IDs

# the facebook ID of the person sending you the message

sender_id = messaging_event['sender']['id']

# the recipient's ID, which should be your page's facebook ID

recipient_id = messaging_event['recipient']['id']

if messaging_event.get('message'):

# Extracting text message

if ('text') in messaging_event['message']:

messaging_text = messaging_event['message']['text']

sendMessage(PAT,sender_id,messaging_text)

else:

messaging_text = ('no text')

return ("ok", 200)

def sendMessage(token, sender_id, text):

"""

Invio messaggio di testo

"""

json_data = {

"recipient": {"id": sender_id},

"message": {"text": text }

}

params = {

"access_token": token

}

r = requests.post('https://graph.facebook.com/v2.6/me/messages', json=json_data, params=params)

if r.status_code != requests.codes.ok:

print (r.text)

def log(message):

print(message)

sys.stdout.flush()

GET e POST

Le API Graph sono il metodo principale di lettura e scrittura di dati da Facebook attraverso delle semplici chiamate HTTP che restituiscono un messaggio di risposta con una struttura JSON.
Nel nostro caso utilizzeremo i due metodi GET e POST:

- GET ci permette di interrogare gli oggetti delle API Graph.
- POST di aggiornare o inserire oggetti.

Richieste di verifica

La documentazione ci suggerisce che come prima cosa dobbiamo inviare una richiesta GET per verificare l'endpoint utilizzando i parametri:

- hub.mode=subscribe
- hub.challenge: una stringa casuale.
- hub.verify_token: il token di verifica , cioè la stringa casuale che abbiamo utilizzato durante l'abilitazione del Webhook.

def verify():
 
    # richieste di verifica
 
    if request.args.get("hub.mode") == "subscribe" and request.args.get("hub.challenge"):
        if not request.args.get("hub.verify_token") == validationToken:
            return ("Verification token mismatch", 403)
        return request.args["hub.challenge"], 200

    return ("webhook ok", 200) #messaggio di verifica

def verify():

# richieste di verifica

if request.args.get("hub.mode") == "subscribe" and request.args.get("hub.challenge"):

if not request.args.get("hub.verify_token") == validationToken:

return ("Verification token mismatch", 403)

return request.args["hub.challenge"], 200

return ("webhook ok", 200) #messaggio di verifica

Quando l'endpoint riceve una richiesta di verifica controlla che hub.verify_token corrisponda al token di verifica che abbiamo inserito per l'abilitazione del webhook. Infine risponde con il valore hub.challenge in modo da sapere che l'endpoint è stato configurato correttamente (codice 200)

Access Token

Il meccanismo di autenticazione di Facebook è basato sul protocollo OAuth 2.0, quindi abbiamo bisogno di acquisire un access token cioè una stringa casuale che contiene informazioni sulla sua scadenza e sull'app che l'ha generata.
Il cui scopo è identificare la sessione associata al nostro echobot a cui verranno accordati i permessi per un determinato insieme di azioni.
Facebook ne utilizza di quattro tipologie:
- User Access Token
- App Access Token
- Token Client
- Page Access Token

Noi necessitiamo di quest'ultimo perché il nostro echoBot abbia accesso al Social Graph.

Nella sezione Generazione di token scegliamo la pagina Facebook da associare al echoBot ed in automatico verrà generata la stringa page access token che inseriremo nel listato.

#facebook page access data
PAT = (" ") #page access token  
validationToken = ("testingEchoBot") #verifica token

#facebook page access data

PAT = (" ") #page access token

validationToken = ("testingEchoBot") #verifica token

Ora nella sezione Webhooks e facendo click su Configura Webhooks apparirà una schermata come la seguente: "Nuova iscrizione della pagina".

L’indirizzo https di URL di callback lo abbiamo ottenuto prima attraverso Heroku, ora non dovremmo far altro che inserirlo. In verifica token possiamo scegliere una stringa qualsiasi a condizione che coincida con quella che utilizzeremo nel codice, nel nostro caso "testingEchoBot".
Ora dobbiamo accordare i permessi per la nostra applicazione nei campi relativi all'iscrizione selezionando:

- message, evento che avviene quando qualcuno invia un messaggio alla nostra pagina.
- message_deliveries, rapporti di consegna dei messaggi inviati.
- messaging_optins viene attivato quando qualcuno utilizza il plugin "invia a Facebook messenger".
- messaging_postbacks, eventi che si verificano ad esempio al tocco di un pulsante inizia o di un persistent menu.

Facciamo click su Verifica e Salva , se l’applicazione python su Heroku risponde correttamente ci dovrebbe appararire la seguente schermata.

Infine non dimentichiamo di effettuare l'iscrizione alla pagina facebook che abbiamo creato.

Invio messaggio di testo

Con questo metodo possiamo inviare semplici messaggi di testo con un limite di 640 caratteri con codifica
UTF-8. Da notare come l'oggetto messages abbia il suo ID nel Social Graph e che per accedervi abbiamo utizzato requests contattando l’indirizzo https://graph.facebook.com/

def sendMessage(token, sender_id, text):

    """
    Invio messaggio di testo
    """

    json_data = {
                 "recipient": {"id": sender_id},
                  "message": {"text": text }
               }
    params =  {
                "access_token": token
              }

    r = requests.post('https://graph.facebook.com/v2.6/me/messages', json=json_data, params=params)
    
    if r.status_code != requests.codes.ok:
       print (r.text)

def sendMessage(token, sender_id, text):

"""

Invio messaggio di testo

"""

json_data = {

"recipient": {"id": sender_id},

"message": {"text": text }

}

params = {

"access_token": token

}

r = requests.post('https://graph.facebook.com/v2.6/me/messages', json=json_data, params=params)

if r.status_code != requests.codes.ok:

print (r.text)

Step - 5 Now try it
Ora non dovete far altro che andare nella pagina che avete creato e testare l'echoBot

Lista degli errori

A questo punto, il nostro FB Messenger Bot non dovrebbe presentare problemi, ma le richieste che effettuiamo alle API Graph possono causare diverse tipologie di errori .

Bibliografia

[1] Mark Buchanan, Nexus, Perché la natura,la società, l'economia la comunicazione funzionano allo stesso modo, Mondadori, 2003
[2] Barabasi, Link, La nuova scienza delle reti, Einaudi, 2004
[3] Mark Buchanan, Atomo sociale, Mondadori,2008

Sitografia
[1] Kostis Tsaprailis, How to build and deploy a Facebook Messenger bot with Python and Flask, a tutorial, 2016

Documentazione ufficiale Heroku
[1] Getting Started on Heroku with Python
[2] Deploying Python Applications with Gunicorn
[3] Dynos and the Dyno Manager
[4] Heroku CLI

Documentazione ufficiale Facebook for developers
[1] Token d'accesso
[2] L'API Graph
[3] Messaggio di testo

Documentazione Conda
[1] Create Python 2 or 3 environments