Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens
Para conectar o n8n ao Telegram você precisa de uma única coisa do Telegram: o token do bot. Salve-o como Access Token de uma credencial Telegram no n8n e use o nó Telegram Trigger para iniciar workflows a cada mensagem recebida e o nó Telegram para enviar mensagens a um chat id. O trigger funciona via webhook da Bot API, então a sua instância do n8n precisa estar acessível numa URL HTTPS pública. Este guia mostra a configuração, o que o n8n self-hosted precisa e os erros mais comuns.
Como funciona a integração do n8n com o Telegram
| Nó | O que faz | Bot API por baixo | Precisa de HTTPS público? |
|---|---|---|---|
| Telegram Trigger | Inicia o workflow a cada update: mensagem, clique em botão, post de canal etc. | setWebhook; depois o Telegram faz POST dos updates para o n8n | Sim |
| Telegram | Envia e edita mensagens, envia arquivos, responde callback queries, lê dados do chat | sendMessage, sendPhoto, editMessageText, answerCallbackQuery… | Não, só requisições de saída |
Como o trigger usa webhook, as regras de webhook da Bot API também valem para o n8n: só HTTPS, portas 443, 80, 88 ou 8443, uma URL de webhook por bot e nada de getUpdates enquanto o webhook estiver ativo.
Passo 1: criar o bot e pegar o token
- Abra o @BotFather, mande
/newbote escolha um nome de exibição e um username terminado embot. - Copie o token que o BotFather devolve. Ele tem o formato
123456789:AAEexampleTokenReplaceWithYours. Para um bot que já existe, abra/mybots→ seu bot → API Token. - Confira o token antes de colar em qualquer lugar:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"
Um token válido devolve "ok": true com os dados do bot; um errado devolve 401 Unauthorized. Você pode fazer a mesma checagem no getMe do Bot API Tester. Como encontrar, verificar e revogar tokens está no guia do token do bot do Telegram; se ainda não tem um bot, comece por como criar um bot no Telegram.
Passo 2: adicionar a credencial do Telegram no n8n
O n8n se autentica no Telegram só com o token do bot. Crie uma nova credencial Telegram e cole o token no campo Access Token. O nó Telegram e o nó Telegram Trigger usam o mesmo tipo de credencial, então basta uma credencial por bot.
Trate o token como uma senha: quem tem o token controla o bot. Se vazar, revogue no @BotFather e atualize a credencial no n8n.
Passo 3: receber updates com o webhook do Telegram Trigger no n8n
Adicione um nó Telegram Trigger, selecione a credencial e escolha quais updates iniciam o workflow. As opções mais comuns são Message para mensagens recebidas e Callback Query para cliques em botões inline; * significa todos os updates, exceto os de membros do chat e de reações, o que corresponde ao padrão da Bot API. O nó também pode ser limitado a chat ids ou user ids específicos e pode baixar imagens e arquivos anexados.
Quando você testa ou publica o workflow, o n8n chama setWebhook para o bot com uma URL da própria instância. A partir daí, o Telegram envia cada update por HTTPS POST para o n8n. Disso decorrem duas coisas:
- As URLs de teste e de produção se sobrescrevem. O n8n usa URLs de webhook diferentes para testar no editor e para o workflow publicado. O Telegram guarda só uma URL por bot, então quem registrou por último recebe os updates. Despublique o workflow enquanto testa ou use um bot separado para testes.
- Um bot, um trigger. Dois workflows, ou duas instâncias do n8n, com Telegram Trigger no mesmo bot ficam trocando o webhook um do outro. Use um trigger por bot e ramifique dentro do workflow, por exemplo com um nó Switch sobre o texto da mensagem.
Deixar o n8n self-hosted acessível por HTTPS
O n8n Cloud já tem um endereço HTTPS público. Uma instância self-hosted monta as URLs de webhook a partir do próprio protocolo, host e porta, o que atrás de um proxy reverso ou em localhost costuma virar um endereço http:// que o Telegram recusa. A solução:
- Coloque o n8n atrás de um proxy reverso (nginx, Caddy, Traefik etc.) que termine o TLS com um certificado válido na porta 443.
- Informe ao n8n o endereço público. As versões atuais usam
N8N_WEBHOOK_URL; o antigoWEBHOOK_URLestá obsoleto desde o n8n 2.35.0, mas ainda é lido, e versões anteriores à 2.30.0 só conhecemWEBHOOK_URL. - Defina
N8N_PROXY_HOPS=1e repasse do proxy os headersX-Forwarded-For,X-Forwarded-HosteX-Forwarded-Proto. - Ative o proxy de WebSocket; sem ele o editor pode parecer travado enquanto espera um evento de teste do trigger.
- Reinicie o n8n e reative o workflow para o trigger registrar a nova URL HTTPS.
# n8n atrás de um proxy reverso que serve https://n8n.example.com
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# versões do n8n anteriores à 2.30.0: use WEBHOOK_URL
# export WEBHOOK_URL=https://n8n.example.com/
Para desenvolvimento local, um túnel que forneça um hostname HTTPS público funciona do mesmo jeito: coloque esse hostname em N8N_WEBHOOK_URL. Lembre que o webhook quebra sempre que o endereço do túnel muda.
Conferir qual webhook o Telegram tem para o seu bot
Quando o trigger fica mudo, pergunte direto ao Telegram com getWebhookInfo. Ele mostra a URL registrada, quantos updates estão na fila e o último erro de entrega. Este script imprime um diagnóstico rápido:
import os
import requests
TOKEN = os.environ["BOT_TOKEN"] # o mesmo token da credencial do 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 errado
info = data["result"]
print("URL do webhook:", info["url"] or "(nenhuma: nenhum Telegram Trigger ativo)")
print("Updates pendentes:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
print("Problema: o Telegram exige uma URL HTTPS")
if "last_error_message" in info:
print("Último erro de entrega:", info["last_error_message"])const TOKEN = process.env.BOT_TOKEN; // o mesmo token da credencial do 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 errado
process.exit(1);
}
const info = data.result;
console.log("URL do webhook:", info.url || "(nenhuma: nenhum Telegram Trigger ativo)");
console.log("Updates pendentes:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
console.log("Problema: o Telegram exige uma URL HTTPS");
}
if (info.last_error_message) {
console.log("Último erro de entrega:", info.last_error_message);
}Salve a versão JavaScript como check.mjs e rode com Node.js 18 ou mais recente. Como ler o resultado: uma URL de outro serviço significa que algo assumiu o webhook do bot; um pending_update_count crescente junto com um last_error_message significa que o Telegram não alcança o n8n ou que o n8n responde com erro. Sem código, use o getWebhookInfo no Bot API Tester.
Passo 4: enviar mensagens do Telegram pelo n8n
Adicione um nó Telegram, escolha o recurso Message e a operação Send Message, selecione a credencial e preencha dois campos:
- Chat ID: um id numérico como
123456789, ou@channelusernamepara um canal público. Num workflow que começa com o Telegram Trigger, mapeie com a expressão$json.message.chat.idpara o bot responder no mesmo chat. - Text: até 4096 caracteres após o parsing das entidades, o limite do
sendMessage.
Dois padrões pegam muita gente de surpresa. O nó acrescenta a linha This message was sent automatically with n8n; desligue Append n8n Attribution nos campos adicionais para removê-la. E o parse mode do nó vem como HTML por padrão, então escape <, > e & no texto dinâmico como <, > e &, senão o Telegram recusa a mensagem com o erro can't parse entities.
Antes de amarrar um chat id ao workflow, confirme que ele funciona com uma requisição no sendMessage do Bot API Tester. Para postar num canal, adicione antes o bot como administrador. O Telegram permite cerca de 30 mensagens por segundo em envios em massa e cerca de uma por segundo num mesmo chat, então limite o ritmo dos loops de disparo; veja os limites da Telegram Bot API.
Como encontrar o chat id
A fonte mais fácil é o próprio trigger: execute o workflow, mande uma mensagem ao bot e leia message.chat.id na saída do trigger. Usuários têm ids positivos, grupos negativos, e supergrupos e canais têm o formato -1001234567890. Se preferir o getUpdates, chame-o antes de ativar qualquer Telegram Trigger desse bot; com o webhook ativo ele falha com 409 Conflict. Todos os métodos, incluindo grupos, canais e tópicos de fórum, estão em como pegar o chat id do Telegram.
Erros comuns do n8n com o Telegram
| Sintoma | Causa | Solução |
|---|---|---|
Bad Request: bad webhook: An HTTPS URL must be provided for webhook | O n8n registrou uma URL http://: localhost ou proxy sem TLS | Termine o TLS no proxy e defina N8N_WEBHOOK_URL (ou WEBHOOK_URL) com o endereço HTTPS |
| Erro de bad webhook sobre a porta | A URL pública usa uma porta diferente de 443, 80, 88 ou 8443 | Exponha o n8n na 443 pelo proxy |
409 Conflict no getUpdates | Um Telegram Trigger mantém um webhook registrado | Desative o workflow e chame deleteWebhook, ou pegue os chat ids no trigger |
| Workflow só funciona no teste ou só publicado | As URLs de webhook de teste e de produção se substituem | Despublique enquanto testa ou use um bot de teste separado |
| Trigger parou depois que outro workflow foi ativado | Um segundo trigger, ou outro serviço, chamou setWebhook com o mesmo token | Um trigger por bot; confira a URL com getWebhookInfo |
| Editor travado em “waiting for trigger event” | Proxy reverso sem suporte a WebSocket | Ative o proxy de WebSocket e reabra o workflow |
| Nenhum update de mensagens do grupo | Modo de privacidade: no grupo o bot só recebe comandos para ele, respostas a ele e mensagens de serviço | Desligue a privacidade com /setprivacy ou torne o bot admin |
401 Unauthorized | Token errado ou revogado na credencial | Confira com getMe e cole o token atual |
400 Bad Request: chat not found ao enviar | Chat id errado ou chat que o bot não acessa: o usuário nunca iniciou o bot ou o bot não está no grupo | Confira o id; peça que o usuário mande /start ou adicione o bot ao grupo |
Para recomeçar do zero, desative o workflow, chame deleteWebhook, confira se o getWebhookInfo mostra url vazia e ative o workflow de novo para o n8n registrar a URL do zero. Para o funcionamento do webhook em geral (secret token, novas tentativas, certificados), veja o guia de webhook do bot do Telegram.
Perguntas frequentes
Como conectar o Telegram ao n8n?
Crie um bot no @BotFather, copie o token e salve-o como Access Token de uma credencial Telegram no n8n. Use o nó Telegram Trigger para receber mensagens e o nó Telegram para enviá-las; os dois usam a mesma credencial.
Por que o Telegram Trigger do n8n mostra “An HTTPS URL must be provided for webhook”?
O trigger registra um webhook com setWebhook, e o Telegram só aceita URLs HTTPS públicas. Se o n8n roda em http://localhost ou atrás de um proxy sem TLS, defina o endereço HTTPS público da instância em N8N_WEBHOOK_URL (WEBHOOK_URL em versões antigas) e termine o TLS no proxy reverso.
Dois workflows do n8n podem usar o trigger do mesmo bot do Telegram?
Não de forma confiável. Um bot tem exatamente uma URL de webhook, então cada ativação sobrescreve a anterior e só o último workflow recebe os updates. Use um trigger por bot, faça o roteamento dentro de um único workflow ou crie outro bot.
Por que o getUpdates devolve 409 Conflict depois que configurei o n8n?
Um Telegram Trigger ativo mantém um webhook registrado para o bot, e o getUpdates não funciona com webhook ativo. Desative o workflow e chame deleteWebhook se precisar de polling, ou pegue os chat ids na saída do trigger.
Preciso de URL HTTPS pública só para enviar mensagens pelo n8n?
Não. O nó Telegram só faz requisições de saída para api.telegram.org, então o envio funciona numa instância local do n8n. HTTPS público só é necessário para receber updates com o Telegram Trigger.
Onde encontro o chat id para o nó Telegram do n8n?
Pegue na saída do trigger (message.chat.id) ou mande uma mensagem ao bot e chame getUpdates antes de ativar o trigger. Canais públicos também aceitam @channelusername.
Guias relacionados
Como criar um bot no Telegram grátis: do BotFather à primeira mensagem
Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.
Como hospedar um bot do Telegram: deploy em VPS, Docker e serverless
Como hospedar e fazer deploy de um bot do Telegram: polling ou webhook, serviço systemd na VPS, Docker, Cloudflare Workers com secret_token e checklist.
Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais
Novidades do Telegram Bot API 10.0–10.5: setMySettings e BotFullInfo, widgets HTML, rich messages, mensagens efêmeras e guest mode, com exemplos JSON.
Erros do Telegram Bot API: o que cada erro significa e como resolver
Erros do Telegram Bot API explicados: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Causas, soluções e código pronto.
Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens
Rate limit do Telegram Bot API na prática: 30 msg/s, 1 msg/s por chat, 20/min em grupos, como tratar 429 e retry_after, limites de arquivo e de texto.
Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start
Configure os comandos do bot do Telegram: /setcommands no @BotFather, setMyCommands com escopos e idiomas, parâmetro do /start e /cmd@bot em grupos.
Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard
Botões no bot do Telegram: inline keyboard com callback_data, answerCallbackQuery, editar a mensagem após o clique, reply keyboard e ForceReply.
Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)
Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.
Telegram bot token: como pegar o token do bot, verificar e revogar
Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.
Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n
Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.
Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot
Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.
Bot inline no Telegram: como ativar o modo inline e responder às consultas
Crie um bot inline no Telegram: ative o modo inline no @BotFather ou com setMySettings, trate updates inline_query e responda com answerInlineQuery.
Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas
Receba pagamentos em Telegram Stars no seu bot: sendInvoice com XTR, pre_checkout_query, successful_payment, reembolsos e assinaturas, com código.
Servidor de teste do Telegram: como testar um bot no ambiente de teste
Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.
Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar
Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.
API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites
Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.
Exemplos de widget do Telegram: HTML completo e bot em Python
Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.
Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot
Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.
Como testar uma Mini App do Telegram: do mock no navegador ao app real
Teste sua Mini App do Telegram passo a passo: modo mock no navegador, localhost via túnel HTTPS, ambiente de testes, DevTools e validação do initData.