Come ospitare un bot Telegram 24/7

Introduzione

Per sviluppare e ospitare un bot Telegram su Square Cloud, è essenziale seguire una sequenza strutturata di configurazioni e prerequisiti. Questa guida tecnica coprirà l’intero processo, dalla configurazione iniziale al deploy in produzione.

Prerequisiti

Account Square Cloud: Registrati tramite la pagina di registrazione usando la tua email.
Piano attivo: Garantisce risorse dedicate e prestazioni ottimizzate per la tua applicazione. Consulta i nostri piani disponibili e scegli quello più adatto alle tue esigenze.

Questa guida usa il runtime Node.js o il runtime Python.

Creare il progetto

Un account Telegram è essenziale per testare e interagire con il tuo bot. Se non ne hai uno, visita il sito ufficiale di Telegram per creare il tuo account.

Applicazione bot su Telegram

Trova BotFather

Accedi a Telegram Web e cerca il bot ufficiale BotFather, responsabile della creazione e gestione dei bot sulla piattaforma.

Ottieni il token

Avvia una conversazione con BotFather e digita /start. Poi, seleziona l’opzione /newbot per creare un nuovo bot. Il sistema ti chiederà un nome per il tuo bot e, dopo la conferma, genererà automaticamente il token di autenticazione necessario.

Generazione del token del bot Telegram con BotFather

Mantieni segreto il token: questo token garantisce il controllo totale sul bot. Non scriverlo mai nel codice e non metterlo nello ZIP: gli esempi qui sotto lo leggono dalla variabile d’ambiente TELEGRAM_BOT_TOKEN.

Sviluppare il bot

Scrivi il bot con grammY (Node.js) o pyTelegramBotAPI (Python). Entrambi gli esempi ripetono ogni messaggio di testo:

Node.js - grammY
Python - telebot

Verifica che Node.js sia installato sul tuo sistema. In caso contrario, scaricalo dal sito ufficiale di Node.js.
Inizializza un nuovo progetto Node.js:

Terminal

npm init -y

Installa la libreria grammY:

Terminal

npm install grammy

Crea il file principale (index.js) con la seguente struttura:

index.js

const { Bot } = require("grammy");

// The token comes from the TELEGRAM_BOT_TOKEN environment variable
const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN);

// Reply to every text message with an echo
bot.on("message:text", async (ctx) => {
  await ctx.reply(`${ctx.me.username} responds: ${ctx.message.text}`);
});

// Long polling: the bot asks Telegram for new messages, so no public URL is needed
bot.start({
  onStart: (botInfo) => console.log(`Bot ${botInfo.username} started successfully!`),
});

Verifica che Python e pip siano installati. In caso contrario, scaricali dal sito ufficiale di Python.
Installa la libreria pyTelegramBotAPI:

Terminal

pip install pyTelegramBotAPI

Crea il file principale (main.py):

main.py

import os

import telebot

# The token comes from the TELEGRAM_BOT_TOKEN environment variable
bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"])
bot_name = bot.get_me().username


# Echo every message that isn't a command
@bot.message_handler(func=lambda message: not message.text.startswith("/"))
def echo_handler(message):
    bot.reply_to(message, f"{bot_name} responds: {message.text}")


if __name__ == "__main__":
    print(f"Bot {bot_name} started successfully!")
    # Long polling: no public URL is needed
    bot.infinity_polling()

Crea il file requirements.txt per gestire le dipendenze:

requirements.txt

pyTelegramBotAPI

Configurare Square Cloud

Crea un file squarecloud.app nella radice del tuo progetto, accanto al file principale. Indica a Square Cloud come eseguire il tuo bot:

DISPLAY_NAME=My Telegram Bot
MAIN=index.js
MEMORY=512
VERSION=recommended
AUTORESTART=true

DISPLAY_NAME=My Telegram Bot
MAIN=main.py
MEMORY=512
VERSION=recommended
AUTORESTART=true

