Pular para o conteúdo principal
O Toolkit Telegram permite que agentes e fluxos de trabalho interajam com bots do Telegram. Ele suporta envio e edição de mensagens, envio de mídias, gerenciamento de membros do chat, geração de links de convite e registro de webhooks para acionar fluxos de trabalho a partir de mensagens recebidas. Os bots do Telegram e suas credenciais são gerenciados através de um bot do Telegram chamado @BotFather — não há console de desenvolvimento web.

​
Pré-requisitos

RequisitoDetalhe
Conta do TelegramNecessária para interagir com @BotFather

​
Etapa 1 — Criar um Bot do Telegram

1

Abra o @BotFather

Abra o Telegram e inicie uma conversa com @BotFather.
2

Crie um novo bot

Envie o comando /newbot e siga as instruções:
InstruçãoDetalhe
Nome do botUm nome de exibição legível por humanos (por exemplo, My App)
Nome de usuárioDeve ser único e terminar em bot (por exemplo, myapp_bot)
3

Copie o token do seu bot

O BotFather responderá com uma mensagem de sucesso contendo o token do seu bot — ele se parece com 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ. Copie e salve-o de forma segura.
Defina uma foto de perfil que combine com o logotipo do seu aplicativo usando o comando /setuserpic no BotFather. Uma imagem reconhecível faz seu bot parecer profissional e confiável para os usuários.

​
Etapa 2 — Adicione o Token ao EK

  1. No fluxo de trabalho, adicione um passo do toolkit Telegram.
  2. Clique em Select a Connection → Create a Connection.
  3. Insira um Connection Name e cole o token do seu bot.
  4. Clique em Save.

​
Gerenciando Seu Token

O token do seu bot é a chave-mestre do seu bot. Não o compartilhe, não o suba para repositórios públicos e não o exponha no código do lado do cliente.
Se o token for acidentalmente exposto, revogue-o imediatamente:
  1. Envie uma mensagem para @BotFather
  2. Envie /mybots
  3. Selecione seu bot
  4. Toque em API Token → Revoke current token
Um novo token será gerado. Atualize a conexão no EK com o novo valor.

​
Ferramentas Disponíveis

FerramentaDescrição
New Message (Trigger)Inicie um fluxo de trabalho quando uma mensagem for enviada ao seu bot
Send Text MessageEnvie uma mensagem de texto do seu bot para qualquer chat
Send MediaEnvie uma foto, vídeo, sticker ou GIF animado
Edit Message TextAtualize o texto de uma mensagem enviada anteriormente
Delete MessageExclua uma mensagem de um chat
Get Chat InfoRecupere metadados sobre um chat
Get Chat MemberConsulte o status de memória de um usuário em um chat
Create Invite LinkGere um link de convite para um grupo ou canal
Register WebhookDiga ao Telegram para encaminhar mensagens do bot para seu fluxo de trabalho
Deregister WebhookRemova o webhook e interrompa a entrega de mensagens

​
Trigger — New Message

Inicia um fluxo de trabalho automaticamente sempre que alguém envia uma mensagem ao seu bot do Telegram. Configuração:
1

Adicione o trigger

Adicione um trigger New Message como o primeiro passo do seu fluxo de trabalho. Copie a URL /tool-webhook/{workflow-id} do painel de configuração do trigger.
2

Registre o webhook

Use o passo Register Webhook para dizer ao Telegram para entregar mensagens nessa URL. Execute uma vez — veja Register Webhook abaixo.
3

Teste

Envie uma mensagem de teste ao seu bot. O fluxo de trabalho é acionado e todos os dados da mensagem ficam disponíveis como variáveis.
Variáveis de trigger disponíveis:
VariávelDescrição
{{ trigger.body.message.text }}O texto da mensagem que o usuário enviou
{{ trigger.body.message.chat.id }}O ID do chat — use isso como Chat ID em todos os passos de envio
{{ trigger.body.message.from.id }}O ID de usuário do Telegram do remetente
{{ trigger.body.message.from.first_name }}O primeiro nome do remetente
{{ trigger.body.message.from.username }}O nome de usuário do remetente (pode estar vazio)
{{ trigger.body.message.message_id }}O ID da mensagem recebida
{{ trigger.body.update_id }}O ID de atualização único do Telegram

