Telegram Serverless: ejecuta el backend de tu bot sin servidor

⏱️ Lectura: 13 min

Telegram acaba de convertir su propia infraestructura en el hosting de tu bot: con Telegram Serverless, el código que responde a un mensaje o a un botón corre directo en los servidores de Telegram, sin que tengas que levantar una VPS, un contenedor ni una función en la nube de un tercero.

📑 En este artículo

1. TL;DR
2. Qué es Telegram Serverless y por qué importa
3. Cómo funciona el modelo mental de tres capas
4. Ejemplos prácticos: de hola mundo a un caso real
5. Cómo empezar paso a paso
6. Casos de uso reales
7. Errores comunes y buenas prácticas
8. Comparativa con alternativas
9. Profundizando: qué pasa por dentro
10. Preguntas frecuentes
    1. ¿Telegram Serverless reemplaza completamente a un VPS?
    2. ¿Qué pasa con los datos si mi bot recibe mucho tráfico de golpe?
    3. ¿Puedo usar librerías npm externas dentro de los módulos?
    4. ¿Necesito una cuenta de Telegram Business o de desarrollador especial?
    5. ¿Cómo pruebo un handler antes de desplegarlo a producción?
    6. ¿Las migraciones de schema.js se pueden revertir?
11. Referencias
    1. 📚 Artículos relacionados

Si alguna vez montaste un servidor solo para que tu bot conteste /start, esta plataforma elimina ese paso por completo: escribís módulos de JavaScript, los desplegás con un comando y Telegram los ejecuta junto a su propia API y a una base de datos incluida.

TL;DR

• Entendés qué es Telegram Serverless y cómo reemplaza a un VPS o cloud function para bots.
• Aprendés el modelo de tres capas: carpeta local, la nube de Telegram y el CLI tgcloud.
• Vas a poder escribir handlers/message.js que respondan updates usando la API y una base SQLite.
• Sabés definir tablas con schema.js usando el DSL table() e integer() del SDK.
• Podés desplegar con npx tgcloud push y migrar el esquema con npx tgcloud migrate.
• Distinguís cuándo conviene Serverless frente a un VPS tradicional o una cloud function externa.
• Identificás los errores comunes al migrar un bot existente a este modelo.

Qué es Telegram Serverless y por qué importa

Telegram Serverless es un runtime de backend integrado a la plataforma: te deja escribir el código que procesa los updates de tu bot (mensajes, botones, inline queries) como módulos planos de JavaScript, sin administrar ningún servidor propio. Telegram lo ejecuta en un sandbox V8 aislado que corre cerca de la Bot API, lo que reduce la latencia entre recibir un update y responder.

La propuesta resuelve un problema que cualquiera que haya hecho un bot conoce: para que /start funcionara 24/7 hacía falta un proceso siempre encendido, alcanzable desde internet y parcheado. Con Serverless ese proceso no existe: tu código corre bajo demanda y escala automáticamente con el tráfico del bot.

La plataforma no es un template para un solo tipo de app. Según la documentación oficial, sirve para bots conversacionales con estado por usuario, para el backend de una Mini App, para juegos con tablas de puntajes y para automatizaciones que llaman APIs HTTP externas y publican resultados en un chat.

📌 Nota: antes de escribir una línea de código tenés que activar la función. En @BotFather: abrí tu bot, entrá a Serverless y activalo. Eso desbloquea el token del CLI, los handlers, la librería y la base de datos.

Cómo funciona el modelo mental de tres capas

Trabajás en tres lugares que se corresponden uno a uno. Tu carpeta local tiene el código versionado; la nube de Telegram tiene la copia desplegada de esos módulos más la base de datos de tu bot; y el CLI tgcloud es el puente que te muestra las diferencias entre ambos y las sincroniza.

Nunca hacés SSH a ningún lado. Editás archivos localmente, corrés npx tgcloud push y la plataforma se encarga del resto. El tráfico de tu bot lo maneja la copia desplegada; la base de datos persiste entre invocaciones aunque cada ejecución del handler sea efímera.

Un proyecto tiene solo tres tipos de código: handlers/ con un archivo por tipo de update, lib/ con código compartido que importás desde cualquier handler, y schema.js con las tablas de tu base de datos.

flowchart TD
    A["Carpeta local: handlers, lib, schema.js"] --> B["npx tgcloud push"]
    B --> C["La nube de Telegram: modulos + base de datos"]
    C --> D["Bot responde updates en produccion"]

Cuando llega un update (un mensaje, un botón presionado, una inline query), Telegram lo enruta al handler correspondiente (handlers/message.js, handlers/callback_query.js, etc.) y llama a su export por defecto. Esa función habla con la Bot API y con la base de datos a través del SDK, y retorna. Un update sin handler que lo atienda simplemente se ignora, así que agregás solo los handlers que necesitás.

