Cómo crear un bot de Telegram con BotFather y obtener el token

Todo bot de Telegram empieza en el mismo lugar: una conversación con BotFather, el bot oficial de Telegram para crear y configurar otros bots. No hay portal de desarrolladores ni formulario. Respondes unos cuantos mensajes y recibes un token, una cadena que tu código usa para demostrar que controla el bot.

Esta guía cubre el camino completo: crear el bot, elegir el username, proteger el token, comprobar que funciona y ejecutar un primer bot. El código usa Python con la API de la versión 22 de python-telegram-bot, que requiere una versión de Python que todavía tenga soporte (la mínima está en la documentación de la librería).

¿Qué necesito antes de empezar?#

• Una cuenta de Telegram, en el celular o en la app de escritorio.
• Una versión de Python que todavía tenga soporte, solo si quieres ejecutar el código de prueba.
• Un lugar para guardar secretos, como una variable de entorno o un archivo .env.

¿Cómo creo un bot con BotFather?#

1. Abre @BotFather en Telegram. Verifica que el username sea exactamente @BotFather, porque existen cuentas que lo imitan.
2. Envía /newbot.
3. BotFather te pide un nombre. Es el nombre visible que aparece en los chats y en los datos de contacto. Puede tener espacios y se puede cambiar después con /setname.
4. BotFather te pide un username. Debe tener entre 5 y 32 caracteres, usar solo letras latinas, números y guiones bajos, y terminar en bot, como tetris_bot o TetrisBot. No distingue mayúsculas de minúsculas, debe ser único y no se puede cambiar después.
5. BotFather responde con el token y un enlace a tu bot, t.me/<username>.

Si el username ya está ocupado, BotFather te pide otro. Prueba agregar una palabra o un número.

¿Cómo es el token y qué permite hacer?#

El token es un número, dos puntos y una cadena larga de letras y dígitos. La documentación de Telegram muestra este formato:

110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

Ese ejemplo no es una credencial real. El token autentica a tu bot, no a tu cuenta. Cualquiera que lo tenga puede controlar el bot, así que trátalo como una contraseña. El tutorial de Telegram considera una mala práctica escribirlo en el código fuente y recomienda variables de entorno o un archivo de configuración.

Si se filtra, revócalo desde BotFather y genera uno nuevo (la documentación de Telegram indica /token para eso). Actualiza todos los lugares donde corre el bot y luego llama a getMe (más abajo) con el token antiguo para confirmar que ya no funciona. Lee qué son las variables de entorno y qué es un archivo .env para mantenerlo fuera de tu repositorio.

¿Cómo pruebo que el token funciona?#

La Bot API es HTTPS simple. Cada petición va a https://api.telegram.org/bot<token>/NOMBRE_DEL_METODO, con la palabra bot delante del token. El método getMe devuelve el perfil del propio bot, por eso es una buena prueba.

export BOT_TOKEN="pega-tu-token-aqui"
curl "https://api.telegram.org/bot${BOT_TOKEN}/getMe"

Un token válido devuelve un JSON con "ok": true y un objeto result con el id, el nombre y el username del bot. Uno inválido devuelve "ok": false con error_code 401 (o 404 cuando el token está mal formado).

¿Cómo ejecuto un primer bot?#

Instala la biblioteca y escribe un bot que responda a /start y repita los mensajes de texto.

pip install "python-telegram-bot>=22,<23"

import os

from telegram import Update
from telegram.ext import (
    Application,
    CommandHandler,
    ContextTypes,
    MessageHandler,
    filters,
)


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("¡Hola! Envíame un mensaje y lo repetiré.")


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


def main() -> None:
    app = Application.builder().token(os.environ["BOT_TOKEN"]).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    app.run_polling()


if __name__ == "__main__":
    main()

Ejecútalo con BOT_TOKEN definida en la misma terminal, abre el enlace de tu bot y pulsa Iniciar. El bot usa long polling: le pregunta a Telegram si hay actualizaciones nuevas, así que no necesita una URL pública. Para ver la diferencia entre polling y webhook, lee cómo hospedar un bot de Telegram 24/7.

¿Cómo termino de configurar el bot en BotFather?#

Estos comandos le dan los últimos detalles al bot. Todos son opcionales:

• /setdescription: texto de hasta 512 caracteres que aparece en "¿Qué puede hacer este bot?" cuando un usuario abre el chat por primera vez.
• /setabouttext: una biografía más corta, de hasta 120 caracteres, que aparece en la página de perfil.
• /setcommands: la lista de comandos que el usuario ve al escribir /.
• /setname: cambia el nombre visible.

Los comandos que registras así solo muestran un menú. Tu código todavía tiene que manejar cada uno.

¿Cuáles son los errores más comunes?#

• telegram.error.InvalidToken o 401 Unauthorized: el token está mal, tiene espacios o comillas de más, o fue revocado en BotFather. Cópialo de nuevo.
• KeyError: 'BOT_TOKEN': la variable de entorno no está definida en la terminal que ejecuta el script.
• El bot no responde: el proceso no está corriendo, o nunca pulsaste Iniciar.
• 409 Conflict (telegram.error.Conflict): dos instancias usan el mismo token con long polling, o hay un webhook configurado. Detén la instancia extra o elimina el webhook con deleteWebhook.
• Username rechazado: no termina en bot, no tiene entre 5 y 32 caracteres o ya está ocupado.

Si el bot funcionaba y dejó de responder, la guía el bot de Telegram no responde repasa las causas una por una.

Cómo hacerlo en Square Cloud#

El bot de arriba solo responde mientras su proceso está corriendo. En tu propia máquina eso se acaba cuando la computadora entra en reposo, así que un bot que usan otras personas necesita un hosting siempre encendido.

En Square Cloud, el hosting es self-service: tú mismo haces el deploy del bot y defines BOT_TOKEN como variable de entorno de la aplicación, así el token queda fuera de tu código. La plataforma es compatible con python-telegram-bot, aiogram, Telethon, Telegraf y grammY. El long polling funciona sin configuración extra, y tienes un subdominio HTTPS disponible si prefieres webhooks. El archivo de configuración squarecloud.app es opcional: el panel puede generarlo durante el deploy, o puedes escribirlo en la raíz del proyecto.

Cada aplicación en segundo plano, como un bot, necesita al menos 256 MB de RAM, y todos los planes son de pago. Los detalles están en hospedar un bot de Telegram en Square Cloud.