Telegram Bot API

Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes

· 8 min de lectura

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

NodoQué haceBot API por debajo¿Necesita HTTPS público?
Telegram TriggerInicia 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 POSTSí
TelegramEnvía y edita mensajes, envía archivos, responde callback queries, lee información del chatsendMessage, 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

  1. Abre @BotFather, envía /newbot y elige un nombre visible y un username que termine en bot.
  2. Copia el token que te devuelve BotFather. Se ve así: 123456789:AAEexampleTokenReplaceWithYours. Para un bot que ya existe, abre /mybots → tu bot → API Token.
  3. 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:

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:

  1. Pon n8n detrás de un proxy inverso (nginx, Caddy, Traefik, etc.) que termine TLS con un certificado válido en el puerto 443.
  2. Indícale a n8n su dirección pública. Las versiones actuales de n8n usan N8N_WEBHOOK_URL; la antigua WEBHOOK_URL está obsoleta desde n8n 2.35.0 pero se sigue leyendo, y las versiones anteriores a 2.30.0 solo conocen WEBHOOK_URL.
  3. Define N8N_PROXY_HOPS=1 y reenvía desde el proxy los encabezados X-Forwarded-For, X-Forwarded-Host y X-Forwarded-Proto.
  4. Activa el proxy de WebSocket; si no, el editor puede parecer congelado mientras espera un evento de prueba del trigger.
  5. 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:

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 &lt;, &gt; y &amp;, 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íntomaCausaSolución
Bad Request: bad webhook: An HTTPS URL must be provided for webhookn8n registró una URL http://: localhost o un proxy sin TLSTermina TLS en el proxy y define N8N_WEBHOOK_URL (o WEBHOOK_URL) con la dirección HTTPS
Error de bad webhook sobre el puertoLa URL pública usa un puerto distinto de 443, 80, 88 u 8443Expón n8n en el 443 a través del proxy
409 Conflict en getUpdatesUn Telegram Trigger mantiene un webhook registradoDesactiva el flujo y llama a deleteWebhook, o toma los chat id del trigger
El flujo funciona solo en pruebas o solo publicadoLas 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 flujoUn segundo trigger, u otro servicio, llamó a setWebhook con el mismo tokenUn trigger por bot; revisa la URL con getWebhookInfo
El editor se queda en “waiting for trigger event”Proxy inverso sin soporte de WebSocketActiva el proxy de WebSocket y vuelve a abrir el flujo
No llegan actualizaciones de mensajes de grupoModo privacidad: en grupos el bot solo recibe los comandos dirigidos a él, las respuestas a sus mensajes y los mensajes de servicioDesactiva la privacidad con /setprivacy o haz al bot administrador
401 UnauthorizedToken incorrecto o revocado en la credencialVerifícalo con getMe y pega el token vigente
400 Bad Request: chat not found al enviarChat id incorrecto o un chat al que el bot no tiene acceso: el usuario nunca lo inició o el bot no está en el grupoRevisa 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.

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.