Come si crea un bot su Telegram per automatizzare l'invio di messaggi?

Introduzione: perché automatizzare l'invio di messaggi con un bot Telegram

I bot Telegram sono programmi che eseguono azioni in modo autonomo all'interno della piattaforma, dalla risposta a comandi all'invio programmato di notifiche. Creare un bot per l'invio automatico di messaggi apre scenari che spaziano dalla distribuzione di contenuti editoriali a promemoria interni al team, fino all'integrazione con sistemi di monitoring. L'intero processo si basa su due pilastri: la registrazione del bot tramite BotFather, il bot ufficiale di Telegram per la gestione dei bot, e l'utilizzo dell'API HTTP, che permette di inviare messaggi in modo semplice e sicuro. In questa guida percorreremo ogni fase, dalla creazione del bot alla scrittura del primo script di automazione, evidenziando le scelte cruciali e gli errori da evitare per ottenere una soluzione affidabile e manutenibile.

Prerequisiti per iniziare

Prima di addentrarci nella procedura, è necessario disporre di un account Telegram attivo, sia su mobile che su desktop. La registrazione del bot avviene attraverso il client mobile o desktop, ma la gestione successiva può essere fatta da qualsiasi piattaforma. Dal punto di vista tecnico, è utile avere familiarità con un ambiente di sviluppo per linguaggi come Python, Node.js o PHP; in questo articolo utilizzeremo Python per la sua semplicità e diffusione. Non è richiesta alcuna esperienza pregressa con l'API di Telegram, ma la conoscenza di base delle richieste HTTP (GET e POST) agevolerà la comprensione. Assicurati di avere installato Python 3.8 o superiore e il modulo requests (installabile con pip install requests).

Creazione del bot con BotFather

Apri Telegram e cerca il contatto ufficiale BotFather. Avvia una chat e digita il comando /newbot. BotFather ti chiederà di scegliere un nome per il bot (quello che gli utenti vedranno) e un username univoco, che deve terminare con 'bot' (es. MioBotEsempio_bot). Una volta completata la registrazione, riceverai un messaggio di conferma che contiene il token API, una stringa alfanumerica che identifica il tuo bot e che utilizzerai per autenticare tutte le richieste. Conserva questo token in un luogo sicuro, poiché chiunque lo possieda può controllare il bot. Se perdi il token, puoi rigenerarlo in qualsiasi momento con il comando /token sempre da BotFather. Dopo la creazione, puoi personalizzare il bot: imposta una descrizione con /setdescription, un'immagine del profilo con /setuserpic e, se lo desideri, un elenco di comandi predefiniti con /setcommands. Questi passaggi sono facoltativi ma migliorano l'esperienza utente.

Primo script: inviare un messaggio semplice

Una volta ottenuto il token, puoi inviare messaggi utilizzando l'endpoint sendMessage dell'API Telegram. L'URL base è https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage. Per esempio, in Python:

import requests
import os

token = os.getenv('TELEGRAM_BOT_TOKEN')  # meglio non hardcodare
chat_id = '123456789'  # ID del destinatario
url = f'https://api.telegram.org/bot{token}/sendMessage'
payload = {'chat_id': chat_id, 'text': 'Ciao, questo è un messaggio automatico!'}
response = requests.post(url, data=payload)
print(response.json())

Il parametro chat_id può essere l'ID di un utente, di un gruppo o di un canale. Per ottenere l'ID del tuo account o di un gruppo, puoi utilizzare bot come IDBot (cercalo su Telegram) o inviare un messaggio al bot e poi leggere l'aggiornamento tramite l'endpoint getUpdates. In ambiente di sviluppo, è consigliabile testare con un gruppo privato prima di passare alla produzione.

Automazione periodica: inviare messaggi a orari prestabiliti

Per automatizzare l'invio in modo regolare, puoi eseguire lo script tramite un cron job (su Linux/macOS) o il Task Scheduler (su Windows). Imposta l'intervallo desiderato (es. ogni giorno alle 8:00) e assicurati che lo script sia eseguibile e che il token sia accessibile come variabile d'ambiente. Un esempio di riga cron per eseguire lo script ogni giorno alle 9:00:

0 9 * * * /usr/bin/python3 /percorso/script.py

In alternativa, per scenari più complessi (invio condizionale, interazione con database), puoi utilizzare un webhook. Telegram supporta la possibilità di ricevere notifiche quando un utente interagisce con il bot, ma per l'invio autonomo di messaggi non è necessario un webhook: un semplice script schedulato è sufficiente. Tuttavia, se il bot deve rispondere a comandi o gestire input, il webhook diventa la scelta migliore per ridurre la latenza e il carico di polling.

Gestione degli errori e logging

Un'automazione affidabile richiede una gestione robusta degli errori. L'API di Telegram può restituire codici di errore HTTP (es. 429 per troppe richieste, 403 per chat bloccata). È buona pratica implementare un meccanismo di retry con backoff esponenziale e registrare i log in un file. In Python, puoi usare il modulo logging per tenere traccia di ogni invio e di eventuali fallimenti. Ad esempio:

import logging
import time
import requests

logging.basicConfig(filename='bot.log', level=logging.INFO)

