Toolkit Telegram

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

Requisito	Detalhe
Conta do Telegram	Necessária para interagir com @BotFather

Etapa 1 — Criar um Bot do Telegram

Abra o @BotFather
Abra o Telegram e inicie uma conversa com @BotFather.
Crie um novo bot
Envie o comando /newbot e siga as instruções:
Instrução Detalhe
Nome do bot Um nome de exibição legível por humanos (por exemplo, My App)
Nome de usuário Deve ser único e terminar em bot (por exemplo, myapp_bot)
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.

Instrução	Detalhe
Nome do bot	Um nome de exibição legível por humanos (por exemplo, `My App`)
Nome de usuário	Deve ser único e terminar em `bot` (por exemplo, `myapp_bot`)

Dica

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

Workflow Builder
Agent Builder

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

Gerenciando Seu Token

Perigo

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:

Envie uma mensagem para @BotFather
Envie /mybots
Selecione seu bot
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

Ferramenta	Descrição
New Message (Trigger)	Inicie um fluxo de trabalho quando uma mensagem for enviada ao seu bot
Send Text Message	Envie uma mensagem de texto do seu bot para qualquer chat
Send Media	Envie uma foto, vídeo, sticker ou GIF animado
Edit Message Text	Atualize o texto de uma mensagem enviada anteriormente
Delete Message	Exclua uma mensagem de um chat
Get Chat Info	Recupere metadados sobre um chat
Get Chat Member	Consulte o status de memória de um usuário em um chat
Create Invite Link	Gere um link de convite para um grupo ou canal
Register Webhook	Diga ao Telegram para encaminhar mensagens do bot para seu fluxo de trabalho
Deregister Webhook	Remova 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:

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.
Registre o webhook
Use o passo Register Webhook para dizer ao Telegram para entregar mensagens nessa URL. Execute uma vez — veja Register Webhook abaixo.
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ável	Descriçã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:

Entrada	Descrição
Chat ID	O 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.
Message	O 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.`
Format	Deixe 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 Preview	Defina como `true` para suprimir previews de links
Message Thread ID	Opcional — relevante apenas para supergrupos de fórum
Reply Markup	Opcional — 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:

Entrada	Descrição
Chat ID	O chat para o qual enviar
Media Type	Deve ser exatamente um dos: `photo`, `video`, `sticker`, `animation`
Media URL	Uma URL HTTPS publicamente acessível para o arquivo — o Telegram busca diretamente
Media ID	Alternativamente, um `file_id` do Telegram de um arquivo enviado anteriormente. Forneça Media URL ou Media ID, não ambos.
Caption	Texto opcional exibido abaixo da mídia. Suporta HTML/MarkdownV2 via Format.
Format	Modo de parsing para a legenda
Message Thread ID	Opcional — para tópicos de supergrupos de fórum

Nota

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:

Entrada	Descrição
Chat ID	O chat onde a mensagem original está
Message ID	O `message_id` da saída do Send Text Message — `{{ step.output.message_id }}`
Text	O novo conteúdo da mensagem
Format	Modo 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:

Entrada	Descrição
Chat ID	O chat contendo a mensagem
Message ID	O `message_id` da mensagem a ser excluída

Nota

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:

Entrada	Descrição
Chat ID	O 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:

Entrada	Descrição
Chat ID	O chat a ser consultado
User ID	O 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.

Create Invite Link

Gera um novo link de convite para um grupo ou canal.

Nota

O bot deve ser um administrador com a permissão "Invite Users" no chat de destino.

Entradas principais:

Entrada	Descrição
Chat ID	O grupo ou canal
Name	Rótulo opcional para o link (até 32 caracteres), visível no painel de administração do Telegram
Expire Date	Opcional. Uma string ISO-8601 quando o link expira, por exemplo `2026-12-31T23:59:59Z`. Convertido internamente para um timestamp unix.
Member Limit	Opcional. 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 }}

Nota

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:

Entrada	Descrição
URL	A URL `/tool-webhook/{workflow-id}` do painel do trigger New Message
Allowed Updates	Defina como `["message"]` para receber apenas mensagens regulares (recomendado). Deixe em branco para usar o mesmo padrão.
Secret Token	Opcional 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 Updates	Defina como `true` para ignorar mensagens que chegaram antes do webhook ser registrado

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.
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.
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" }

Nota

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:

Entrada	Descrição
Drop Pending Updates	Defina como `true` para descartar quaisquer mensagens enfileiradas enquanto o webhook estava ativo

Nota

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

Sintoma	Causa Provável	Correção
O fluxo de trabalho não é acionado em novas mensagens	Webhook não registrado ou apontando para URL incorreta	Execute Register Webhook com a URL de trigger correta
`401 Unauthorized`	Token do bot é inválido ou revogado	Verifique o token ou gere um novo via @BotFather
Mídia não entregue	URL não é acessível publicamente	Use uma URL HTTPS pública — URLs locais ou privadas não funcionarão
Não é possível excluir uma mensagem	Mensagem tem mais de 48 horas ou bot não é administrador	Bots só podem excluir mensagens recentes, a menos que tenham privilégios de administrador
`creates_join_request: true` no link de convite	Chat exige aprovação de administrador para novos membros	Este é o comportamento esperado — os usuários devem ser aprovados antes de entrar
Mensagens antigas acionando o fluxo de trabalho	Atualizações pendentes não foram limpas durante o registro do webhook	Registre novamente com `Drop Pending Updates` definido como `true`

Pré-requisitos​

Etapa 1 — Criar um Bot do Telegram​

Etapa 2 — Adicione o Token ao EK​

Gerenciando Seu Token​

Ferramentas Disponíveis​

Trigger — New Message​

Ações de Mensagens​

Send Text Message​

Send Media​

Edit Message Text​

Delete Message​

Ações de Chat e Membros​

Get Chat Info​

Get Chat Member​

Create Invite Link​

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

Register Webhook​

Deregister Webhook​

Solução de Problemas​

Pré-requisitos

Etapa 1 — Criar um Bot do Telegram

Etapa 2 — Adicione o Token ao EK

Gerenciando Seu Token

Ferramentas Disponíveis

Trigger — New Message

Ações de Mensagens

Send Text Message

Send Media

Edit Message Text

Delete Message

Ações de Chat e Membros

Get Chat Info

Get Chat Member

Create Invite Link

Ações de Configuração de Webhook

Register Webhook

Deregister Webhook

Solução de Problemas