Modulo didattico · Sviluppo Web / E-commerce

Creare applicazioni con i bot Telegram

Un percorso operativo pensato per chi si avvicina per la prima volta all'API dei bot Telegram: dai concetti di base alla configurazione, fino a cinque casi d'uso reali con esempi di codice.

💬
@BotFather
Crea il bot
→
🔑
Bot Token
Credenziale unica
→
🌐
Bot API
api.telegram.org
→
👤
Utenti/Chat
chat_id
01

Fondamenti

Telegram è, tra le piattaforme di messaggistica, quella con l'onboarding più semplice per uno sviluppatore: non serve un account business, bastano pochi minuti con un bot di sistema.

Piattaforma

Bot API

L'interfaccia ufficiale di Telegram per creare bot: un programma che può inviare/ricevere messaggi, gestire gruppi e canali, mostrare pulsanti interattivi.

Creazione

@BotFather

Un bot di sistema di Telegram: con il comando /newbot crei un nuovo bot e ricevi immediatamente il suo token, senza approvazioni o attese.

Sicurezza

Bot Token

Stringa segreta che autentica ogni chiamata: https://api.telegram.org/bot{TOKEN}/METODO. Chi lo possiede controlla il bot.

Ricezione

Webhook o Polling

Due modi per ricevere messaggi: un webhook (Telegram chiama il tuo server) oppure il polling (il tuo server chiede periodicamente "ci sono novità?").

Identificativo

chat_id

Il numero che identifica una chat, un gruppo o un canale: è il destinatario di ogni messaggio che il bot invia.

Nessuna finestra 24h

Differenza chiave con WhatsApp

Telegram non impone una finestra di 24 ore né template approvati: un bot può scrivere in qualsiasi momento a chi ha avviato una chat con /start.

02

Setup operativo passo-passo

Segui questi quattro passaggi in ordine. Spunta ogni step man mano che lo completi.

01Crea il bot con @BotFather

Apri una chat con @BotFather su Telegram, invia /newbot e segui le istruzioni: scegli un nome visualizzato e uno username che termini in "bot" (es. MioNegozio_bot).

02Conserva il token ricevuto

BotFather ti restituisce subito un token (es. 123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxx). È l'unica credenziale che ti serve: non ci sono altri permessi da richiedere.

03Invia il tuo primo messaggio di prova

Scrivi /start al tuo bot da Telegram (serve per ottenere il tuo chat_id), poi esegui:

cURL — ottieni il tuo chat_id
curl "https://api.telegram.org/bot{TOKEN}/getUpdates"
cURL — invia un messaggio di prova
curl -X POST "https://api.telegram.org/bot{TOKEN}/sendMessage" \
  -d "chat_id={IL_TUO_CHAT_ID}" \
  -d "text=Ciao! Questo è il mio primo messaggio via Bot API."
Segna come completato quando ricevi il messaggio su Telegram

04Configura il webhook di ricezione

Per ricevere messaggi in tempo reale senza interrogare continuamente Telegram, imposta un webhook con un URL pubblico HTTPS (in fase di apprendimento puoi usare un tunnel come ngrok):

cURL — imposta il webhook
curl -X POST "https://api.telegram.org/bot{TOKEN}/setWebhook" \
  -d "url=https://tuoserver.it/webhook"
Errore comune: dimenticare che webhook e polling (getUpdates) sono alternativi: se un webhook è attivo, getUpdates non riceverà nulla finché non lo disattivi.
03

Le cinque tipologie di applicazione

Clicca su ciascuna scheda per aprire scenario, esempio di codice e avvertenze.

🎧

Assistenza clienti

Risposte automatiche a domande frequenti
▾
Scenario: un cliente scrive "Orari di apertura?" e il bot risponde subito con l'informazione, senza intervento umano.
Node.js — risposta automatica su parola chiave
// Riceviamo l'update dal webhook e rispondiamo in base al testo
app.post('/webhook', async (req, res) => {
  const msg = req.body.message;
  if (msg?.text?.toLowerCase().includes('orari')) {
    await sendMessage(msg.chat.id, 'Siamo aperti dal lunedì al sabato, 9-19.');
  }
  res.sendStatus(200);
});
Cosa non fare: non far dipendere risposte critiche solo da parole chiave rigide: prevedi sempre un modo per passare a un operatore umano.
🔔