def send_message(token, chat_id, text, retries=3):
    for attempt in range(retries):
        try:
            resp = requests.post(url, data={'chat_id': chat_id, 'text': text}, timeout=10)
            if resp.status_code == 200:
                logging.info(f'Messaggio inviato a {chat_id}: {text[:30]}...')
                return
            elif resp.status_code == 429:
                wait = int(resp.json().get('parameters', {}).get('retry_after', 5))
                logging.warning(f'Rate limit: attendo {wait} secondi')
                time.sleep(wait)
            else:
                logging.error(f'Errore {resp.status_code}: {resp.text}')
        except requests.exceptions.Timeout:
            logging.warning(f'Tentativo {attempt+1} fallito per timeout')
            time.sleep(2**attempt)
    logging.error('Tutti i tentativi esauriti')

Sicurezza e buone pratiche

Il token del bot è la chiave di accesso al tuo bot: non deve mai essere condiviso pubblicamente, né incluso in repository Git o in codice lato client. Usa variabili d'ambiente o un vault di segreti. Limita le autorizzazioni del bot: per l'invio di messaggi è sufficiente la capacità di scrivere in chat o canali; non è necessario che il bot sia amministratore se non per funzioni specifiche (es. eliminare messaggi). Quando invii messaggi a canali o gruppi, assicurati che il bot sia stato aggiunto come membro e che abbia i permessi necessari. Per i canali, il bot deve essere amministratore per poter pubblicare. Inoltre, considera che l'API di Telegram impone limiti di frequenza (rate limit): non più di 30 messaggi al secondo per chat (limite teorico) e circa 20 messaggi al minuto per bot su larga scala. Oltre questi limiti, potresti ricevere errori 429. Pianifica l'invio con pause o utilizza la libreria telegram (python-telegram-bot) che gestisce automaticamente il throttling.

Invio di messaggi a canali e gruppi

Per automatizzare l'invio a un canale, devi rendere il bot amministratore del canale stesso. Aggiungi il bot al canale, vai nelle impostazioni del canale, seleziona 'Amministratori', aggiungi il bot e assegna almeno il permesso di 'Inviare messaggi'. L'ID del canale può essere ottenuto inviando un messaggio al bot e poi chiamando getUpdates, oppure utilizzando il formato @nomecanale (funziona solo se il bot è amministratore). Per i gruppi, il bot deve essere aggiunto come membro; se il gruppo è pubblico, puoi ottenere l'ID tramite l'URL del gruppo. In entrambi i casi, il parametro chat_id può essere un numero negativo (per i gruppi) o un numero positivo (per gli utenti).

Automazione avanzata con webhook e bot interattivi

Sebbene l'invio programmato non richieda un webhook, se il tuo bot deve anche rispondere a comandi o eseguire azioni in base a input esterni, impostare un webhook diventa fondamentale. Il webhook permette a Telegram di inviare una richiesta POST al tuo server ogni volta che il bot riceve un messaggio o un comando. Per impostare un webhook, usa l'endpoint setWebhook con l'URL del tuo server (deve essere HTTPS). Puoi utilizzare servizi come Heroku, AWS Lambda o un VPS per ospitare il bot. In questo caso, l'automazione dell'invio può essere integrata nel flusso di risposta: ad esempio, quando un utente invia un comando /invia_ora, il bot potrebbe inviare un messaggio a un canale. Tuttavia, per l'invio puramente autonomo e non legato all'interazione, lo scheduler rimane la soluzione più semplice e leggera.

Errori comuni e come evitarli

Uno degli errori più frequenti è dimenticare di aggiungere il bot come amministratore del canale, ottenendo un errore 403 Forbidden. Un altro è confondere il formato dell'ID chat: per i gruppi, l'ID è un numero negativo (es. -123456789), mentre per gli utenti è positivo. Inoltre, il token deve essere passato correttamente nell'URL: l'URL corretto è https://api.telegram.org/bot<TOKEN>/sendMessage (nota: 'bot' preposto al token, senza spazio). Se lo script non produce output, verifica che il modulo requests sia installato e che la connessione a Internet sia attiva. Infine, tieni presente che l'API di Telegram può restituire un errore 400 se il messaggio è troppo lungo (limite di 4096 caratteri per messaggio). Per messaggi più lunghi, suddividi il testo in più invii.

Limitazioni e considerazioni sui volumi

L'API di Telegram non prevede costi, ma impone limiti di frequenza. Per invii a migliaia di utenti, è necessario distribuire le richieste nel tempo o utilizzare tecniche di broadcast tramite topic. Inoltre, i bot non possono inviare messaggi a utenti che non hanno avviato una conversazione con il bot, a meno che il bot non sia stato aggiunto a un gruppo in cui l'utente è presente. Questo vincolo è importante in caso di newsletter automatizzate: è richiesto un opt-in esplicito. Per canali, invece, non è necessario che i singoli iscritti interagiscano con il bot; il bot pubblica come amministratore. Se prevedi un volume molto elevato, considera l'uso di un bot separato per ogni canale o la distribuzione su più token.

Domande frequenti

Conclusione e passi successivi

Creare un bot Telegram per l'invio automatico di messaggi è un processo accessibile che richiede pochi passaggi: registrazione via BotFather, scrittura di uno script leggero e schedulazione. Con le buone pratiche illustrate (gestione sicura del token, logging, gestione errori, rispetto dei limiti di frequenza) si ottiene una soluzione stabile adatta a molti casi d'uso, dalla distribuzione di notizie a promemoria interni. Per chi desidera approfondire, il passo successivo è l'integrazione di comandi interattivi e l'uso di webhook per creare bot più complessi. La documentazione ufficiale di Telegram a core.telegram.org/bots/api è la risorsa di riferimento per ogni dettaglio. Prova a creare il tuo primo bot oggi stesso e automatizza la comunicazione in modo semplice e potente.