Ejemplos prácticos: de hola mundo a un caso real

El handler más simple posible recibe un mensaje y contesta. No toca la base de datos, no importa nada más que el SDK de la API:

import { api } from 'sdk';

export default async function (message) {
  await api.sendMessage({
    chat_id: message.chat.id,
    text: `Recibi tu mensaje: ${message.text ?? '(sin texto)'}`,
  });
}

Este archivo va en handlers/message.js. Desplegado con npx tgcloud push, ya es un bot vivo que hace eco de cada mensaje: no hay base de datos ni estado, así que no hace falta correr ninguna migración.

El siguiente ejemplo se acerca a un caso real: un bot de soporte que cuenta cuántos tickets abrió cada chat y recuerda el último asunto. Primero definimos la tabla en schema.js:

import { table, integer, text } from 'sdk/db';

export const tickets = table('tickets', {
  chatId: integer('chat_id').primaryKey(),
  abiertos: integer('abiertos').notNull().default(0),
  ultimoAsunto: text('ultimo_asunto'),
});

Y después el handler que inserta o actualiza esa fila en cada mensaje, usando onConflictDoUpdate para incrementar el contador atómicamente:

import { api, db } from 'sdk';
import { tickets } from 'schema';
import { sql } from 'sdk/db';

export default async function (message) {
  const chatId = message.chat.id;
  const asunto = message.text ?? 'Sin asunto';

  const [fila] = await db.insert(tickets)
    .values({ chatId, abiertos: 1, ultimoAsunto: asunto })
    .onConflictDoUpdate({
      target: tickets.chatId,
      set: { abiertos: sql`${tickets.abiertos} + 1`, ultimoAsunto: asunto },
    })
    .returning()
    .run();

  await api.sendMessage({
    chat_id: chatId,
    text: `Ticket #${fila.abiertos} registrado para este chat. Asunto: ${fila.ultimoAsunto}`,
  });
}

Con esto ya tenés un bot con estado persistente por chat, sin haber tocado un servidor. El resultado esperado: cada mensaje nuevo devuelve un número de ticket que se incrementa y guarda el último asunto recibido.

sequenceDiagram
    participant U as Usuario
    participant T as Telegram
    participant H as Handler en V8
    participant D as Base de datos
    U->>T: envia mensaje
    T->>H: entrega el update
    H->>D: inserta o actualiza fila
    D-->>H: devuelve fila actualizada
    H-->>T: llama a api.sendMessage
    T-->>U: muestra la respuesta

Cómo empezar paso a paso

Hace falta Node.js 18 o superior y un bot ya registrado con @BotFather. Primero instalá Node según tu sistema operativo.

Windows:

winget install OpenJS.NodeJS.LTS

macOS:

brew install node

Linux (Debian/Ubuntu):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Con Node instalado, el resto de los pasos es idéntico en las tres plataformas. Primero activá Serverless en @BotFather (Bot → Serverless → activar) y después creá el proyecto:

npm create @tgcloud/bot soporte_bot
cd soporte_bot

El comando scaffolda una carpeta lista para editar, con un handler de ejemplo en handlers/message.js y un archivo docs/tgcloud-sdk.md con la referencia del SDK. Pasá . como argumento si querés scaffoldear en la carpeta actual.

Escribí tu schema.js y tus handlers como en los ejemplos anteriores, y después desplegá:

npx tgcloud push
npx tgcloud migrate
npx tgcloud status

push sube tus módulos, migrate aplica los cambios de esquema pendientes contra la base de datos en la nube, y status te muestra qué versión está corriendo en producción y si hay diferencias sin desplegar. Usá run para probar un handler puntual antes de desplegar.

Casos de uso reales

Un bot conversacional con IA que necesita recordar el contexto de cada usuario entre mensajes encaja naturalmente: el estado vive en la tabla, no en memoria de un proceso que puede reiniciarse. Un backend de Mini App puede usar los mismos handlers para servir datos dinámicos al frontend embebido en Telegram sin exponer un endpoint público aparte.

Para juegos y herramientas, la base de datos incluida sirve para tablas de posiciones y cuestionarios sin contratar un motor externo. Y para automatizaciones e integraciones, el HTTP saliente disponible en cada módulo permite llamar APIs de terceros y publicar el resultado en un canal, por ejemplo un bot que revisa un feed cada cierto tiempo y postea alertas.

Errores comunes y buenas prácticas

El error más frecuente al migrar un bot existente es olvidar que no hay sistema de archivos persistente: cualquier estado que tu bot necesite recordar entre invocaciones tiene que vivir en la tabla de schema.js, no en una variable global ni en un archivo temporal.

⚠️ Ojo: si corrés tgcloud push sin haber corrido tgcloud migrate después de agregar una tabla nueva, el handler va a fallar al intentar leer o escribir en una tabla que todavía no existe en la base desplegada.

