Tutorial de la API de bots de Telegram: crea tu primer bot

El tutorial más rápido de la API de bots de Telegram se resume en tres comandos: obtener un token de BotFather, llamar a getUpdates para leer mensajes y llamar a sendMessage para responder. Todo lo demás en el desarrollo de bots se construye sobre este ciclo. Esta guía te lleva por el camino completo, desde tu primera solicitud cURL hasta un bot en funcionamiento con un webhook y una librería.

La API de bots es una interfaz HTTP, lo que significa que puedes probarla con curl antes de escribir una sola línea de código de aplicación. Esto la convierte en una de las APIs más amigables para aprender. Si eres un desarrollador que quiere un bot funcionando hoy, o un creador que sopesa el código frente a una plataforma sin código como TeleClaw, estás en el lugar correcto.

Al finalizar, comprenderás cómo la API autentica las solicitudes, cómo recibir y enviar mensajes, la diferencia entre long polling y webhooks, y los límites de tasa que suelen frustrar a la mayoría de los primeros bots.

Puntos clave

• Un bot es solo un cliente HTTP. Cada método es una solicitud a https://api.telegram.org/bot<TOKEN>/METHOD_NAME, por lo que cURL es suficiente para empezar.
• Tres métodos principales te ponen en marcha: getMe para verificar el token, getUpdates para leer mensajes y sendMessage para responder.
• Long polling y webhooks son mutuamente excluyentes. Usa polling para pruebas locales, cambia a un webhook para producción.
• La API es gratuita, pero Telegram limita el envío masivo a aproximadamente 30 mensajes por segundo a diferentes usuarios y uno por segundo por chat.
• Una librería ahorra tiempo una vez que tu bot crece más allá de un script. Usa python-telegram-bot, aiogram o Telegraf.

¿Qué es la API de bots de Telegram?

La API de bots de Telegram es una interfaz basada en HTTP para conectar tu código a Telegram a través de un bot. Según la introducción para desarrolladores de Telegram, los bots son cuentas especiales que no requieren un número de teléfono y sirven como interfaz para el código que se ejecuta en tu servidor.

Cada solicitud que realizas se autentica con un token de bot en lugar de una cuenta de usuario. El token identifica al bot, por lo que debes tratarlo como una contraseña y nunca subirlo a un repositorio público. La documentación de Telegram lo dice claramente: guarda tu token en un lugar seguro y no lo compartas.

La API en sí es gratuita. Telegram ha ofrecido la API de bots sin costo desde su lanzamiento, sin tarifas por mensaje y sin límite en la cantidad de bots que puedes crear. Por eso, muchas herramientas comunitarias, asistentes de soporte y automatizaciones se ejecutan en ella. Si eres nuevo en la plataforma, nuestra guía sobre cómo crear un bot de Telegram cubre la configuración de la cuenta con más detalle.

Paso 1: Obtén un token de bot de BotFather

Abre Telegram y busca @BotFather, el bot oficial para crear y gestionar otros bots. Inicia un chat y envía el comando /newbot.

BotFather te pedirá dos cosas en orden:

1. Un nombre de visualización para tu bot, como “Mi Primer Bot API”.
2. Un nombre de usuario que termine en bot, como mi_primer_bot_demo.

Cuando termines, BotFather te devolverá un token de API que se parece a 123456789:AAExampleTokenStringHere. Este token es la única credencial que necesitarás para el resto de este tutorial.

Atención: Cualquiera con tu token controla tu bot. Guárdalo en una variable de entorno, no en el código fuente. Si se filtra, envía /revoke a BotFather y obtén uno nuevo.

Paso 2: Llama a tu primer método de la API de bots

Antes de escribir cualquier programa, confirma que el token funciona. El método getMe devuelve información básica sobre tu bot y es la comprobación de estado estándar. Reemplaza <YOUR_TOKEN> con el valor de BotFather.

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

Una respuesta exitosa es un JSON con "ok": true y el ID, nombre y nombre de usuario de tu bot. Si ves "ok": false, el token es incorrecto o tiene un error tipográfico.

Esa única solicitud es el patrón completo. Cada método de la API de bots de Telegram sigue la misma estructura: una llamada HTTPS a https://api.telegram.org/bot<TOKEN>/METHOD_NAME, con parámetros en la cadena de consulta o en el cuerpo de la solicitud POST, y un objeto JSON como respuesta. La lista completa se encuentra en la referencia de la API de bots, que documenta cada método y objeto que puedas necesitar.

Paso 3: Recibe y envía mensajes

Ahora, hagamos que el bot sea útil. Hay una regla que sorprende a los principiantes: un bot no puede iniciar una conversación. El usuario tiene que enviar un mensaje al bot primero. Así que abre tu bot en Telegram y envíale cualquier texto, como “hola”.

Luego, lee ese mensaje con getUpdates, que obtiene las actualizaciones entrantes usando long polling y devuelve un array de objetos de actualización.

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

En la respuesta, busca message.chat.id. Ese chat_id es la dirección a la que responderás. Cópialo y luego llama a sendMessage:

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Hola desde mi primer bot"

Tu bot responderá en el chat. Ese ciclo de ida y vuelta, leer con getUpdates y responder con sendMessage, es el bucle central detrás de la mayoría de los bots de Telegram. El parámetro text acepta hasta 4096 caracteres por mensaje, por lo que las respuestas largas deben dividirse.

Dos detalles a recordar a medida que escalas este ejemplo de la API de bots de Telegram a código real:

• Recalcula el offset. Pasa el update_id de la última actualización más uno como parámetro offset en tu próxima llamada a getUpdates, o Telegram seguirá devolviendo las mismas actualizaciones.
• Un método a la vez. getUpdates deja de funcionar en el momento en que registras un webhook, que es el tema del siguiente paso.

