Configurazione webhook bot Telegram: guida completa per sviluppatori

La configurazione del webhook del bot Telegram collega il tuo server al flusso di aggiornamenti di Telegram in modo che i messaggi arrivino in tempo reale invece che tramite un ciclo di polling. Se stai costruendo un bot personalizzato con l’API del Bot, i webhook sono il percorso di produzione standard: Telegram invia ogni aggiornamento al tuo endpoint HTTPS e il tuo codice risponde.

Questa guida illustra i prerequisiti, la registrazione, un esempio di gestore funzionante, la verifica, la risoluzione dei problemi e quando una piattaforma gestita come TeleClaw ha più senso rispetto all’auto-hosting.

Punti chiave

• I webhook e il long polling si escludono a vicenda. L’impostazione di un webhook disabilita getUpdates finché non lo rimuovi.
• HTTPS è obbligatorio. Il tuo endpoint necessita di TLS 1.2+, un certificato corrispondente e la porta 443, 80, 88 o 8443.
• Registra con setWebhook, verifica con getWebhookInfo. Controlla last_error_message quando gli aggiornamenti smettono di fluire.
• Usa secret_token per confermare che le richieste provengono da Telegram, non da scanner casuali che colpiscono il tuo URL.
• Alternativa senza codice: TeleClaw gestisce l’hosting e la consegna in modo da saltare completamente il livello del server.

Webhook vs long polling: quale scegliere

Telegram offre due modi per ricevere aggiornamenti. Secondo le FAQ sui bot, si sceglie un metodo per bot. Non è possibile eseguirli entrambi contemporaneamente.

Il long polling è il modo più veloce per prototipare. Il tuo bot chiama getUpdates in un ciclo, elabora ogni batch e avanza l’offset. Nessun dominio, nessun certificato, nessuna porta aperta.

I webhook ribaltano il modello. Telegram invia un POST HTTPS al tuo URL ogni volta che qualcuno invia un messaggio al bot. Questo elimina le richieste di polling inattive e riduce il tempo di reazione, il che è importante per i bot di supporto, i flussi di pagamento e la moderazione di gruppo su larga scala.

Se stai ancora registrando il bot stesso, inizia con la nostra guida alla creazione di un bot Telegram per ottenere un token da BotFather prima di continuare qui.

Prerequisiti per la configurazione del webhook del bot Telegram

Prima di chiamare setWebhook, conferma che la tua infrastruttura soddisfi i requisiti di Telegram dalla guida ufficiale sui webhook:

• Token del bot da @BotFather (vedi la guida alla creazione del bot collegata sopra).
• Dominio pubblico con un certificato TLS valido. I certificati auto-firmati funzionano solo se carichi la chiave pubblica tramite il parametro certificate.
• Porta supportata sul tuo server: 443 (predefinita), 80, 88 o 8443. Altre porte vengono rifiutate.
• CN o SAN del certificato devono corrispondere al dominio nel tuo URL webhook. I certificati wildcard potrebbero non funzionare. I reindirizzamenti non sono supportati.
• Accesso POST in entrata dalle sottoreti Telegram 149.154.160.0/20 e 91.108.4.0/22.

Per lo sviluppo locale, esponi localhost tramite un tunnel (ngrok, Cloudflare Tunnel o simili) che ti fornisce un URL HTTPS pubblico. Testa che il tunnel restituisca HTTP 200 per le richieste POST prima di registrare il webhook.

Passaggio 1: Costruisci il tuo endpoint webhook

Il tuo server necessita di un percorso che accetti richieste POST, analizzi l’oggetto JSON Update e restituisca rapidamente HTTP 200. I gestori lenti fanno sì che Telegram riprovi e alla fine segnali errori in getWebhookInfo.

Esempio minimo di Node.js con Express:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Python con Flask segue lo stesso schema: leggi JSON da request, convalida l’intestazione segreta se configurata, elabora l’aggiornamento, restituisci 200.

Rispondi velocemente. Il lavoro pesante (scritture nel database, chiamate API AI) dovrebbe andare a una coda in background. Telegram si aspetta un rapido riconoscimento. Puoi anche rispondere in linea restituendo un corpo JSON con un campo method invece di effettuare una chiamata API separata, come descritto nelle note sui webhook dell’API del Bot.

Passaggio 2: Configura il webhook del bot Telegram con setWebhook

Una volta che il tuo endpoint è attivo, registralo con l’API del Bot. Sostituisci <TOKEN> e l’URL con i tuoi valori.

Usando curl:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

Riferimento parametri:

