Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes
Para conectar n8n con Telegram solo necesitas una cosa de Telegram: el token de un bot. Guárdalo como Access Token de una credencial de Telegram en n8n y luego usa el nodo Telegram Trigger para iniciar flujos con los mensajes entrantes y el nodo Telegram para enviar mensajes a un chat id. El trigger funciona con un webhook de la Bot API, así que tu instancia de n8n debe ser accesible desde una URL HTTPS pública. Esta guía cubre la configuración, lo que necesita n8n autoalojado y los errores más frecuentes.
Cómo funciona la integración de n8n con Telegram
| Nodo | Qué hace | Bot API por debajo | ¿Necesita HTTPS público? |
|---|---|---|---|
| Telegram Trigger | Inicia el flujo con una actualización: un mensaje, la pulsación de un botón, una publicación en un canal, etc. | setWebhook; después Telegram envía las actualizaciones a n8n por POST | Sí |
| Telegram | Envía y edita mensajes, envía archivos, responde callback queries, lee información del chat | sendMessage, sendPhoto, editMessageText, answerCallbackQuery… | No, solo peticiones salientes |
Como el trigger usa un webhook, a n8n también le aplican las reglas de webhooks de la Bot API: solo HTTPS, puertos 443, 80, 88 u 8443, una URL de webhook por bot y nada de getUpdates mientras el webhook esté configurado.
Paso 1: crear un bot y obtener el token
- Abre @BotFather, envía
/newboty elige un nombre visible y un username que termine enbot. - Copia el token que te devuelve BotFather. Se ve así:
123456789:AAEexampleTokenReplaceWithYours. Para un bot que ya existe, abre/mybots→ tu bot → API Token. - Verifica el token antes de pegarlo en cualquier lado:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"
Un token válido devuelve "ok": true con los datos del bot; uno incorrecto devuelve 401 Unauthorized. Puedes hacer la misma prueba con getMe en Bot API Tester. Cómo encontrar, verificar y revocar tokens lo explicamos en la guía del token de bot de Telegram; si aún no tienes bot, empieza por cómo crear un bot en Telegram.
Paso 2: agregar las credenciales de Telegram en n8n
n8n se autentica ante Telegram solo con el token del bot. Crea una credencial de Telegram nueva y pega el token en su campo Access Token. El nodo Telegram y el nodo Telegram Trigger usan el mismo tipo de credencial, así que basta con una credencial por bot.
Trata el token como una contraseña: quien lo tenga controla el bot. Si se filtra, revócalo en @BotFather y actualiza la credencial en n8n.
Paso 3: recibir actualizaciones con el webhook del Telegram Trigger de n8n
Agrega un nodo Telegram Trigger, selecciona tu credencial y elige qué actualizaciones deben iniciar el flujo. Lo típico es Message para los mensajes entrantes y Callback Query para las pulsaciones de botones inline; * significa todas las actualizaciones excepto las de miembros del chat y reacciones, igual que el valor por defecto de la Bot API. El nodo también se puede limitar a ciertos chat id o user id, y puede descargar las imágenes y archivos adjuntos.
Cuando pruebas el flujo o lo publicas, n8n llama a setWebhook para tu bot con una URL de su propia instancia. A partir de ahí, Telegram envía cada actualización a n8n como un POST HTTPS. De esto se derivan dos cosas:
- Las URL de prueba y de producción se sobrescriben entre sí. n8n usa URL de webhook distintas para probar en el editor y para el flujo publicado. Telegram guarda una sola URL por bot, así que recibe las actualizaciones la que se registró al último. Despublica el flujo mientras pruebas o usa otro bot para pruebas.
- Un bot, un trigger. Dos flujos, o dos instancias de n8n, con un Telegram Trigger sobre el mismo bot se reemplazan el webhook una y otra vez. Usa un trigger por bot y ramifica dentro del flujo, por ejemplo con un nodo Switch sobre el texto del mensaje.
Hacer accesible por HTTPS un n8n autoalojado
n8n Cloud ya tiene una dirección HTTPS pública. Una instancia autoalojada arma sus URL de webhook a partir de su propio protocolo, host y puerto, lo que detrás de un proxy inverso o en localhost suele dar una dirección http:// que Telegram rechaza. La solución:
- Pon n8n detrás de un proxy inverso (nginx, Caddy, Traefik, etc.) que termine TLS con un certificado válido en el puerto 443.
- Indícale a n8n su dirección pública. Las versiones actuales de n8n usan
N8N_WEBHOOK_URL; la antiguaWEBHOOK_URLestá obsoleta desde n8n 2.35.0 pero se sigue leyendo, y las versiones anteriores a 2.30.0 solo conocenWEBHOOK_URL. - Define
N8N_PROXY_HOPS=1y reenvía desde el proxy los encabezadosX-Forwarded-For,X-Forwarded-HostyX-Forwarded-Proto. - Activa el proxy de WebSocket; si no, el editor puede parecer congelado mientras espera un evento de prueba del trigger.
- Reinicia n8n y vuelve a activar el flujo para que el trigger registre la nueva URL HTTPS.
# n8n detrás de un proxy inverso que sirve https://n8n.example.com
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# versiones de n8n anteriores a 2.30.0: usa WEBHOOK_URL en su lugar
# export WEBHOOK_URL=https://n8n.example.com/
Para desarrollo local, un túnel que te dé un hostname HTTPS público funciona igual: pon ese hostname en N8N_WEBHOOK_URL. Ten en cuenta que el webhook se rompe cada vez que cambia la dirección del túnel.
Comprobar qué webhook tiene Telegram para tu bot
Cuando el trigger no recibe nada, pregúntale directamente a Telegram con getWebhookInfo. Muestra la URL registrada, cuántas actualizaciones esperan y el último error de entrega. Este script imprime un diagnóstico breve:
import os
import requests
TOKEN = os.environ["BOT_TOKEN"] # el mismo token que en la credencial de n8n
API = f"https://api.telegram.org/bot{TOKEN}"
data = requests.get(f"{API}/getWebhookInfo", timeout=10).json()
if not data["ok"]:
raise SystemExit(f"{data['error_code']} {data['description']}") # 401: token incorrecto
info = data["result"]
print("URL del webhook:", info["url"] or "(ninguna: no hay un Telegram Trigger activo)")
print("Actualizaciones pendientes:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
print("Problema: Telegram necesita una URL HTTPS")
if "last_error_message" in info:
print("Último error de entrega:", info["last_error_message"])const TOKEN = process.env.BOT_TOKEN; // el mismo token que en la credencial de n8n
const API = `https://api.telegram.org/bot${TOKEN}`;
const data = await (await fetch(`${API}/getWebhookInfo`)).json();
if (!data.ok) {
console.error(`${data.error_code} ${data.description}`); // 401: token incorrecto
process.exit(1);
}
const info = data.result;
console.log("URL del webhook:", info.url || "(ninguna: no hay un Telegram Trigger activo)");
console.log("Actualizaciones pendientes:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
console.log("Problema: Telegram necesita una URL HTTPS");
}
if (info.last_error_message) {
console.log("Último error de entrega:", info.last_error_message);
}Guarda la versión de JavaScript como check.mjs y ejecútala con Node.js 18 o superior. Cómo leer el resultado: si la URL es de otro servicio, algo más se quedó con el webhook del bot; si pending_update_count crece y hay un last_error_message, Telegram no llega a n8n o n8n responde con un error. Sin código, usa getWebhookInfo en Bot API Tester.
Paso 4: enviar mensajes de Telegram desde n8n
Agrega un nodo Telegram, elige el recurso Message y la operación Send Message, selecciona la credencial y completa dos campos:
- Chat ID: un id numérico como
123456789, o@channelusernamepara un canal público. En un flujo que empieza con el Telegram Trigger, asígnalo con una expresión a$json.message.chat.idpara que el bot responda en el mismo chat. - Text: hasta 4096 caracteres después de procesar las entidades, el límite de
sendMessage.
Hay dos valores por defecto que sorprenden. El nodo agrega la línea This message was sent automatically with n8n; desactiva Append n8n Attribution en los campos adicionales para quitarla. Y el parse mode del nodo es HTML por defecto, así que escapa <, > y & en el texto dinámico como <, > y &, o Telegram rechazará el mensaje con un error can't parse entities.
Antes de conectar un chat id a un flujo, puedes confirmar que funciona con una sola petición en sendMessage en Bot API Tester. Para publicar en un canal, primero agrega el bot como administrador del canal. Telegram permite unos 30 mensajes por segundo en envíos masivos y alrededor de uno por segundo en un mismo chat, así que regula los bucles de difusión; consulta los límites de la Telegram Bot API.
Cómo encontrar el chat id
La fuente más fácil es el propio trigger: ejecuta el flujo, escríbele al bot y lee message.chat.id en la salida del trigger. Los usuarios tienen id positivos, los grupos negativos, y los supergrupos y canales se ven como -1001234567890. Si prefieres getUpdates, llámalo antes de que haya un Telegram Trigger activo para ese bot; mientras el webhook esté configurado, falla con 409 Conflict. Todos los métodos, incluidos grupos, canales y temas de foros, están en cómo obtener el chat id de Telegram.
Solución de errores de n8n con Telegram
| Síntoma | Causa | Solución |
|---|---|---|
Bad Request: bad webhook: An HTTPS URL must be provided for webhook | n8n registró una URL http://: localhost o un proxy sin TLS | Termina TLS en el proxy y define N8N_WEBHOOK_URL (o WEBHOOK_URL) con la dirección HTTPS |
| Error de bad webhook sobre el puerto | La URL pública usa un puerto distinto de 443, 80, 88 u 8443 | Expón n8n en el 443 a través del proxy |
409 Conflict en getUpdates | Un Telegram Trigger mantiene un webhook registrado | Desactiva el flujo y llama a deleteWebhook, o toma los chat id del trigger |
| El flujo funciona solo en pruebas o solo publicado | Las URL de webhook de prueba y producción se reemplazan entre sí | Despublica mientras pruebas o usa un bot de pruebas aparte |
| El trigger dejó de funcionar al activar otro flujo | Un segundo trigger, u otro servicio, llamó a setWebhook con el mismo token | Un trigger por bot; revisa la URL con getWebhookInfo |
| El editor se queda en “waiting for trigger event” | Proxy inverso sin soporte de WebSocket | Activa el proxy de WebSocket y vuelve a abrir el flujo |
| No llegan actualizaciones de mensajes de grupo | Modo privacidad: en grupos el bot solo recibe los comandos dirigidos a él, las respuestas a sus mensajes y los mensajes de servicio | Desactiva la privacidad con /setprivacy o haz al bot administrador |
401 Unauthorized | Token incorrecto o revocado en la credencial | Verifícalo con getMe y pega el token vigente |
400 Bad Request: chat not found al enviar | Chat id incorrecto o un chat al que el bot no tiene acceso: el usuario nunca lo inició o el bot no está en el grupo | Revisa el id; pide al usuario que envíe /start o agrega el bot al grupo |
Para empezar desde cero, desactiva el flujo, llama a deleteWebhook, comprueba que getWebhookInfo muestre una url vacía y vuelve a activar el flujo para que n8n registre su URL de nuevo. Para la mecánica de los webhooks en general (secret tokens, reintentos, certificados), consulta la guía del webhook de bots de Telegram.
Preguntas frecuentes
¿Cómo conecto Telegram con n8n?
Crea un bot con @BotFather, copia su token y guárdalo como Access Token de una credencial de Telegram en n8n. Usa el nodo Telegram Trigger para recibir mensajes y el nodo Telegram para enviarlos; ambos usan la misma credencial.
¿Por qué el Telegram Trigger de n8n dice “An HTTPS URL must be provided for webhook”?
El trigger registra un webhook con setWebhook, y Telegram solo acepta URL HTTPS públicas. Si n8n corre en http://localhost o detrás de un proxy sin TLS, define la dirección HTTPS pública de tu instancia en N8N_WEBHOOK_URL (WEBHOOK_URL en versiones antiguas) y termina TLS en el proxy inverso.
¿Dos flujos de n8n pueden usar el trigger del mismo bot de Telegram?
No de forma confiable. Un bot tiene una sola URL de webhook, así que cada activación sobrescribe la anterior y solo el último flujo recibe las actualizaciones. Usa un trigger por bot, reparte dentro de un único flujo o crea otro bot.
¿Por qué getUpdates devuelve 409 Conflict después de configurar n8n?
Un Telegram Trigger activo mantiene un webhook registrado para el bot, y getUpdates no funciona mientras haya un webhook. Desactiva el flujo y llama a deleteWebhook si necesitas polling, o toma los chat id de la salida del trigger.
¿Necesito una URL HTTPS pública solo para enviar mensajes de Telegram desde n8n?
No. El nodo Telegram solo hace peticiones salientes a api.telegram.org, así que el envío funciona desde una instancia local de n8n. El HTTPS público solo hace falta para recibir actualizaciones con el Telegram Trigger.
¿Dónde encuentro el chat id para el nodo Telegram de n8n?
Tómalo de la salida del trigger (message.chat.id), o escríbele al bot y llama a getUpdates antes de activar el trigger. Los canales públicos también aceptan @channelusername.
Guías relacionadas
Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje
Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.
Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless
Cómo desplegar un bot de Telegram: polling o webhook, servicio systemd en un VPS, Docker, Cloudflare Workers con secret_token y checklist de lanzamiento.
Telegram Bot API 10.0–10.5: ajustes del bot, widgets, rich messages, mensajes efímeros, modo invitado y más
Qué hay de nuevo en Telegram Bot API 10.0–10.5: setMySettings y BotFullInfo, widgets HTML, mensajes rich y efímeros, modo invitado, con ejemplos JSON.
Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo
Errores de la Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict y 429 retry_after. Causas, soluciones y código de manejo.
Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes
Límites de la Telegram Bot API: 30 msg/s, 1 msg/s por chat, 20/min en grupos, cómo manejar 429 con retry_after y límites de tamaño de archivo y de texto.
Comandos de un bot de Telegram: setMyCommands, scopes y deep links con /start
Configura los comandos de tu bot de Telegram: /setcommands en @BotFather, setMyCommands con scopes e idiomas, parámetro de /start y /cmd@bot en grupos.
Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard
Agrega botones a tu bot de Telegram: teclado inline con callback_data, answerCallbackQuery, editar el mensaje tras cada clic, reply keyboard y ForceReply.
Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso
Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.
Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)
Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.
Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)
Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.
Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas
Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.
Bot inline de Telegram: cómo activar el modo inline y responder consultas
Crea un bot inline de Telegram: activa el modo inline con @BotFather o setMySettings, procesa inline_query y responde con answerInlineQuery.
Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones
Acepta pagos con Telegram Stars en tu bot: sendInvoice con XTR, pre_checkout_query, successful_payment, reembolsos y suscripciones, con código.
Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas
Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.
Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir
Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.
API JavaScript de TelegramWidget: referencia, eventos, errores y límites
Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.
Ejemplos de widgets de Telegram: HTML completo y bot en Python
Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.
Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot
Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.
Cómo probar una Mini App de Telegram: del navegador a Telegram real
Cómo probar una Mini App de Telegram: modo mock en el navegador, localhost con túnel HTTPS, entorno de prueba, DevTools y validación de initData.