MAIN è il file che Square Cloud esegue, e MEMORY è la RAM del bot in MB. I bot richiedono almeno 256 MB; 512 MB lasciano spazio per crescere.
AUTORESTART=true riavvia il bot se va in crash. Consulta come funziona il riavvio automatico.
Non c’è SUBDOMAIN: con il long polling, il bot non ha bisogno di un URL pubblico.

Consulta il riferimento del file di configurazione per tutti i campi.

Impostare il token del bot

Il tuo codice legge il token dalla variabile d’ambiente TELEGRAM_BOT_TOKEN, quindi il token non finisce mai nei tuoi file. Impostalo in uno di questi modi:

Dashboard: nella pagina di upload, apri Configurazione avanzata e aggiungi una variabile chiamata TELEGRAM_BOT_TOKEN con il tuo token come valore. Per un bot già pubblicato, aggiungila nella pagina Variabili d’ambiente dell’applicazione e riavvia il bot.
CLI: subito dopo aver caricato il bot (vedi Deploy e verifica), impostala con squarecloud app env set e riavvia il bot:

squarecloud app env set TELEGRAM_BOT_TOKEN=your_token_here
squarecloud app restart

Il bot legge le variabili d’ambiente all’avvio, quindi riavvialo dopo ogni modifica. Consulta Variabili d’ambiente per gli altri modi di gestirle.

Per eseguire prima il bot sul tuo computer, imposta la variabile nel terminale: export TELEGRAM_BOT_TOKEN=your_token_here su macOS e Linux, oppure $env:TELEGRAM_BOT_TOKEN="your_token_here" in PowerShell.

Cosa mettere nello ZIP

Il file principale (index.js o main.py) e gli altri file sorgente.
package.json o requirements.txt.
squarecloud.app.

Lascia fuori node_modules, .venv e __pycache__: Square Cloud installa le dipendenze all’avvio del bot.

Deploy e verifica

Crea lo ZIP descritto sopra, poi caricalo:

Tramite dashboard

Accedi alla pagina di upload

Accedi alla pagina di upload e carica il file zip del tuo progetto.

Configura il tuo ambiente

Dopo aver caricato il tuo zip, dovrai configurare il nome, il file principale o il runtime environment e altre impostazioni per il tuo progetto.
Se stai caricando un progetto web, assicurati di selezionare “Web Publication” e di impostare un sottodominio per il tuo progetto.

Esegui il deploy del tuo progetto

Infine, clicca sul pulsante “Deploy” per ospitare il tuo progetto su Square Cloud.
Dopo il deploy, puoi monitorare lo stato e i log del tuo progetto dalla dashboard.

Caricamento dell'applicazione su Square Cloud

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Nella dashboard, attendi che lo stato della tua applicazione mostri “in esecuzione” e controlla i log per eventuali errori di avvio.
Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.

La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

Tramite CLI

Per utilizzare questo metodo, il tuo progetto deve avere un file di configurazione chiamato squarecloud.app nella sua radice. Indica a Square Cloud come eseguire la tua applicazione.

Guida al file di configurazione

Scopri come creare il file di configurazione squarecloud.app che definisce l’ambiente della tua applicazione.

Installa la CLI

Installa la CLI di Square Cloud. Se ce l’hai già, esegui lo stesso comando per aggiornarla:

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

Accedi

Esegui il comando qui sotto. Apre il tuo browser: approva l’accesso lì e la CLI è pronta. Non c’è nessuna chiave API da copiare. Per script e CI, consulta Autenticazione della CLI.

squarecloud auth login

Carica il tuo progetto

Dalla cartella del tuo progetto, esegui il comando qui sotto. La CLI comprime la cartella corrente, escludendo ciò che elenca squarecloud.ignore, e la carica:

squarecloud upload

Per caricare uno zip che hai creato tu, passalo con --file:

squarecloud upload --file <path/to/zip>

Conferma che la tua app sia online

Il primo deploy richiede di solito meno di un minuto. Controlla lo stato e i log della tua applicazione direttamente dal terminale:

squarecloud app status
squarecloud app logs

Se hai fatto il deploy di un sito web o di un’API, apri https://<tuo-sottodominio>.squareweb.app nel tuo browser: dovresti vedere la tua applicazione rispondere. Se hai fatto il deploy di un bot, invia un comando per confermare che sia online.