​
Ações de Mensagens

​
Send Text Message

Envia uma mensagem de texto do seu bot para qualquer chat do Telegram. Entradas principais:
EntradaDescrição
Chat IDO chat para o qual enviar. Para a pessoa que acionou o fluxo de trabalho, use {{ trigger.body.message.chat.id }}. Para um grupo ou canal fixo, cole seu ID numérico.
MessageO texto a ser enviado. Misture texto estático com variáveis, por exemplo Olá {{ trigger.body.message.from.first_name }}, sua solicitação foi recebida.
FormatDeixe em branco para texto simples. Defina como HTML para <b>negrito</b> / <i>itálico</i>. Defina como MarkdownV2 para Markdown (caracteres especiais são escapados automaticamente).
Disable Web Page PreviewDefina como true para suprimir previews de links
Message Thread IDOpcional — relevante apenas para supergrupos de fórum
Reply MarkupOpcional — um objeto JSON para teclados inline ou teclados de resposta personalizados
Referenciando a saída em passos posteriores:
  • Message ID (necessário para Edit ou Delete posteriormente): {{ step.output.message_id }}
  • Chat ID: {{ step.output.chat_id }}

​
Send Media

Envia uma foto, vídeo, sticker ou GIF animado para um chat do Telegram. Entradas principais:
EntradaDescrição
Chat IDO chat para o qual enviar
Media TypeDeve ser exatamente um dos: photo, video, sticker, animation
Media URLUma URL HTTPS publicamente acessível para o arquivo — o Telegram busca diretamente
Media IDAlternativamente, um file_id do Telegram de um arquivo enviado anteriormente. Forneça Media URL ou Media ID, não ambos.
CaptionTexto opcional exibido abaixo da mídia. Suporta HTML/MarkdownV2 via Format.
FormatModo de parsing para a legenda
Message Thread IDOpcional — para tópicos de supergrupos de fórum
Se nem Media URL nem Media ID for fornecido, o passo retorna um erro. A URL deve ser acessível publicamente — URLs locais ou privadas não funcionarão.

​
Edit Message Text

Atualiza o texto de uma mensagem enviada anteriormente pelo seu bot. Entradas principais:
EntradaDescrição
Chat IDO chat onde a mensagem original está
Message IDO message_id da saída do Send Text Message — {{ step.output.message_id }}
TextO novo conteúdo da mensagem
FormatModo de parsing para o novo texto (em branco = texto simples, HTML ou MarkdownV2)
Exemplo de caso de uso: Envie “Processando sua solicitação…” primeiro. Execute a lógica do fluxo de trabalho. Em seguida, edite essa mensagem com o resultado final — o usuário vê uma mensagem em vez de duas.

​
Delete Message

Exclui uma mensagem de um chat. Entradas principais:
EntradaDescrição
Chat IDO chat contendo a mensagem
Message IDO message_id da mensagem a ser excluída
Os bots só podem excluir suas próprias mensagens, a menos que o bot seja um administrador no chat. O Telegram também impõe um limite de tempo — mensagens com mais de 48 horas geralmente não podem ser excluídas por bots.

​
Ações de Chat e Membros

​
Get Chat Info

Recupera metadados sobre um chat. Entradas principais:
EntradaDescrição
Chat IDO chat a ser consultado
Referenciando valores em passos posteriores:
  • Título do chat: {{ step.output.title }}
  • Descrição: {{ step.output.description }}
  • Link de convite: {{ step.output.invite_link }}

​
Get Chat Member

Consulta um usuário específico dentro de um chat e retorna seu status de memória e cargo. Entradas principais:
EntradaDescrição
Chat IDO chat a ser consultado
User IDO ID de usuário do Telegram a ser consultado. Para a pessoa que acionou o fluxo de trabalho, use {{ trigger.body.message.from.id }}.
Referenciando valores em passos posteriores:
  • Status: {{ step.output.status }}
  • Nome de usuário: {{ step.output.username }}
