> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Toolkit Telegram
> Conecte seu bot do Telegram a agentes e fluxos de trabalho para enviar mensagens, gerenciar chats e acionar automações a partir de mensagens recebidas.
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 Telegram e inicie uma conversa com [@BotFather](https://t.me/BotFather).
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`) |
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**.
1. Abra seu agente no **Agent Builder**.
2. Vá até a aba **Toolkits** na barra lateral esquerda.
3. Encontre **Telegram** e clique em **Add to Agent**.
4. Cole o token do seu bot em **Telegram Bot Token**.
5. 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
| 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 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.
Use o passo **Register Webhook** para dizer ao Telegram para entregar mensagens nessa URL. Execute uma vez — veja [Register Webhook](#register-webhook) abaixo.
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 `negrito` / `itálico`. 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 |
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 |
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.
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 }}`
`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 |
Crie um fluxo de trabalho com um trigger New Message. Copie a URL `/tool-webhook/{workflow-id}` do painel do trigger.
Em um fluxo de trabalho avulso ou execução de teste manual, adicione um passo **Register Webhook** e preencha as entradas acima.
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:
```bash theme={null}
curl -X POST "https://api.telegram.org/bot/setWebhook" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/tool-webhook/",
"allowed_updates": ["message"],
"secret_token": "my-secret-abc123"
}'
```
Uma resposta bem-sucedida:
```json theme={null}
{ "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:**
| Entrada | Descrição |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| Drop Pending Updates | Defina 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
| 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` |