Come programmare l'invio di messaggi con un bot Telegram?

Perché programmare l'invio di messaggi con un bot Telegram

L'automazione della comunicazione è una delle esigenze più comuni per chi gestisce canali, gruppi o assistenza clienti su Telegram. Con un bot Telegram è possibile inviare messaggi in modo automatico a orari prestabiliti, senza dover intervenire manualmente ogni volta. Che si tratti di promemoria quotidiani, notifiche di sistema, newsletter o aggiornamenti periodici, programmare l'invio permette di risparmiare tempo e garantire puntualità.

In questo articolo vedremo come realizzare un bot in grado di spedire messaggi pianificati, utilizzando le API ufficiali di Telegram e strumenti di scheduling esterni. Il percorso è adatto sia a principianti che vogliono seguire passaggi precisi, sia a sviluppatori esperti che cercano soluzioni robuste e scalabili. Non inventeremo funzionalità inesistenti: tutto ciò che descriviamo è basato sulla documentazione pubblica e su pratiche consolidate.

Perché programmare l'invio di messaggi con un bot Telegram

Prerequisiti tecnici

Prima di iniziare è necessario disporre di:

Un account Telegram attivo – per creare e gestire il bot.
BotFather – il bot ufficiale di Telegram che permette di creare nuovi bot e ottenere il token di accesso.
Un ambiente di sviluppo – può essere un server Linux (VPS), un computer locale o un servizio cloud (es. Replit, PythonAnywhere).
Conoscenze base di programmazione – esempi in Python e Node.js, ma il concetto è applicabile ad altri linguaggi.

Non è richiesto alcun abbonamento a servizi a pagamento: l'API di Telegram è completamente gratuita. Attenzione però ai limiti di rate (30 messaggi al secondo per bot, con alcune eccezioni).

Creazione del bot con BotFather

Per ottenere il token del bot, avvia una chat con @BotFather su Telegram e usa il comando /newbot. Segui le istruzioni: scegli un nome (es. `PromemoriaSettimanale`) e uno username univoco che termina con “bot” (es. `PromemoriaSettimanaleBot`). Al termine riceverai un token HTTP API, una stringa di circa 40 caratteri che identifica il tuo bot. Conservalo in un luogo sicuro.

Con il token puoi già testare l'invio di messaggi via browser o con uno strumento come curl. Ad esempio:

curl -X POST https://api.telegram.org/bot<TOKEN>/sendMessage -d "chat_id=@tuocanale&text=Ciao mondo"

Se tutto funziona, sei pronto per la parte di scheduling.

Architettura di un bot con invio programmato

Un bot che invia messaggi a orari predefiniti non ha bisogno di ascoltare input 24/7 (a meno che non debba anche rispondere ai comandi). Per la sola pianificazione puoi adottare due approcci principali:

Polling vs Webhook

Il polling prevede che il bot interroghi periodicamente i server Telegram per ricevere gli aggiornamenti (messaggi, comandi). È semplice da implementare ma consuma risorse se eseguito in continuo. Per un bot che invia solo messaggi pianificati, non serve nemmeno: puoi semplicemente chiamare sendMessage all'ora desiderata senza dover mantenere una connessione persistente. Il webhook è utile se il bot deve reagire in tempo reale a messaggi degli utenti; per la programmazione non è necessario.

La scelta consigliata per un bot puramente schedulato è quella di eseguire uno script con un cron job (o equivalente) che al momento prefissato invia il messaggio e termina. Questo approccio è leggero, facile da monitorare e non richiede server sempre attivi (se usi un provider serverless).

Metodi di scheduling

Cron job su Linux

Il metodo più classico è usare cron su un server Unix-like. Scrivi uno script (Python, Node.js, Shell) che invii il messaggio e configuralo in crontab -e. Esempio per inviare ogni giorno alle 9:00:

0 9 * * * /usr/bin/python3 /home/utente/send_message.py

Lo script Python può essere semplice come:

import requests
TOKEN = "il_tuo_token"
CHAT_ID = "@tuocanale"
messaggio = "Buongiorno! Il bot vi augura una buona giornata."
url = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
p = {"chat_id": CHAT_ID, "text": messaggio}
requests.post(url, data=p)

Questo approccio funziona, ma ha alcuni svantaggi: devi gestire manualmente il server, assicurarti che lo script non fallisca (es. rete assente) e monitorare i log. Per installazioni piccole è più che sufficiente.

Servizi serverless e cloud scheduler

Se non vuoi gestire un server, puoi utilizzare piattaforme serverless come AWS Lambda con CloudWatch, Google Cloud Functions con Cloud Scheduler, o servizi più semplici come IFTTT (per operazioni basiche). Un esempio comune è usare GitHub Actions: crei un workflow che viene eseguito su un cron e chiama l'API Telegram. Ecco un workflow YAML di esempio:

name: Invia messaggio programmato
on:
  schedule:
    - cron: '30 8 * * 1-5'  # lun-ven alle 8:30 UTC