• url (obbligatorio): Il tuo endpoint HTTPS. Usa una stringa vuota per rimuovere il webhook.
• secret_token (opzionale): 1-256 caratteri (A-Z, a-z, 0-9, _, -). Telegram lo invia nell’intestazione X-Telegram-Bot-Api-Secret-Token.
• max_connections (opzionale): 1-100 connessioni simultanee. Il valore predefinito è 40.
• allowed_updates (opzionale): Limita i tipi di aggiornamento che ricevi. Riduce la dimensione del payload se gestisci solo messaggi.
• drop_pending_updates (opzionale): Imposta true per scartare gli aggiornamenti in coda quando si cambiano i webhook.
• certificate (opzionale): Carica il tuo file di chiave pubblica per i certificati auto-firmati.

Una risposta di successo assomiglia a {"ok":true,"result":true,"description":"Webhook was set"}.

Passaggio 3: Verifica con getWebhookInfo

Conferma sempre la registrazione immediatamente. Questo è il tuo primo strumento di risoluzione dei problemi quando gli aggiornamenti smettono di arrivare.

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Esempio di risposta:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

Osserva questi campi:

• url: Vuoto significa che nessun webhook è attivo (il bot è in long polling).
• pending_update_count: Aggiornamenti in coda in attesa di consegna. Un numero crescente segnala errori di consegna.
• last_error_date e last_error_message: Il motivo dell’errore più recente. Correggi la causa principale, quindi Telegram riprova automaticamente.
• ip_address: Quale IP di Telegram sta attualmente colpendo il tuo endpoint.

Invia un messaggio di prova al tuo bot da un account Telegram reale. Se pending_update_count rimane a zero e i log del tuo server mostrano il POST, la configurazione del webhook del bot Telegram funziona.

Esempio di webhook del bot Telegram: gestore di richieste di unione

I bot per le richieste di unione (flussi di ammissione in stile Guardian) necessitano del tipo di aggiornamento chat_join_request. La nostra guida al bot Guardian copre il lato del prodotto. Ecco il cablaggio del webhook.

Registra con le richieste di unione abilitate:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

Logica del gestore (pseudocodice):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Esegui la logica di screening, quindi approva o rifiuta tramite l'API del Bot
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram consegna le richieste di unione come aggiornamenti push, quindi i webhook sono una soluzione naturale per i bot di ammissione che devono rispondere prima che la richiesta scada.

Rimuovere il webhook del bot Telegram e tornare al polling

Hai bisogno di eseguire il debug localmente con getUpdates? Rimuovi prima il webhook.

Opzione A con deleteWebhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

Opzione B con setWebhook e URL vuoto:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

Entrambi i metodi riabilitano il long polling. Se salti questo passaggio, getUpdates non restituisce nulla perché il webhook è ancora registrato al tuo URL di produzione.

Risoluzione dei problemi comuni degli errori del webhook

Quando getWebhookInfo mostra errori, abbina il messaggio a una soluzione:

Esegui getWebhookInfo a intervalli regolari in produzione. Catturare last_error_message in anticipo previene ore di perdita silenziosa di messaggi.

Salta il server: bot gestiti con TeleClaw

Non tutti i bot necessitano di un’infrastruttura webhook personalizzata. Se il tuo obiettivo è un assistente AI per un gruppo o un canale aziendale, l’hosting e la consegna degli aggiornamenti sono problemi risolti.

TeleClaw collega il tuo token BotFather a un runtime gestito alimentato da OpenClaw. Configuri personalità, base di conoscenza e regole di moderazione nella dashboard. La piattaforma gestisce gli endpoint HTTPS, la scalabilità e il routing del modello AI. Aggiungi @claw come amministratore di gruppo e vai online senza scrivere un gestore webhook.

Esplora cosa può fare un bot gestito nella pagina delle funzionalità di TeleClaw. Per una guida completa senza codice, consulta la nostra guida al chatbot Telegram senza codice.

I webhook personalizzati hanno ancora senso quando hai bisogno del controllo completo: backend proprietari, residenza dei dati regolamentata o elaborazione di aggiornamenti non standard. Per tutto il resto, il costo operativo della gestione dei certificati, del monitoraggio e della gestione dei tentativi si accumula rapidamente.

Conclusione

La configurazione del webhook del bot Telegram si riduce a quattro passaggi: distribuisci un endpoint HTTPS, chiama setWebhook, verifica con getWebhookInfo e monitora gli errori. Usa secret_token per la convalida delle richieste, limita allowed_updates a ciò che elabori e mantieni i gestori veloci.

Gli sviluppatori che desiderano la consegna push in produzione senza eseguire server possono utilizzare TeleClaw invece. Incolla il tuo token, configura il comportamento dell’AI e concentrati su ciò che dice il bot piuttosto che su come arrivano gli aggiornamenti.

Pronto a lanciare un bot AI senza gestire i webhook? Aggiungi @claw al tuo gruppo Telegram →