Telegram — La Piattaforma per Bot Più Popolare

Telegram — La Piattaforma per Bot Più Popolare

Se hai mai usato Telegram, sai già perché è un posto fantastico per i bot. È veloce, funziona su qualsiasi dispositivo e ha una base di utenti enorme. Ma ecco il punto: Telegram non è solo un posto dove i bot esistono — è un posto dove il tuo Agente Hermes può davvero brillare.

Una volta collegato Hermes a Telegram, ottieni un bot conversazionale completo con cui puoi chattare da qualsiasi luogo. Invia un messaggio vocale e viene trascritto automaticamente. Chiedi un report programmato e arriva direttamente nella tua chat. Puoi persino aggiungere il bot alle chat di gruppo e farlo partecipare alla conversazione. Gestisce testo, voce, immagini e allegati — tutto tramite la solida libreria python-telegram-bot.

Vediamo la configurazione, passo dopo passo.

Passo 1: Crea il Tuo Bot con BotFather

Ogni bot di Telegram inizia con un token API da @BotFather, il gestore ufficiale dei bot di Telegram. Ecco come ottenere il tuo:

1. Apri Telegram e cerca @BotFather, oppure vai su t.me/BotFather
2. Invia /newbot
3. Scegli un nome visualizzato — qualsiasi cosa ti piaccia, tipo “Hermes Agent”
4. Scegli uno username — deve essere unico e terminare con bot (es. my_hermes_bot)
5. BotFather ti risponderà con il tuo token API, che assomiglia a questo:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Mantieni segreto il tuo token! Chiunque abbia questo token può controllare il tuo bot. Se dovesse mai trapelare, revocalo immediatamente con /revoke in BotFather.

Passo 2: Personalizza il Tuo Bot (Opzionale ma Ne Vale la Pena)

Alcuni comandi rapidi di BotFather possono rendere il tuo bot curato e professionale:

Comando	Scopo
/setdescription	Il testo “Cosa può fare questo bot?” mostrato prima che qualcuno inizi a chattare
/setabouttext	Breve testo nella pagina del profilo del bot
/setuserpic	Carica un avatar per il tuo bot
/setcommands	Definisci il menu dei comandi (il pulsante / nella chat)
/setprivacy	Controlla se il bot vede tutti i messaggi di gruppo (vedi Passo 3)

Per /setcommands, un buon set iniziale è:

help - Mostra le informazioni di aiuto
new - Inizia una nuova conversazione
sethome - Imposta questa chat come canale principale

Indicatore di Stato Online/Offline (Opzionale)

I bot di Telegram non hanno il puntino verde “online” come gli account utente. La cosa più simile è la descrizione breve del bot — la riga sotto il suo nome nella pagina del profilo.

Attiva status_indicator e Hermes imposterà quella descrizione su Online quando il gateway si connette e Offline allo spegnimento pulito:

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

Un paio di note: questa descrizione è globale (visibile a tutti gli utenti), e solo uno spegnimento pulito scrive “Offline” — un crash improvviso lascia l’ultimo stato. È disattivato di default perché modifica il profilo del tuo bot.

Priorità e Limite del Menu Comandi (Opzionale)

Hermes registra automaticamente il suo menu comandi quando il gateway Telegram si avvia. Di default, lo limita a 60 comandi — abbastanza per tutti i comandi integrati più le skill comuni. Se hai comandi di plugin che devono rimanere visibili nel selettore /, puoi dare loro priorità:

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

• prepend: i tuoi comandi prima, poi quelli di default di Hermes
• append: i default di Hermes prima, poi i tuoi
• replace: usa solo la tua lista per l’ordinamento di priorità

Telegram consente fino a 100 comandi, ma payload grandi possono fallire. Hermes usa 60 di default per affidabilità e limita i valori a 1..100.

Passo 3: Modalità Privacy — Fondamentale per i Gruppi

Ecco la fonte numero 1 di confusione quando si usano i bot nei gruppi: la modalità privacy è ATTIVA di default.

Con la modalità privacy ATTIVA, il tuo bot vede solo:

• Messaggi che iniziano con /
• Risposte ai messaggi del bot stesso
• Messaggi di servizio (ingressi, uscite, pin)
• Messaggi nei canali dove il bot è amministratore

Con la modalità privacy DISATTIVATA, il bot vede ogni messaggio nel gruppo.

Per disattivarla:

1. Scrivi a @BotFather
2. Invia /mybots
3. Seleziona il tuo bot
4. Vai su Bot Settings → Group Privacy → Turn off

Importante: Devi rimuovere e ri-aggiungere il bot a qualsiasi gruppo dopo aver modificato questa impostazione. Telegram memorizza nella cache lo stato della privacy quando il bot si unisce, e non lo aggiorna finché non viene ri-aggiunto.

Alternativa: Promuovi il bot ad amministratore del gruppo. I bot amministratori ricevono sempre tutti i messaggi, senza bisogno di modificare la privacy.

Osserva le Conversazioni di Gruppo Senza Rispondere Automaticamente

Vuoi che il tuo bot veda i messaggi di gruppo ma risponda solo quando viene menzionato? Configuralo così:

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

I messaggi non menzionati provenienti dalle chat consentite vengono aggiunti alla trascrizione della sessione come contesto osservato — ma non attivano l’agente. Solo una successiva menzione @nomebot attiva effettivamente una risposta.

---

Tutto qui! Con questi tre passaggi, hai un bot Telegram completamente funzionante alimentato da Hermes Agent. Vai avanti — inviagli un messaggio vocale, aggiungilo a un gruppo e guardalo fare la sua magia.