jobs:
  send:
    runs-on: ubuntu-latest
    steps:
      - name: Call Telegram API
        run: |
          curl -X POST https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN }}/sendMessage \
            -d "chat_id=${{ secrets.CHAT_ID }}&text=Promemoria: incontro alle 9:00"

Attenzione: GitHub Actions ha un limite di tempo di esecuzione (6 ore per workflow) e va bene per invii non troppo frequenti. Puoi anche usare servizi di scheduling gratuiti come cron-job.org, che eseguono una richiesta HTTP all'URL di un tuo endpoint. In quel caso devi avere un piccolo server web che riceve la richiesta e invia il messaggio.

Utilizzo di librerie bot con scheduler integrato

Se il tuo bot deve anche ascoltare comandi o interagire con gli utenti, potresti voler integrare lo scheduling direttamente nel codice del bot. Librerie come python-telegram-bot (v20+) offrono un JobQueue che permette di pianificare invii periodici. Esempio:

from telegram.ext import Application, JobQueue

async def send_scheduled(context):
    await context.bot.send_message(chat_id="@tuocanale", text="Messaggio pianificato")

application = Application.builder().token("TOKEN").build()
job_queue = application.job_queue
job_queue.run_repeating(send_scheduled, interval=86400, first=9*3600)  # ogni 24h dalle 9:00
application.run_polling()

In questo scenario il bot rimane in esecuzione continua e gestisce sia gli aggiornamenti sia i job programmati. È una soluzione elegante se devi anche rispondere ai comandi, ma consuma più risorse. Per invii puri, uno script cron è più semplice.

Considerazioni sui limiti di rate

Telegram impone limiti di invio per prevenire spam. Per bot normali, il limite è di 30 messaggi al secondo per chat; per messaggi verso canali o gruppi grandi, il limite può essere inferiore. Se devi inviare a molte chat contemporaneamente, distribuisci le chiamate nell'arco di qualche secondo. Inoltre, se il bot invia più di 20 messaggi al minuto a uno stesso utente, potresti incorrere in un ban temporaneo. Per messaggi programmati a un solo canale, questi limiti sono raramente un problema, ma tienili a mente se prevedi di inviare a molte destinazioni.

Un suggerimento pratico: aggiungi un ritardo tra le chiamate multiple (es. time.sleep(0.1)) e monitora le risposte API per gestire l'errore 429 (Too Many Requests).

Gestione degli errori e logging

Uno script di scheduling deve essere resiliente. Se la richiesta all'API fallisce (rete assente, token scaduto, chat_invalid), è importante registrare l'errore e, se possibile, riprovare. Implementa un semplice meccanismo di retry con backoff esponenziale. Esempio in Python:

import requests
from time import sleep

def send_message_safe(token, chat_id, text, retries=3):
    url = f"https://api.telegram.org/bot{token}/sendMessage"
    for i in range(retries):
        try:
            resp = requests.post(url, data={"chat_id": chat_id, "text": text}, timeout=10)
            if resp.status_code == 200:
                return True
            else:
                print(f"Errore: {resp.status_code} - {resp.text}")
        except requests.exceptions.RequestException as e:
            print(f"Tentativo {i+1} fallito: {e}")
            sleep(2**i)
    return False

Salva i log in un file o inviali a un servizio di monitoraggio. Per bot semplici, anche una stampa su stdout è sufficiente se hai il crond che inoltra la posta.

Invio di messaggi formattati e multimediali

Oltre al testo semplice, puoi programmare l'invio di immagini, documenti, sondaggi o messaggi con formattazione Markdown/HTML. L'API supporta i parametri parse_mode (HTML o MarkdownV2) e diversi tipi di media. Ad esempio per un'immagine:

curl -X POST https://api.telegram.org/botTOKEN/sendPhoto \
  -F chat_id=@tuocanale \
  -F photo=@/path/immagine.jpg \
  -F caption="Didascalia con grassetto" \
  -F parse_mode=HTML

Per i messaggi pianificati, assicurati che i file siano accessibili al bot (caricati localmente o tramite URL). Se usi un servizio serverless come AWS Lambda, devi includere i file statici nel pacchetto di deployment o utilizzare URL pubblici.

Invio di messaggi formattati e multimediali

Sicurezza e privacy

Il token del bot è la chiave di accesso. Non condividerlo mai pubblicamente e non includerlo in repository pubblici. Usa variabili d'ambiente o servizi di secret management (es. GitHub Secrets, AWS Secrets Manager). Inoltre, se il bot invia messaggi a un canale privato, assicurati che il bot sia amministratore del canale. Non inviare messaggi a chat non autorizzate; rispetta le policy di Telegram e le normative sulla privacy (es. GDPR se invii a utenti europei).

Risoluzione dei problemi comuni

Di seguito alcune situazioni frequenti e come affrontarle.