Possíveis valores de status: creator, administrator, member, restricted, left, kicked Exemplo de caso de uso: Verifique {{ step.output.status }} — se for igual a left ou kicked, pule o envio da mensagem e trate o erro. Gera um novo link de convite para um grupo ou canal.
O bot deve ser um administrador com a permissão “Invite Users” no chat de destino.
Entradas principais:
EntradaDescrição
Chat IDO grupo ou canal
NameRótulo opcional para o link (até 32 caracteres), visível no painel de administração do Telegram
Expire DateOpcional. Uma string ISO-8601 quando o link expira, por exemplo 2026-12-31T23:59:59Z. Convertido internamente para um timestamp unix.
Member LimitOpcional. Número máximo de pessoas que podem entrar via este link (1–99.999)
Referenciando o link em passos posteriores:
  • URL de convite: {{ step.output.invite_link }}
expire_date na saída é um timestamp unix (segundos inteiros), não formato ISO. creates_join_request será true se o chat exigir aprovação de administrador para novos membros.

​
Ações de Configuração de Webhook

Estes dois passos conectam um trigger New Message ao seu bot. Execute-os uma vez por fluxo de trabalho.

​
Register Webhook

Diz ao Telegram para começar a encaminhar mensagens do seu bot para a URL do seu fluxo de trabalho. Entradas principais:
EntradaDescrição
URLA URL /tool-webhook/{workflow-id} do painel do trigger New Message
Allowed UpdatesDefina como ["message"] para receber apenas mensagens regulares (recomendado). Deixe em branco para usar o mesmo padrão.
Secret TokenOpcional mas recomendado. Qualquer string aleatória (por exemplo, my-secret-abc123). O Telegram a inclui em cada cabeçalho de requisição webhook para que você possa verificar se as requisições são autênticas.
Drop Pending UpdatesDefina como true para ignorar mensagens que chegaram antes do webhook ser registrado
1

Copie a URL do trigger

Crie um fluxo de trabalho com um trigger New Message. Copie a URL /tool-webhook/{workflow-id} do painel do trigger.
2

Adicione Register Webhook

Em um fluxo de trabalho avulso ou execução de teste manual, adicione um passo Register Webhook e preencha as entradas acima.
3

Execute uma vez

Execute o passo. Em seguida, envie uma mensagem ao seu bot — seu fluxo de trabalho principal deve ser acionado agora.
Alternativamente, registre via curl para uma configuração rápida e avulsa: 
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/tool-webhook/<YOUR_WORKFLOW_ID>",
    "allowed_updates": ["message"],
    "secret_token": "my-secret-abc123"
  }'
Uma resposta bem-sucedida: 
{ "ok": true, "result": true, "description": "Webhook was set" }
Um bot do Telegram pode ter apenas um webhook ativo por vez. Registrar uma nova URL substitui qualquer anterior.

​
Deregister Webhook

Remove o webhook e interrompe o envio de mensagens do Telegram para seu fluxo de trabalho. Entradas principais:
EntradaDescrição
Drop Pending UpdatesDefina como true para descartar quaisquer mensagens enfileiradas enquanto o webhook estava ativo
Cancele o registro do webhook quando você desativar ou arquivar um fluxo de trabalho. Se você deixar o webhook registrado mas o fluxo de trabalho inativo, o Telegram continuará enviando requisições que ficarão sem resposta.

​
Solução de Problemas

SintomaCausa ProvávelCorreção
O fluxo de trabalho não é acionado em novas mensagensWebhook não registrado ou apontando para URL incorretaExecute Register Webhook com a URL de trigger correta
401 UnauthorizedToken do bot é inválido ou revogadoVerifique o token ou gere um novo via @BotFather
Mídia não entregueURL não é acessível publicamenteUse uma URL HTTPS pública — URLs locais ou privadas não funcionarão
Não é possível excluir uma mensagemMensagem tem mais de 48 horas ou bot não é administradorBots só podem excluir mensagens recentes, a menos que tenham privilégios de administrador
creates_join_request: true no link de conviteChat exige aprovação de administrador para novos membrosEste é o comportamento esperado — os usuários devem ser aprovados antes de entrar
Mensagens antigas acionando o fluxo de trabalhoAtualizações pendentes não foram limpas durante o registro do webhookRegistre novamente com Drop Pending Updates definido como true