Guida all'API di Telegram Bot: crea il tuo primo bot

Il tutorial più rapido per l’API di Telegram Bot si riassume in tre comandi: ottieni un token da BotFather, chiama getUpdates per leggere i messaggi e sendMessage per rispondere. Tutto il resto nello sviluppo di bot si basa su questo ciclo. Questa guida ti accompagnerà attraverso l’intero percorso, dalla tua prima richiesta cURL a un bot funzionante con un webhook e una libreria.

L’API Bot è un’interfaccia HTTP, il che significa che puoi testarla con curl prima di scrivere una singola riga di codice applicativo. Questo la rende una delle API più facili da imparare. Se sei uno sviluppatore che desidera un bot funzionante oggi, o un costruttore che valuta il codice rispetto a una piattaforma no-code come TeleClaw, sei nel posto giusto.

Alla fine capirai come l’API autentica le richieste, come ricevere e inviare messaggi, la differenza tra long polling e webhook, e i limiti di frequenza che mettono in difficoltà la maggior parte dei primi bot.

Punti chiave

• Un bot è solo un client HTTP. Ogni metodo è una richiesta a https://api.telegram.org/bot<TOKEN>/METHOD_NAME, quindi cURL è sufficiente per iniziare.
• Tre metodi fondamentali ti fanno partire: getMe per verificare il token, getUpdates per leggere i messaggi e sendMessage per rispondere.
• Long polling e webhook sono mutualmente esclusivi. Fai polling per i test locali, passa a un webhook per la produzione.
• L’API è gratuita, ma Telegram limita l’invio massivo a circa 30 messaggi al secondo a utenti diversi e uno al secondo per chat.
• Una libreria ti fa risparmiare tempo una volta che il tuo bot cresce oltre un semplice script. Usa python-telegram-bot, aiogram o Telegraf.

Cos’è l’API di Telegram Bot?

L’API di Telegram Bot è un’interfaccia basata su HTTP per connettere il tuo codice a Telegram tramite un bot. Secondo l’introduzione per sviluppatori di Telegram, i bot sono account speciali che non richiedono un numero di telefono e servono come interfaccia per il codice in esecuzione sul tuo server.

Ogni richiesta che effettui si autentica con un token bot anziché un account utente. Il token identifica il bot, quindi trattalo come una password e non caricarlo mai in un repository pubblico. La documentazione di Telegram lo dice chiaramente: salva il tuo token in un luogo sicuro e non condividerlo.

L’API stessa è gratuita. Telegram ha offerto l’API Bot gratuitamente sin dal suo lancio, senza costi per messaggio e senza limiti sul numero di bot che puoi creare. Ecco perché così tanti strumenti della community, assistenti di supporto e automazioni la utilizzano. Se sei nuovo sulla piattaforma, la nostra guida su come creare un bot Telegram copre in dettaglio la configurazione dell’account.

Passo 1: Ottieni un token bot da BotFather

Apri Telegram e cerca @BotFather, il bot ufficiale per creare e gestire altri bot. Avvia una chat e invia il comando /newbot.

BotFather ti chiederà quindi due cose in ordine:

1. Un nome visualizzato per il tuo bot, come “Primo Bot API”.
2. Un nome utente che termina con bot, come first_api_demo_bot.

Quando hai finito, BotFather ti restituirà un token API che assomiglia a 123456789:AAExampleTokenStringHere. Questo token è l’unica credenziale di cui avrai bisogno per il resto di questo tutorial.

Attenzione: Chiunque abbia il tuo token controlla il tuo bot. Conservalo in una variabile d’ambiente, non nel codice sorgente. Se dovesse trapelare, invia /revoke a BotFather e ottienine uno nuovo.

Passo 2: Chiama il tuo primo metodo dell’API Bot

Prima di scrivere qualsiasi programma, conferma che il token funzioni. Il metodo getMe restituisce informazioni di base sul tuo bot ed è il controllo di salute standard. Sostituisci <YOUR_TOKEN> con il valore ottenuto da BotFather.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Una risposta di successo è un JSON con "ok": true e l’ID, il nome e il nome utente del tuo bot. Se vedi "ok": false, il token è sbagliato o presenta un errore di battitura.