Sintomo	Possibile causa	Soluzione
Il messaggio non arriva	Token errato o chat_id sbagliato	Verifica il token con `getMe` e controlla che il bot sia membro del gruppo/canale.
Errore 403 Forbidden	Il bot non ha i permessi per scrivere nella chat	Aggiungi il bot come amministratore (canali) o membro (gruppi).
Il cron job non parte	Percorso assoluto dello script errato o variabili d'ambiente mancanti	Usa percorsi assoluti e testa lo script manualmente prima di inserirlo in crontab.
Rate limit superato	Troppe richieste in poco tempo	Introduci un ritardo o utilizza `sendMediaGroup` per inviare più messaggi insieme.

Esempio completo: promemoria quotidiano con Python e cron

Mettiamo insieme tutto in un esempio pratico. Supponiamo di voler inviare ogni mattina alle 8:30 un messaggio motivazionale a un canale Telegram. Creiamo uno script Python invia_motivazionale.py:

#!/usr/bin/env python3
import os
import requests
import sys

def main():
    token = os.environ.get("BOT_TOKEN")
    chat_id = os.environ.get("CHAT_ID")
    if not token or not chat_id:
        print("Mancano variabili d'ambiente")
        sys.exit(1)
    messaggio = "Ricorda: oggi è un'ottima giornata per imparare qualcosa di nuovo!"
    url = f"https://api.telegram.org/bot{token}/sendMessage"
    resp = requests.post(url, data={"chat_id": chat_id, "text": messaggio}, timeout=10)
    if resp.status_code == 200:
        print("Messaggio inviato con successo")
    else:
        print(f"Errore: {resp.status_code} {resp.text}")
        sys.exit(1)

if __name__ == "__main__":
    main()

Imposta le variabili d'ambiente nel crontab o in un file env. Aggiungi al crontab:

30 8 * * * cd /home/utente && python3 invia_motivazionale.py >> /var/log/bot_motivazionale.log 2>&1

Assicurati che lo script sia eseguibile e che il percorso di Python sia corretto. Il log ti aiuterà a debuggare eventuali fallimenti.

Quando evitare lo scheduling via bot

La programmazione di messaggi con un bot non è sempre la scelta migliore. Evita di usarla per:

Notifiche in tempo reale – se hai bisogno di latenze molto basse, meglio un webhook o un servizio di push.
Invii massivi a migliaia di utenti – rischi di superare i rate limit e causare blocchi. Per broadcast, considera l'API di Telegram per i canali (pubblica solo il canale).
Messaggi con contenuti che cambiano frequentemente – se il testo varia in base a dati live, lo scheduling potrebbe non catturare l'ultimo aggiornamento; allora meglio un trigger su evento.

FAQ

Posso programmare l'invio di messaggi a più chat contemporaneamente?

Sì, puoi iterare una lista di chat_id e inviare a ciascuna. Presta attenzione ai rate limit: invia in sequenza con un piccolo ritardo (es. 0.2 secondi) per evitare blocchi. Esempio: se hai 10 chat, un ciclo con sleep(0.3) tra una richiesta e l'altra mantiene il flusso sotto i 30 msg/s.

È necessario tenere il bot sempre online?

No, per la sola pianificazione puoi usare uno script che viene eseguito al momento desiderato e termina. Se invece hai bisogno di comandi interattivi, allora devi mantenere il processo in esecuzione. Per un bot che fa entrambe le cose, l'approccio con JobQueue (python-telegram-bot) unisce scheduling e ascolto in un unico processo.

Come faccio a testare lo scheduling senza attendere l'orario previsto?

Esegui manualmente lo script con un orario fittizio. Se usi cron, modifica temporaneamente l'orario in ' * * * * ' per eseguirlo ogni minuto. Ricordati di ripristinarlo dopo il test. In alternativa, puoi impostare una variabile d'ambiente di debug che forza l'invio immediato.

Il bot può inviare messaggi a utenti privati senza che questi abbiano avviato una chat?

No, per inviare un messaggio a un utente privato, quest'ultimo deve prima aver avviato una conversazione con il bot (inviare il comando /start). Per i canali e i gruppi, il bot deve essere membro e avere i permessi di scrittura.

Quale linguaggio è migliore per uno script di scheduling?

Python è il più usato per la sua semplicità e librerie. Anche Node.js e Go sono validi. La scelta dipende dall'ambiente; l'importante è che lo script possa essere eseguito da un cron job o da un trigger serverless. Se usi AWS Lambda, Node.js può essere più integrato, ma Python è altrettanto supportato.

Conclusioni e best practice

Programmare l'invio di messaggi con un bot Telegram è un'attività alla portata di qualsiasi sviluppatore, una volta compresi i meccanismi base delle API e dello scheduling. Ricapitoliamo i punti chiave:

Usa il metodo più semplice per il tuo caso: uno script con cron è spesso sufficiente per invii singoli o a un canale.
Gestisci gli errori: non dare per scontato che la richiesta vada sempre a buon fine.
Proteggi il token: variabili d'ambiente e repository privati.
Monitora i log: per debug rapido.
Rispetta i limiti di rate: pianifica di conseguenza.

Con questi strumenti puoi automatizzare promemoria, annunci, notifiche e molto altro, liberando tempo per attività più creative. Ora non ti resta che creare il tuo bot e iniziare a sperimentare.