GOLEM Telegram Bot - Cronologia

Giomba: aggiornamenti sulla dockerizzazione

2020-12-06T13:32:03Z

aggiornamenti sulla dockerizzazione

Giulio: Aggiunta guida d'uso -- documentazione in scrittura

2018-01-13T22:10:28Z

Aggiunta guida d'uso -- documentazione in scrittura

Giulio: /* Cosa fa il nostro bot */ Appuntate alcune delle nuove funzionalità -- da rivedere

2017-09-25T10:26:06Z

Cosa fa il nostro bot: Appuntate alcune delle nuove funzionalità -- da rivedere

Giomba: Aggiornamenti sul codice github e il VPS

2017-09-24T20:49:50Z

Aggiornamenti sul codice github e il VPS

Giomba: Pagina categorizzata

2017-09-16T20:57:50Z

Pagina categorizzata

Giomba il 16:07, 29 lug 2016

2016-07-29T16:07:27Z

Giomba: Creata pagina con 'Il bot Telegram del GOLEM è in fase di '''testing''', e per ora il codice sorgente può essere consultato solamente dai nostri soci attraverso l'interfaccia WebDav di ILS opp...'

2016-07-28T21:00:44Z

Creata pagina con 'Il bot Telegram del GOLEM è in fase di '''testing''', e per ora il codice sorgente può essere consultato solamente dai nostri soci attraverso l'interfaccia WebDav di ILS opp...'

Nuova pagina

Il bot Telegram del GOLEM è in fase di '''testing''', e per ora il codice sorgente può essere consultato solamente dai nostri soci attraverso l'interfaccia WebDav di ILS oppure su richiesta.

== Creare un BOT ==
Aprire una chat col bot [https://telegram.me/botfather BotFather] e creare un nuovo bot seguendo le intuitive istruzioni interattive. Generare anche il ''token''. Il token è un codice casuale, ma univoco una volta creato, che serve agli sviluppatori per accedere al bot.

È una cosa brutta che assomiglia a questo:
110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

== Contattare il bot tramite token ==
Costruire un URL tipo questo: https://api.telegram.org/bot''TOKEN''/''metodo''
* ''TOKEN'' è ovviamente il token che abbiamo generato
* ''metodo'' è l'operazione che vogliamo effettuare

Ne esistono tante [https://core.telegram.org/bots/api], noi ne vedremo alcune che ci servono.

=== getMe ===
Ottiene informazioni sul bot. Lo usiamo per vedere se i server di Telegram funzionano.
Esempio di URL da consultare:
https://api.telegram.org/bot110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw/getMe

Riceveremo in risposta un documento JSON che possiamo facilmente interpretare tramite Python o PHP per estrapolare le varie informazioni attraverso il nostro programma.

== Ricevere gli aggiornamenti ==
Quando qualcuno scrive al bot, il messaggio viene inviato ai server di Telegram, che lo mantengono per un certo periodo (max 24 ore). Per leggerlo tramite il nostro bot (il nostro programma) esistono due modi:
* query attiva via HTTP (getUpdates): a intervalli regolari, il nostro programma interroga i server di Telegram per sapere se c'è un nuovo messaggio. CONTRO: è grande spreco di risorse; PRO: utile per fare debugging;
* query passiva via HTTP (WebHook): quando i server di Telegram ricevono un messaggio per il bot, saranno loro a contattare il nostro programma via HTTP; PRO: non spreca risorse CONTRO: necessità di un server web dedicato e debugging più ostico.

Alla fine, la soluzione con query passiva WebHook è decisamente quella più sensata.

Mentre si usa un WebHook non si può usare il getUpdates, e viceversa (ma va?).

== WebHook ==
Per impostare un WebHook bisogna usare il metodo ''setWebhook'', con una cosa del genere:
https://api.telegram.org/bot110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw/setWebhook?url=

Se lasciamo ''url='' vuoto in questo modo, cancelliamo il WebHook e Telegram non contatterà il nostro programma quando il nostro bot riceverà un messaggio. Utile per tornare nella modalità getUpdates e fare debugging.

Altrimenti, dobbiamo specificare l'URL a cui si trova il nostro programma, per esempio:
https://api.telegram.org/bot110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw/setWebhook?url=https://golem.linux.it/directory/bot.php

Ovviamente non è quello, mica siamo così citrulli da scriverlo qui! :-)
È meglio usare URL con nomi strani e caratteri casuali, così si evita che qualcuno possa ''inavvertitamente'' (o intenzionalmente) usare il nostro programma a sproposito.
Siccome ci fa fatica pensare a dei caratteri casuali, facciamoci aiutare da questo comando:
dd if=/dev/urandom bs=1 count=12 | base64

== Certificato SSL ==
'''Importante:''' tutte le query devono avvenire attraverso HTTPS (HTTP su SSL). Si può acquistare un certificato (sganciando parecchi euri), si può generare con [https://letsencrypt.org/ Let's Encrypt] oppure si può generare in locale e autofirmarlo (self-signed). La prima soluzione è la più immediata e costosa, la seconda e la terza sono meno immediate ma sono gratuita (free as in free beer, che non è poi così male).

Generiamo il nostro certificato [https://core.telegram.org/bots/self-signed]:
openssl req -newkey rsa:2048 -sha256 -nodes -keyout golem.linux.it.key -x509 -days 720 -out golem.linux.it.pem -subj "/C=IT/ST=Italy/L=Florence/O=GruppoLinuxEmpoli/CN=golem.linux.it"

* ''-days 720'' imposta la scadenza (nel caso specifico, tra due anni)
* ''-keyout golem.linux.it.key'' specifica il nome del file su cui verrà scritta la nostra chiave privata (da custodire '''gelosamente''')
* ''-out golem.linux.it.pem'' specifica il nome del file su cui verrà scritta la nostra chiave pubblica (che manderemo a Telegram)

E impostiamo il nostro webserver per usarlo come certificato per l'HTTPS. Per esempio, ecco qui come farlo su [http://www.glgprograms.it/?p=tricks/raspberrypi-8 Apache].

Mandiamo a Telegram la nostra chiave pubblica effettuando una richiesta HTTP di tipo POST invece che GET, con lo stesso URL di prima, e ovviamente allegando il nostro certificato pubblico. Per farlo possiamo usare ''curl'' con questo praticissimo comando:
curl -F "url=https://golem.linux.it/directory/bot.php" -F "certificate=@golem.linux.it.pem" https://api.telegram.org/bot110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw/setWebhook

Il comando dovrebbe restituire un messaggio di successo dai server di Telegram.

Come doppio controllo, controlliamo che tutto funzioni davvero provando il metodo ''getUpdates'': deve dare errore perché abbiamo impostato il WebHook.

== Programma ==
Scriviamo il nostro programma (per esempio in PHP) e mettiamolo all'URL appena indicato a Telegram. Mandiamo un messaggio al nostro bot, e notiamo che il nostro script viene contattato (possiamo controllare ''/var/log/apache2/access.log'' per vedere se davvero viene chiamato. Si può usare ''tail -f'' su quel file per controllarlo in tempo reale)

A questo punto il nostro programma non deve far altro che leggere il JSON che gli è stato inviato tramite HTTP POST e decidere cosa fare. Il JSON contiene il messaggio e tutti i metadati relativi ad esso (presenza di link, emoticon, allegati come foto, video, ecc...) e per il suo contenuto ci sono varie strutture documentate [https://core.telegram.org/bots/api#making-requests].

== Cosa fa il nostro bot ==
Il nostro bot riceve messaggi da chiunque, ma prende in considerazione solo quelli provenienti dagli utenti che noi abilitiamo (per ragioni che saranno ovvie presto).

Il messaggio viene sempre inoltrato al nostro canale su Telegram, indipendentemente dal contenuto.
Se il messaggio contiene un URL, allora si suppone che il link sia adatto per la mailing list, e allora viene analizzato, e se punta ad una pagina HTML con un campo ''title'' valido, viene inoltrato sulla nostra mailing list tradizionale.

'''Oss:''' abbiamo scelto di non mettere un comando per far ciò per snellire il processo di condivisione.

Infine, un altro script indipendente osserva i cambiamenti sul feed RSS del nostro blog Wordpress, e quando ci sono dei nuovi articoli li inoltra sulla mailing list e sul canale.

@@ Riga 4: / Riga 4: @@
 * ''Documentazione:'' una rapida descrizione del codice del GOLEM BOT
-Il BOT del GOLEM provvede ad indirizzare messaggi, foto e video sul canale dell'associazione, permettendo anche di pianificarne l'invio in momenti successivi. È in fase di '''testing''', al momento sta correttamente funzionando sul nostro VPS.
+Il BOT del GOLEM provvede ad indirizzare messaggi, foto e video sul [https://web.telegram.org/#/im?p=@golem_empoli canale Telegram dell'associazione], permettendo anche di controllare chi può inviare i messaggi e pianificarne l'invio in momenti successivi.
-Il codice sorgente può essere consultato su [https://github.com/GolemEmpoli/golem-telegram-bot github].
+'''Nota:''' da gennaio 2020, la funzionalità di invio differito è integrata nell'applicazione ufficiale.
 = Guida d'uso =
- Attenzione! Il BOT sta ancora funzionando "alla vecchia maniera". È necessario richiedere l'abilitazione per utilizzare la nuova interfaccia
+Il BOT è raggiungibile col nome [http://t.me/GOLEMpoliBot @GOLEMpoliBot], naturalmente riceve messaggi da chiunque, ma prende in considerazione solo quelli provenienti dagli utenti da noi abilitati.
 I restanti utenti saranno indirizzati verso il [http://t.me/golem_empoli canale].
 La prima volta che viene contattato, il BOT si presenta illustrando funzionalità e comandi.
@@ Riga 103: / Riga 107: @@
 A questo punto il nostro programma non deve far altro che leggere il JSON che gli è stato inviato tramite HTTP POST e decidere cosa fare. Il JSON contiene il messaggio e tutti i metadati relativi ad esso (presenza di link, emoticon, allegati come foto, video, ecc...) e per il suo contenuto ci sono varie strutture documentate [https://core.telegram.org/bots/api#making-requests].
 Il BOT inoltra sul canale qualsiasi messaggio, a patto che il mittente sia fra gli utenti autorizzati.
@@ Riga 116: / Riga 119: @@
 Tempo stimato per la condivisione: 3 secondi. Immediatezza d'uso: 1 Googol (circa 10<sup>100</sup>)
-Un secondo script viene lanciato ogni ora dal server, controlla se ci sono messaggi pianificati, eventualmente li invia e li rimuove dalla pila.
+Un secondo script viene lanciato ogni ora dal server, controlla se ci sono messaggi pianificati, eventualmente li invia e li rimuove dalla coda.
 ==Più nel dettaglio==

@@ Riga 1: / Riga 1: @@
-Il bot Telegram del GOLEM è in fase di '''testing'''.
+Su questa pagina si trovano...
 Il codice sorgente può essere consultato su [https://github.com/GolemEmpoli/golem-telegram-bot github].
-Al momento tutto sta correttamente funzionando sul nostro VPS.
+= Guida d'uso =
-== Creare un BOT ==
+Il BOT è raggiungibile col nome [http://t.me/GOLEMpoliBot @GOLEMpoliBot], naturalmente riceve messaggi da chiunque, ma prende in considerazione solo quelli provenienti dagli utenti da noi abilitati. I restanti utenti saranno indirizzati verso il [http://t.me/golem_empoli canale].
 Aprire una chat col bot [https://telegram.me/botfather BotFather] e creare un nuovo bot seguendo le intuitive istruzioni interattive. Generare anche il ''token''. Il token è un codice casuale, ma univoco una volta creato, che serve agli sviluppatori per accedere al bot.
@@ Riga 72: / Riga 103: @@
 A questo punto il nostro programma non deve far altro che leggere il JSON che gli è stato inviato tramite HTTP POST e decidere cosa fare. Il JSON contiene il messaggio e tutti i metadati relativi ad esso (presenza di link, emoticon, allegati come foto, video, ecc...) e per il suo contenuto ci sono varie strutture documentate [https://core.telegram.org/bots/api#making-requests].
-== Cosa fa il nostro bot ==
+Un esempio semplice da studiare e facilmente replicabile è la [https://github.com/GolemEmpoli/golem-telegram-bot/releases/tag/v0.99-alpha versione 0.99] del GOLEM BOT, reperibile su GitHub.
-Il nostro bot è raggiungibile col nome @GOLEMpoliBot, naturalmente riceve messaggi da chiunque, ma prende in considerazione solo quelli provenienti dagli utenti che noi abilitiamo (per ragioni che saranno ovvie presto).
+Il BOT inoltra sul canale qualsiasi messaggio, a patto che il mittente sia fra gli utenti autorizzati.
 Con l'ultima versione di codice il bot si comporta come segue: se è ricevuto del testo puro oppure un'immagine, viene richiesto mediante tastiera inline se si vuole inoltrare il contenuto al nostro canale Telegram, se si vuole programmare l'invio per il futuro oppure se si vuol annullare l'operazione.
 Il caso di invio programmato compaiono di seguito un calendario ed una lista di orari che consentono la pianificazione.
@@ Riga 87: / Riga 119: @@
-===Più nel dettaglio===
+==Più nel dettaglio==
   Attenzione: si tratta, allo stato attuale, di appunti sparsi in fase di scrittura
@@ Riga 101: / Riga 133: @@
 Il problema della perdita delle variabili che si ha fra un messaggio e l'altro è stato risolto mediante <code>Memcached</code>, un demone che permette di salvare o recuperare variabili in uno spazio di memoria condiviso. Si è stabilito che ogni variabile relativa ad un certo utente debba essere salvata nella forma <code>''codice_utente''-''nome_variabile''</code>.
-Ogni volta che il bot viene sollecitato lo script verifica che tipo di sollecitazione è stata fatta (callback, messaggio...) e si procede all'interpretazione dei dati. Vengono scartate richieste provenienti dagli utenti non autorizzati (che sono bacchettati con un messaggio di errore), da gruppi o dal canale stesso.
+Ogni volta che il bot viene sollecitato lo script verifica che tipo di sollecitazione è stata fatta (callback, messaggio...) e si procede all'interpretazione dei dati. Vengono scartate richieste provenienti dagli utenti non autorizzati (che sono indirizzati verso il canale), da gruppi o dal canale stesso.
-Dopodiché viene recuperato lo stato in cui il bot si trova (relativo all'utente che ha sollevato la sollecitazione) e il percorso prosegue seguendo la macchina a stati.
+Dopodiché viene recuperato lo stato in cui il bot si trova (relativo all'utente che ha lanciato la sollecitazione) e il percorso prosegue seguendo la macchina a stati.
 [[Category:Officina]]
 [[Category:Howto]]

@@ Riga 75: / Riga 75: @@
 Il nostro bot è raggiungibile col nome @GOLEMpoliBot, naturalmente riceve messaggi da chiunque, ma prende in considerazione solo quelli provenienti dagli utenti che noi abilitiamo (per ragioni che saranno ovvie presto).
-Il messaggio viene sempre inoltrato al nostro canale su Telegram, indipendentemente dal contenuto.
+Con l'ultima versione di codice il bot si comporta come segue: se è ricevuto del testo puro oppure un'immagine, viene richiesto mediante tastiera inline se si vuole inoltrare il contenuto al nostro canale Telegram, se si vuole programmare l'invio per il futuro oppure se si vuol annullare l'operazione.
-Se il messaggio contiene un URL, allora si suppone che il link sia adatto per la mailing list, e allora viene analizzato, e se punta ad una pagina HTML con un campo ''title'' valido, viene inoltrato anche sulla nostra mailing list tradizionale.
+Il caso di invio programmato compaiono di seguito un calendario ed una lista di orari che consentono la pianificazione.
-'''Oss:''' a proposito di questo uso "strano" del bot, abbiamo scelto di scrivere direttamente a lui e non di fargli leggere i comandi all'interno del nostro gruppo per snellire il processo di condivisione.
+Il bot accetta anche alcuni comandi, come <code>/help</code> per avere rapide informazioni sul funzionamento e <code>/list</code> per prendere visione dei messaggi pianificati.
-Così, per condividere un link interessante, basterà inviarlo al bot e lui penserà a inoltrarlo ai canali di comunicazione giusti, senza necessità di usare comandi strani.
 Tempo stimato per la condivisione: 3 secondi. Immediatezza d'uso: 1 Googol (circa 10<sup>100</sup>)
-Infine, un altro script indipendente osserva i cambiamenti sul feed RSS del nostro blog Wordpress, e quando ci sono dei nuovi articoli li inoltra sulla mailing list e sul canale. Di nuovo, penserà a tutto lui.
+Un secondo script viene lanciato ogni ora dal server, controlla se ci sono messaggi pianificati, eventualmente li invia e li rimuove dalla pila.
 [[Category:Officina]]
 [[Category:Howto]]

@@ Riga 1: / Riga 1: @@
-Il bot Telegram del GOLEM è in fase di '''testing''', e per ora il codice sorgente può essere consultato solamente dai nostri soci attraverso l'interfaccia WebDav di ILS oppure su richiesta.
+Il bot Telegram del GOLEM è in fase di '''testing'''.
-'''Temporaneamente''', tutto gira sul server di [[Utente:Giomba|giomba]], almeno finché non avremo sistemato la questione del VPS.
 == Creare un BOT ==

← Versione meno recente		Versione delle 20:57, 16 set 2017
Riga 81:		Riga 81:

	Infine, un altro script indipendente osserva i cambiamenti sul feed RSS del nostro blog Wordpress, e quando ci sono dei nuovi articoli li inoltra sulla mailing list e sul canale. Di nuovo, penserà a tutto lui.		Infine, un altro script indipendente osserva i cambiamenti sul feed RSS del nostro blog Wordpress, e quando ci sono dei nuovi articoli li inoltra sulla mailing list e sul canale. Di nuovo, penserà a tutto lui.
		+
		+	[[Category:Officina]]
		+	[[Category:Howto]]