Quella singola richiesta è l’intero schema. Ogni metodo dell’API di Telegram Bot segue la stessa forma: una chiamata HTTPS a https://api.telegram.org/bot<TOKEN>/METHOD_NAME, con parametri nella stringa di query o nel corpo POST, e un oggetto JSON in risposta. L’elenco completo si trova nella riferimento dell’API Bot, che documenta ogni metodo e oggetto di cui avrai mai bisogno.

Passo 3: Ricevere e inviare messaggi

Ora rendiamo il bot utile. C’è una regola che sorprende i principianti: un bot non può iniziare una conversazione. L’utente deve prima inviare un messaggio al bot. Quindi apri il tuo bot in Telegram e inviagli un testo qualsiasi, come “ciao”.

Successivamente, leggi quel messaggio con getUpdates, che recupera gli aggiornamenti in arrivo usando il long polling e restituisce un array di oggetti di aggiornamento.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

Nella risposta, trova message.chat.id. Quel chat_id è l’indirizzo a cui risponderai. Copialo, quindi chiama sendMessage:

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Ciao dal mio primo bot"

Il tuo bot risponde nella chat. Questo ciclo, leggere con getUpdates e rispondere con sendMessage, è il cuore della maggior parte dei bot Telegram. Il parametro text accetta fino a 4096 caratteri per messaggio, quindi le risposte lunghe devono essere suddivise.

Due dettagli da ricordare mentre scali questo esempio di API di Telegram Bot in codice reale:

• Ricalcola l’offset. Passa l’update_id dell’ultimo aggiornamento più uno come parametro offset nella tua prossima chiamata getUpdates, altrimenti Telegram continuerà a restituire gli stessi aggiornamenti.
• Un metodo alla volta. getUpdates smette di funzionare nel momento in cui registri un webhook, che è l’argomento del prossimo passo.

Passo 4: Scegliere tra long polling o webhook

Telegram offre due modi per ricevere aggiornamenti, e puoi usarne solo uno per bot alla volta.

• Il long polling significa che il tuo codice chiama ripetutamente getUpdates. È il percorso più semplice per l’apprendimento e lo sviluppo locale perché non richiede un URL pubblico, solo un processo che continua a funzionare.
• I webhook significano che Telegram invia ogni aggiornamento al tuo endpoint HTTPS come richiesta POST nell’istante in cui si verifica. Questo è lo standard di produzione: latenza inferiore, nessun polling inattivo e si adatta meglio a un traffico costante.

Per passare a un webhook, registra il tuo URL HTTPS pubblico una volta:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/webhook"

Il tuo endpoint necessita di un certificato TLS valido e deve restituire HTTP 200 rapidamente. Se gli aggiornamenti smettono di arrivare, la prima cosa da fare è sempre ispezionare l’errore. Per il flusso completo di registrazione, verifica e risoluzione dei problemi, consulta la nostra guida alla configurazione del webhook per bot Telegram. In breve: inizia con il polling mentre costruisci, passa a un webhook prima del lancio.

Passo 5: Integra l’API in una libreria

Il cURL grezzo è ottimo per imparare, ma i bot di produzione utilizzano una libreria. Una libreria gestisce le chiamate API, l’analisi degli aggiornamenti, i tentativi e lo stato della conversazione, in modo da scrivere solo la logica specifica del tuo bot. Telegram elenca le librerie della community per quasi ogni linguaggio nella sua pagina di esempi dell’API Bot.

Scegli in base al linguaggio che già conosci:

• Python: python-telegram-bot è puro Python, completamente asincrono e supporta Python 3.10 e versioni successive. aiogram e pyTelegramBotAPI sono alternative popolari.
• Node.js: Telegraf è maturo e compatibile con TypeScript. node-telegram-bot-api è un’opzione di lunga data.

