Telegram Bot API

Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens

· 8 min de leitura

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 fazBot API por baixoPrecisa de HTTPS público?
Telegram TriggerInicia o workflow a cada update: mensagem, clique em botão, post de canal etc.setWebhook; depois o Telegram faz POST dos updates para o n8nSim
TelegramEnvia e edita mensagens, envia arquivos, responde callback queries, lê dados do chatsendMessage, 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

  1. Abra o @BotFather, mande /newbot e escolha um nome de exibição e um username terminado em bot.
  2. 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.
  3. 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:

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:

  1. 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.
  2. Informe ao n8n o endereço público. As versões atuais usam N8N_WEBHOOK_URL; o antigo WEBHOOK_URL está obsoleto desde o n8n 2.35.0, mas ainda é lido, e versões anteriores à 2.30.0 só conhecem WEBHOOK_URL.
  3. Defina N8N_PROXY_HOPS=1 e repasse do proxy os headers X-Forwarded-For, X-Forwarded-Host e X-Forwarded-Proto.
  4. Ative o proxy de WebSocket; sem ele o editor pode parecer travado enquanto espera um evento de teste do trigger.
  5. 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:

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 &lt;, &gt; e &amp;, 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

SintomaCausaSolução
Bad Request: bad webhook: An HTTPS URL must be provided for webhookO n8n registrou uma URL http://: localhost ou proxy sem TLSTermine o TLS no proxy e defina N8N_WEBHOOK_URL (ou WEBHOOK_URL) com o endereço HTTPS
Erro de bad webhook sobre a portaA URL pública usa uma porta diferente de 443, 80, 88 ou 8443Exponha o n8n na 443 pelo proxy
409 Conflict no getUpdatesUm Telegram Trigger mantém um webhook registradoDesative o workflow e chame deleteWebhook, ou pegue os chat ids no trigger
Workflow só funciona no teste ou só publicadoAs URLs de webhook de teste e de produção se substituemDespublique enquanto testa ou use um bot de teste separado
Trigger parou depois que outro workflow foi ativadoUm segundo trigger, ou outro serviço, chamou setWebhook com o mesmo tokenUm trigger por bot; confira a URL com getWebhookInfo
Editor travado em “waiting for trigger event”Proxy reverso sem suporte a WebSocketAtive o proxy de WebSocket e reabra o workflow
Nenhum update de mensagens do grupoModo de privacidade: no grupo o bot só recebe comandos para ele, respostas a ele e mensagens de serviçoDesligue a privacidade com /setprivacy ou torne o bot admin
401 UnauthorizedToken errado ou revogado na credencialConfira com getMe e cole o token atual
400 Bad Request: chat not found ao enviarChat id errado ou chat que o bot não acessa: o usuário nunca iniciou o bot ou o bot não está no grupoConfira 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.

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.