Otro descuido típico es asumir que un update sin handler dispara algún error: en realidad se ignora en silencio, así que si tu bot no responde a un tipo de update conviene revisar primero si falta el archivo correspondiente en handlers/ antes de sospechar de la lógica interna.

Por último, tratá las migraciones como código revisado, no como un paso automático: cada cambio de esquema queda registrado y versionado junto al resto del proyecto, así que un git diff sobre schema.js debería ser tan legible como cualquier otro cambio de código.

Comparativa con alternativas

Opción	Cuándo usarla	Ventaja	Limitación
Telegram Serverless	Bots y Mini Apps sin necesidad de infraestructura propia	Cero servidores, base de datos y API incluidas, deploy atómico	Acoplado a Telegram, no sirve para lógica fuera del ecosistema del bot
VPS propio	Bots que ya integran otros servicios propios o requieren control total del entorno	Control absoluto del runtime y del sistema operativo	Hay que mantenerlo encendido, parchearlo y escalarlo manualmente
Cloud Function (Lambda, Cloud Run)	Backends que además de Telegram sirven a otros clientes o canales	Portable entre proveedores, integra con el resto de un stack cloud	Hay que conectar vos mismo la Bot API, la base de datos y las credenciales
Hosting panel (tipo cPanel/Heroku)	Prototipos rápidos con interfaz gráfica de administración	Configuración visual, poco conocimiento de infraestructura necesario	Menos control fino, dependencia del proveedor del panel

Profundizando: qué pasa por dentro

Cada invocación de un handler corre en un V8 isolate liviano, el mismo mecanismo de aislamiento que usan runtimes como Cloudflare Workers o Deno Deploy: un contexto de ejecución separado por invocación, sin el costo de arrancar un proceso del sistema operativo completo. Al correr físicamente cerca de la infraestructura de la Bot API, las llamadas a api.* y a la base de datos tienen menos saltos de red que un handler alojado en otro proveedor cloud.

💭 Clave: el deploy es atómico: tgcloud push reemplaza todos los módulos de una vez, no archivo por archivo, así que no hay una ventana donde el bot corra con una mezcla de código viejo y nuevo.

La base de datos incluida está respaldada por SQLite, lo que explica por qué el SDK expone un DSL de tablas (table(), integer(), text()) en vez de pedirte una cadena de conexión: no hay un servidor de base de datos aparte que configurar, solo el archivo gestionado por la plataforma.

flowchart LR
    A["Editar schema.js y handlers/"] --> B["npx tgcloud push"]
    B --> C["npx tgcloud migrate"]
    C --> D["npx tgcloud status"]
    D --> E["Bot en produccion"]

Para confirmar que un deploy quedó activo, npx tgcloud status muestra la versión desplegada y si tu copia local difiere de la nube; no hace falta ningún panel externo para verificarlo.

📖 Resumen en Telegram: Ver resumen

Tu próximo paso: cloná el proyecto de ejemplo con npm create @tgcloud/bot, agregale una tabla propia en schema.js y desplegala con tgcloud push seguido de tgcloud migrate para ver el ciclo completo en un bot real.

Preguntas frecuentes

¿Telegram Serverless reemplaza completamente a un VPS?

Para la lógica del bot en sí, sí. Si tu backend además sirve a otros clientes fuera de Telegram, vas a seguir necesitando esa infraestructura aparte.

¿Qué pasa con los datos si mi bot recibe mucho tráfico de golpe?

La ejecución escala automáticamente porque cada invocación corre en su propio isolate; no hay un proceso único que se sature.

¿Puedo usar librerías npm externas dentro de los módulos?

El proyecto se estructura como código JavaScript estándar en lib/, aunque las dependencias externas quedan sujetas a lo que soporte el sandbox V8 de la plataforma.

¿Necesito una cuenta de Telegram Business o de desarrollador especial?

No, alcanza con un bot registrado en @BotFather con la opción Serverless activada desde el panel del bot.

¿Cómo pruebo un handler antes de desplegarlo a producción?

El CLI incluye el comando run para ejecutar un handler puntual localmente antes de subirlo con push.

¿Las migraciones de schema.js se pueden revertir?

Se gestionan como cambios revisados dentro del flujo normal de tgcloud migrate, versionados junto al resto del proyecto igual que cualquier otro archivo de código.

Referencias

• Telegram Serverless: documentación oficial con la referencia completa del SDK, el CLI y el modelo de proyecto.
• Telegram Bot API: referencia de los métodos disponibles en el objeto api del SDK.
• SQLite: motor de base de datos que respalda el almacenamiento incluido en cada proyecto.
• Node.js: runtime requerido en versión 18 o superior para usar el CLI tgcloud.

📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.

Imagen destacada: Foto de Hazel Z en Unsplash