MANUAL AVANZADO · TU PRIMER AGENTE EN TELEGRAM · V1
Imaquinua
Un agente en tu Telegram. Costo: cero.
Ya escribes prompts con criterio y guardaste tu método en un skill. El siguiente paso: darle al skill un lugar donde vivir. Este manual arma un agente que responde en Telegram usando solo piezas con capa gratuita — sin servidor propio y sin tarjeta de crédito.
La arquitectura, en cuatro piezasTODAS CON CAPA GRATUITA
1
LA CARA · EL BOT DE TELEGRAMDonde tu equipo conversa con el agente. Se crea hablando con @BotFather.
$0 SIEMPRE
2
EL CARTERO · EL WEBHOOKUn pedazo de código en la nube que recibe cada mensaje y devuelve la respuesta. Vive en Cloudflare Workers.
$0 · 100K/DÍA
3
EL CRITERIO · TU SKILLEl skill que escribiste en el manual anterior, pegado como instrucción de sistema. Es lo único que no se descarga: es tuyo.
TU VENTAJA
4
EL MOTOR · LA API DEL MODELOEl modelo de lenguaje que redacta. Gemini (Google AI Studio) o Llama vía Groq tienen API key gratuita.
$0 CON LÍMITES
El flujo completo: alguien escribe al bot → Telegram avisa al cartero → el cartero arma el mensaje con tu skill → el motor responde → el cartero lo devuelve al chat. Todo en un par de segundos.
Un agente no es magia: es tu skill con un número de teléfono.01 / 04
AGENTE EN TELEGRAM · LAS DECISIONES ANTES DE ESCRIBIR CÓDIGO
02 / 04
¿Con código o sin código?
RUTA A · CON CÓDIGO (LA DE ESTE MANUAL)Cloudflare Workers: pegas un script de ~40 líneas, gratis hasta 100.000 mensajes al día, tuyo para siempre. Si sabes copiar, pegar y leer con calma, puedes.
RUTA B · SIN CÓDIGOMake o n8n conectan Telegram y el modelo con bloques visuales. La capa gratuita alcanza para probar (~1.000 operaciones/mes); para uso diario, quedará corta.
¿Qué motor gratuito elegir?
GEMINI · GOOGLE AI STUDIOAPI key gratis en minutos. Buen español, límites diarios generosos para un equipo chico.
LLAMA VÍA GROQRapidísimo y con capa gratuita. Modelo abierto: si mañana quieres mudarte, el skill viaja contigo.
Los límites gratuitos cambian cada pocos meses: revisa la página de precios el día que empieces. La arquitectura no cambia; el motor se cambia en una línea.
Las tres reglas de seguridadNO NEGOCIABLES
1El token es una llave, no un dato. Va en las variables secretas del worker, nunca pegado en el código ni compartido por chat. Quien tiene el token, es el bot.
2Lista blanca de chats. El worker responde solo a los IDs de tu equipo. Un bot abierto al mundo es tu API key pagando la curiosidad de extraños.
3Nada sensible por el bot. Ni contraseñas, ni datos de clientes, ni cifras que no pondrías en un correo externo. El agente v1 es para trabajo, no para secretos.
Decide las tres cosas de esta página antes de tocar el teclado. Es media hora que ahorra semanas.IMAQUINUA · AGENTE TELEGRAM
AGENTE EN TELEGRAM · LA RECETA · ~1 HORA
03 / 04
De cero a agente, en 6 pasos
1
Crea el bot con @BotFatherEn Telegram, busca @BotFather → /newbot → nombre y usuario. Te devuelve el token. Guárdalo como la llave que es.
2
Saca tu API key gratuita del motorGoogle AI Studio (Gemini) o console.groq.com (Llama). Cuenta, botón «crear API key», listo. Tampoco se comparte.
3
Crea el worker (el cartero)Cuenta gratis en Cloudflare → Workers → «crear worker» → pega la lógica de abajo. El token y la API key van en variables secretas, no en el código.
4
Pega tu skill como instrucción de sistemaEl archivo del manual anterior, completo: propósito, método, reglas, ejemplos, formato. Aquí es donde tu agente deja de ser un chatbot genérico.
5
Conecta Telegram con tu workerAbre en el navegador: api.telegram.org/bot<TOKEN>/setWebhook?url=<URL-DEL-WORKER> — si responde «ok», ya están casados.
6
Pruébalo 10 veces y corrige el skill, no el códigoCon casos reales de tu semana. Si responde mal, el 90% de las veces la falla está en el skill. Versión nueva, prueba de nuevo.
LA LÓGICA DEL CARTERO · PSEUDOCÓDIGO — PÍDELE A TU IA QUE LO CONVIERTA EN CÓDIGO REAL
cuando llegue un mensaje de Telegram:
si el chat_id NO está en mi lista blanca → ignorar
tomar el texto del mensaje
armar la llamada al motor:
sistema = MI SKILL (completo)
usuario = el texto + los últimos 10 mensajes del chat
pedir la respuesta al motor (Gemini o Groq)
enviarla de vuelta con sendMessage al mismo chat_id
guardar el par pregunta/respuesta para la memoria
Sí: puedes pegarle esta página a tu IA y pedirle el worker completo. Eso también es el método — tú pones el criterio de qué debe hacer; ella escribe la sintaxis.
La memoria v1 es humilde: los últimos 10 mensajes. Suficiente para conversar; imposible de romper.IMAQUINUA · AGENTE TELEGRAM
AGENTE EN TELEGRAM · ANTES DE SOLTARLO AL EQUIPO
04 / 04
Checklist de lanzamiento
El token y la API key viven en variables secretas, no en el código.
La lista blanca tiene solo los chat IDs del equipo — probado con un extraño.
El skill tiene versión, fecha y dueño con nombre propio.
Pasó las 10 pruebas con casos reales y las correcciones fueron al skill.
El equipo sabe qué NO preguntarle — y que el criterio final sigue siendo humano.
La cuenta, en serio
PIEZA
COSTO
EL LÍMITE REAL
Bot de Telegram
$0
Ninguno que te toque
Cloudflare Workers
$0
100.000 mensajes/día
API del modelo
$0
Cuota diaria del free tier; si la pasas, felicidades: ya mide su valor
Lo que viene después del v1
Herramientas: que el agente consulte tu hoja de precios o tu calendario antes de responder. Memoria larga: que recuerde clientes y acuerdos. Varios skills: un agente por trabajo, no uno que hace todo.Cada uno de esos pasos toca datos de tu operación — y ahí ya no se juega: se diseña con criterio, permisos y medición. Ese es exactamente nuestro trabajo.
¿El agente ya trabaja y quieres conectarlo a tu operación?La ruta de Automatizaciones del workshop gratuito arma el caso con tus herramientas reales.