La tua app non si avvia? Consulta la guida alla risoluzione dei problemi per le cause più comuni e le relative soluzioni.

Testare il bot

Dopo il deploy, cerca il tuo bot su Telegram e inviagli un messaggio. Il bot risponde con lo stesso testo, a conferma che è in esecuzione.

Errori comuni

Error 409: Conflict: terminated by other getUpdates request

Un’altra copia del bot sta leggendo gli aggiornamenti con lo stesso token, ad esempio quella che hai avviato sul tuo computer. Telegram consegna gli aggiornamenti a una sola connessione di long polling per bot. Ferma l’altra copia, oppure revoca il token in BotFather se non sai dove è in esecuzione, poi imposta il nuovo token e riavvia il bot.

Error 401: Unauthorized

Il token è sbagliato o è stato revocato. Copia il token attuale da BotFather, impostalo di nuovo e riavvia il bot.

Token vuoto o `KeyError: 'TELEGRAM_BOT_TOKEN'`

La variabile TELEGRAM_BOT_TOKEN non è impostata: grammY si ferma con Empty token! e l’esempio Python si ferma con un KeyError. Imposta la variabile, come in Impostare il token del bot, e riavvia il bot.

Prossimi passi

L'app non si avvia

Risolvi moduli mancanti, errori di memoria e altri errori di avvio.

Variabili d'ambiente

Gestisci il token del tuo bot e gli altri segreti.

python-telegram-bot con aiohttp

Usi python-telegram-bot? Risolvi le frequenti eccezioni NetworkError.

Per saperne di più su queste librerie, consulta la documentazione ufficiale di grammY e la pagina di pyTelegramBotAPI su PyPI.

Contattaci

Se continui a riscontrare difficoltà tecniche, il nostro team di supporto specializzato è disponibile ad assisterti. Contattaci e saremo felici di aiutarti a risolvere qualsiasi problema: la qualità del supporto è una parte importante del motivo per cui gli sviluppatori valutano Square Cloud 4,9/5 su 402 recensioni su Google e Trustpilot.

Bots

Siti web

API e backend

Database

App self-hosted

Guide

Guide alla migrazione

Come ospitare un bot Telegram 24/7

Introduzione

Prerequisiti

Creare il progetto

Applicazione bot su Telegram

Sviluppare il bot

Configurare Square Cloud

Impostare il token del bot

Cosa mettere nello ZIP

Deploy e verifica

Tramite dashboard

Tramite CLI

Guida al file di configurazione

Testare il bot

Errori comuni

Error 409: Conflict: terminated by other getUpdates request

Error 401: Unauthorized

Token vuoto o `KeyError: 'TELEGRAM_BOT_TOKEN'`

Prossimi passi

L'app non si avvia

Variabili d'ambiente

python-telegram-bot con aiohttp

Contattaci

​Introduzione

​Prerequisiti

​Creare il progetto

​Applicazione bot su Telegram

​Sviluppare il bot

​Configurare Square Cloud

​Impostare il token del bot

​Cosa mettere nello ZIP

​Deploy e verifica

​Tramite dashboard

​Tramite CLI

Guida al file di configurazione

​Testare il bot

​Errori comuni

​Error 409: Conflict: terminated by other getUpdates request

​Error 401: Unauthorized

​Token vuoto o KeyError: 'TELEGRAM_BOT_TOKEN'

​Prossimi passi

L'app non si avvia

Variabili d'ambiente

python-telegram-bot con aiohttp

​Contattaci

Introduzione

Prerequisiti

Creare il progetto

Applicazione bot su Telegram

Sviluppare il bot

Configurare Square Cloud

Impostare il token del bot

Cosa mettere nello ZIP

Deploy e verifica

Tramite dashboard

Tramite CLI

Testare il bot

Errori comuni

Error 409: Conflict: terminated by other getUpdates request

Error 401: Unauthorized

Token vuoto o `KeyError: 'TELEGRAM_BOT_TOKEN'`

Prossimi passi

Contattaci