Notifiche e alert

Avvisi di sistema, promemoria, aggiornamenti d'ordine
▾
Scenario: un e-commerce invia una notifica quando lo stato di un ordine cambia, senza restrizioni di finestra oraria.
cURL — invio di una notifica
curl -X POST "https://api.telegram.org/bot{TOKEN}/sendMessage" \
  -d "chat_id={CHAT_ID_CLIENTE}" \
  -d "text=Il tuo ordine #12345 è stato spedito! 📦"
Cosa non fare: non inviare notifiche a un chat_id se l'utente non ha mai avviato la chat con /start: il bot non può scrivere per primo a nessuno.
📣

Canali di diffusione

Marketing e contenuti su canali Telegram
▾
Scenario: un brand pubblica aggiornamenti su un canale Telegram pubblico, a cui gli utenti si iscrivono liberamente.
cURL — pubblica su un canale (bot come admin)
curl -X POST "https://api.telegram.org/bot{TOKEN}/sendMessage" \
  -d "chat_id=@nomecanale" \
  -d "text=Nuova collezione disponibile da oggi! 🛍️"
Cosa non fare: non dimenticare di rendere il bot amministratore del canale prima di provare a pubblicare, altrimenti la chiamata fallirà.
🤖

Chatbot conversazionale

Flusso guidato con pulsanti inline
▾
Scenario: un bot guida l'utente tra opzioni tramite pulsanti, invece di richiedere testo libero.
JSON — messaggio con pulsanti inline
{
  "chat_id": "{CHAT_ID}",
  "text": "Cosa vuoi fare?",
  "reply_markup": {
    "inline_keyboard": [[
      { "text": "📦 Traccia ordine", "callback_data": "traccia" },
      { "text": "💬 Parla con operatore", "callback_data": "operatore" }
    ]]
  }
}
Cosa non fare: non dimenticare di rispondere sempre a answerCallbackQuery dopo un click su un pulsante, altrimenti l'utente vedrà un caricamento infinito.
🛒

Bot e-commerce/community

Ordini semplici e gestione gruppi
▾
Scenario: un piccolo negozio gestisce ordini via bot e modera un gruppo community, con il bot come amministratore.
Node.js — gestione comando /ordine
if (msg.text === '/ordine') {
  await sendMessage(msg.chat.id, 'Scrivi il codice prodotto che vuoi ordinare.');
  sessioni[msg.chat.id] = { stato: 'attesa_codice' };
}
Cosa non fare: non affidare al bot azioni di moderazione irreversibili (ban permanenti) senza una conferma da un amministratore umano.
04

Glossario interattivo

Clicca su un termine per rivelarne la definizione.

Bot Token clicca
Stringa segreta assegnata da BotFather che autentica ogni chiamata alla Bot API.
@BotFather clicca
Il bot di sistema di Telegram usato per creare e gestire altri bot.
chat_id clicca
Identificativo numerico di una chat privata, gruppo o canale, usato come destinatario dei messaggi.
Webhook clicca
URL del tuo server che Telegram chiama automaticamente quando arriva un nuovo messaggio o evento.
Polling clicca
Metodo alternativo al webhook: il server richiede periodicamente a Telegram se ci sono nuovi aggiornamenti (getUpdates).
Inline Keyboard clicca
Pulsanti agganciati a un messaggio che l'utente può premere, generando un callback_data gestito dal bot.
Canale clicca
Spazio di diffusione unidirezionale (solo gli admin pubblicano); diverso da un gruppo, dove tutti possono scrivere.
/start clicca
Il comando che un utente invia per avviare la conversazione con un bot: da quel momento il bot può scrivergli.
05

Esercitazioni pratiche

Verifica quanto hai appreso con questo quiz di autovalutazione.

1. Chi crea un nuovo bot Telegram e ne rilascia il token?
2. Cosa deve fare un utente prima che il bot possa scrivergli?
3. Webhook e polling possono essere attivi insieme?
4. Cosa succede se non rispondi a un callback_query dopo un click su un pulsante inline?
06

Attestato di completamento

Completa tutti i passaggi della Sezione 2 per sbloccare il tuo attestato personale in PDF.

🔒
Attestato non ancora disponibile
Completa tutti e 4 i passaggi della Sezione 2 — Setup operativo.