Ecco lo stesso bot eco in Python, il punto di partenza più comune per un tutorial sull’API di Telegram Bot in Python:

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

TOKEN = "YOUR_TOKEN"

async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
 await update.message.reply_text(update.message.text)

app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()

E l’equivalente Node.js con Telegraf:

import { Telegraf } from 'telegraf'

const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()

Entrambi svolgono lo stesso lavoro del ciclo cURL del Passo 3, ma in poche righe e con le parti più complesse gestite per te. Maria, una sviluppatrice backend che prototipava un bot di supporto, è passata dai test cURL a python-telegram-bot in un pomeriggio e aveva gestori di comandi e pulsanti inline funzionanti la sera stessa. I concetti dell’API si sono trasferiti direttamente perché la libreria è un sottile wrapper sugli stessi metodi HTTP.

Limiti di frequenza e quote da conoscere

L’API è gratuita, ma non è illimitata. Le FAQ sui Bot di Telegram elencano le linee guida che impediscono al tuo bot di essere rallentato.

• Un messaggio al secondo per chat. In una singola conversazione, evita di inviare più velocemente di così.
• Circa 30 messaggi al secondo in totale quando si invia a molti utenti diversi. Se superi questo limite, inizierai a ricevere risposte HTTP 429 “Too Many Requests”.
• Circa 20 messaggi al minuto allo stesso gruppo.

Quando una trasmissione richiede davvero di più, puoi abilitare le Trasmissioni a Pagamento in @BotFather, il che aumenta il limite verso i 1000 messaggi al secondo. I messaggi oltre i 30 gratuiti al secondo costano 0.1 Telegram Stars ciascuno. La maggior parte dei bot non ne ha mai bisogno, ma è bene sapere che il limite esiste prima di progettare una funzione di notifica.

Rispetta un 429 leggendo il valore retry_after che Telegram restituisce e mettendo in pausa per quel numero di secondi. Una libreria gestisce questo per te, il che è un motivo in più per passare dalle richieste grezze una volta che il tuo traffico è reale.

Salta il codice: bot AI senza server

Non tutti i progetti richiedono una codebase personalizzata. Se il tuo obiettivo è un assistente AI in un gruppo Telegram, l’API Bot è un’infrastruttura che potresti non voler mantenere da solo, specialmente l’hosting, HTTPS e il livello webhook.

TeleClaw è una piattaforma no-code che gestisce il bot per te e connette Claude AI subito. Apri la dashboard TeleClaw, incolla il tuo token BotFather e configura il comportamento senza toccare setWebhook o la gestione dei limiti di frequenza. Tomas, che gestisce una community crypto di 4.000 membri, ha sostituito un bot personalizzato a metà con TeleClaw e ha avuto la moderazione AI e le risposte alle FAQ attive la sera stessa.

È la stessa API Bot sotto il cofano. Stai scegliendo se gestire tu stesso il livello server o lasciare che una piattaforma lo faccia. Esplora cosa copre questo sulla pagina delle funzionalità di TeleClaw e confronta le opzioni nel nostro riepilogo dei migliori bot Telegram. Per una costruzione puramente da dashboard, consulta la nostra guida ai chatbot Telegram no-code.

Conclusione

Ora hai un modello mentale funzionante dell’API di Telegram Bot: un token da BotFather, metodi HTTP come getMe, getUpdates e sendMessage, una scelta tra long polling e webhook, e una libreria per avvolgere il tutto una volta che il tuo bot cresce. L’API è gratuita, ben documentata e abbastanza accessibile da testare con cURL in pochi minuti.

Il passo successivo più veloce è il più piccolo. Apri @BotFather, esegui /newbot e invia la tua prima richiesta getMe per confermare il token. Da lì puoi costruire in Python o Node, o saltare completamente il server. Per lanciare un bot basato su AI in pochi minuti anziché giorni, accedi alla dashboard TeleClaw e collegalo al tuo gruppo e configuralo nella dashboard di TeleClaw.