Paso 4: Elige entre long polling o un webhook

Telegram ofrece dos formas de recibir actualizaciones, y solo puedes usar una por bot a la vez.

• Long polling significa que tu código llama repetidamente a getUpdates. Es el camino más fácil para el aprendizaje y el desarrollo local porque no necesita una URL pública, solo un proceso que se mantenga en ejecución.
• Webhooks significan que Telegram envía cada actualización a tu endpoint HTTPS como una solicitud POST en el instante en que ocurre. Este es el estándar de producción: menor latencia, sin polling inactivo y escala mejor bajo tráfico constante.

Para cambiar a un webhook, registra tu URL HTTPS pública una vez:

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

Tu endpoint necesita un certificado TLS válido y debe devolver HTTP 200 rápidamente. Si las actualizaciones dejan de llegar, el primer paso es siempre inspeccionar el error. Para el flujo completo de registro, verificación y solución de problemas, consulta nuestra guía de configuración de webhook para bots de Telegram. En resumen: comienza con polling mientras construyes, pasa a un webhook antes de lanzar.

Paso 5: Envuelve la API en una librería

El cURL puro es excelente para aprender, pero los bots de producción utilizan una librería. Una librería maneja las llamadas a la API, el análisis de actualizaciones, los reintentos y el estado de la conversación, para que solo escribas la lógica específica de tu bot. Telegram enumera librerías comunitarias para casi todos los lenguajes en su página de ejemplos de la API de bots.

Elige según el lenguaje que ya conozcas:

• Python: python-telegram-bot es Python puro, completamente asíncrono y compatible con Python 3.10 y versiones posteriores. aiogram y pyTelegramBotAPI son alternativas populares.
• Node.js: Telegraf es maduro y compatible con TypeScript. node-telegram-bot-api es una opción de larga trayectoria.

Aquí tienes el mismo bot de eco en Python, el punto de partida más común para un tutorial de la API de bots de Telegram en 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()

Y el equivalente en 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()

Ambos hacen el mismo trabajo que el bucle cURL del Paso 3, pero en unas pocas líneas y con las partes complicadas resueltas por ti. María, una desarrolladora backend que prototipaba un bot de soporte, pasó de las pruebas con cURL a python-telegram-bot en una tarde y tenía manejadores de comandos y botones en línea funcionando el mismo día. Los conceptos de la API se trasladaron directamente porque la librería es una capa delgada sobre los mismos métodos HTTP.

Límites de tasa y cuotas a tener en cuenta

La API es gratuita, pero no ilimitada. Las Preguntas Frecuentes de Bots de Telegram enumeran las pautas para evitar que tu bot sea limitado.

• Un mensaje por segundo por chat. En una sola conversación, evita enviar más rápido que eso.
• Aproximadamente 30 mensajes por segundo en total al enviar a muchos usuarios diferentes. Si te excedes, empezarás a recibir respuestas HTTP 429 “Too Many Requests”.
• Aproximadamente 20 mensajes por minuto al mismo grupo.

Cuando una transmisión realmente necesita más, puedes habilitar las Transmisiones Pagadas en @BotFather, lo que eleva el límite a 1000 mensajes por segundo. Los mensajes que superan los 30 por segundo gratuitos cuestan 0.1 Telegram Stars cada uno. La mayoría de los bots nunca necesitan esto, pero es bueno conocer el límite antes de diseñar una función de notificación.

Respeta un 429 leyendo el valor retry_after que devuelve Telegram y pausando durante esa cantidad de segundos. Una librería se encarga de esto por ti, lo cual es una razón más para pasar de las solicitudes directas una vez que tu tráfico es real.

Olvídate del código: bots de IA sin servidor

No todos los proyectos necesitan una base de código personalizada. Si tu objetivo es un asistente de IA en un grupo de Telegram, la API de bots es una infraestructura que quizás no quieras mantener tú mismo, especialmente el alojamiento, HTTPS y la capa de webhook.

TeleClaw es una plataforma sin código que ejecuta el bot por ti y conecta Claude AI de forma predeterminada. Añades @claw a tu grupo, pegas tu token de BotFather en el panel de control y configuras el comportamiento sin tocar setWebhook ni la gestión de límites de tasa. Tomás, quien dirige una comunidad de criptomonedas de 4,000 miembros, reemplazó un bot personalizado a medio terminar con TeleClaw y tuvo moderación de IA y respuestas a preguntas frecuentes en vivo la misma noche.

Es la misma API de bots subyacente. Estás eligiendo si operar la capa del servidor tú mismo o dejar que una plataforma lo haga. Explora lo que cubre esto en la página de características de TeleClaw y compara opciones en nuestro resumen de los mejores bots de Telegram. Para una construcción puramente desde el panel de control, consulta nuestra guía de chatbot de Telegram sin código.

Conclusión

Ahora tienes un modelo mental funcional de la API de bots de Telegram: un token de BotFather, métodos HTTP como getMe, getUpdates y sendMessage, una elección entre long polling y webhooks, y una librería para envolverlo todo una vez que tu bot crezca. La API es gratuita, está bien documentada y es lo suficientemente accesible como para probarla con cURL en minutos.

El siguiente paso más rápido es el más pequeño. Abre @BotFather, ejecuta /newbot y envía tu primera solicitud getMe para confirmar el token. A partir de ahí, puedes construir en Python o Node, o saltarte el servidor por completo. Para lanzar un bot impulsado por IA en minutos en lugar de días, añade @claw a tu grupo y configúralo en el panel de control de TeleClaw.