# Gatilho do Telegram

> Inicie um workflow sempre que o seu bot do Telegram receber uma mensagem e passe o texto, a foto, o vídeo ou o áudio da mensagem para os nós seguintes.

Source: https://nodaro.ai/pt-BR/docs/nodes/automate/telegram-trigger

O nó **Gatilho do Telegram** (Telegram Trigger) inicia um workflow sempre que o seu bot do Telegram recebe uma mensagem. Ele passa o texto da mensagem, e qualquer foto, vídeo ou arquivo de áudio que ela tenha, para os nós depois dele. Um bot pode, por exemplo, transformar cada mensagem que recebe em uma imagem. O gatilho em si é gratuito.

- Found in: Automate › Triggers
- Output: data
- API type: `telegram-trigger`

## Quando usar
- Criar um bot que gera uma imagem ou um vídeo a partir de cada mensagem de texto.
- Responder mensagens com um nó [**Prompt**](https://nodaro.ai/docs/nodes/automate/prompt) e enviar a resposta de volta com o [**Publicar no Telegram** (Telegram Post)](https://nodaro.ai/docs/nodes/publish/telegram-post).
- Receber as fotos, os vídeos e os arquivos de áudio que as pessoas enviam ao bot.
- Reunir os posts de um grupo ou de um canal de que o seu bot é membro e processar cada um deles.

## Início rápido
### Conectar o seu bot
Primeiro, conecte o seu bot do Telegram em **Integrações**. Veja [Publicar nas redes sociais](https://nodaro.ai/docs/guides/publishing-to-social).

### Adicionar o nó e escolher o bot
Pressione Tab no canvas e escolha **Automatizar › Gatilhos › Gatilho do Telegram**. No painel de configurações, escolha o bot em **Bot do Telegram**.

### Filtrar as mensagens
Se quiser, insira um chat em **Filtro por ID do chat** e escolha os **Tipos de mensagem** que devem iniciar uma execução.

### Ativar e salvar
Clique em **Ativar gatilho** e depois salve o workflow. O salvamento registra o bot no Telegram, e o status mostra **Ativo — monitorando mensagens**.

### Enviar uma mensagem ao bot
Agora, cada mensagem que corresponde aos filtros inicia uma execução.

Workflow: Cada mensagem de texto enviada ao bot vira o prompt do Gerar imagem, e o Publicar no Telegram envia a imagem para um chat.

- Gatilho do Telegram → Gerar imagem (prompt)
- Gerar imagem → Publicar no Telegram

## Configurações
| Configuração | O que faz |
| --- | --- |
| **Bot do Telegram** | O bot conectado a ser monitorado. Obrigatório: sem um bot, nada é registrado. Quando ainda não há nenhum bot conectado, o painel mostra um link para **Integrações**. |
| **Filtro por ID do chat** | Só as mensagens deste chat iniciam uma execução, como `@channel` ou um ID numérico que começa com `-100`. Deixe vazio para receber mensagens de todos os chats. |
| **Tipos de mensagem** | Quais tipos de mensagem iniciam uma execução: **Texto**, **Foto**, **Vídeo**, **Áudio** e **Documento**. Os cinco vêm ativados por padrão. |
| **Ativar gatilho** | Ativa o gatilho, ou o desativa com **Desativar gatilho**. A mudança vale quando você salva o workflow. |

O status no topo do painel mostra o estado do gatilho:

| Status | Significado |
| --- | --- |
| **Ativo — monitorando mensagens** | O gatilho está ativado e há um bot escolhido. |
| **Escolha um bot — ainda não está monitorando** | O gatilho está ativado, mas nenhum bot foi escolhido. |
| **Inativo** | O gatilho está desativado. |

## O que o nó repassa
O nó tem uma saída, **Mensagem**. Quando uma execução começa, o Nodaro passa a mensagem para os nós conectados de acordo com o que ela contém:

| A mensagem contém | Ela vai para |
| --- | --- |
| Texto | O prompt do próximo nó, ou a legenda de um nó de publicação |
| Uma foto | Uma entrada de imagem, como as referências de um nó de imagem |
| Um vídeo | Uma entrada de vídeo |
| Áudio | Uma entrada de áudio |

A mensagem também leva o ID do chat e o ID da mensagem. O Nodaro baixa qualquer foto, vídeo ou arquivo de áudio para o armazenamento antes de a execução começar.

## Vários gatilhos em um bot
Um bot do Telegram envia as mensagens dele para exatamente um endereço, então todos os gatilhos do mesmo bot compartilham um único registro. Você pode apontar quantos workflows quiser para um bot. Cada mensagem recebida é comparada com o **Filtro por ID do chat** e os **Tipos de mensagem** de todos os gatilhos, e cada gatilho que corresponde inicia a própria execução.

Remover um gatilho nunca interrompe os outros. Desativar ou excluir um gatilho o remove no próximo salvamento. Quando não sobra nenhum gatilho ativo no bot, o Nodaro remove o registro do bot no Telegram.

## O que uma execução por gatilho executa
Um gatilho conectado a nós executa só o próprio ramo: os nós depois do gatilho e todos os nós de que eles precisam como entrada. Um gatilho que não está conectado a nada executa o workflow inteiro. Cada Gatilho do Telegram que você configura no editor executa o próprio ramo. Por isso, dois gatilhos no mesmo bot, com filtros de chat diferentes, iniciam duas execuções separadas para uma mensagem que corresponde aos dois. Uma execução manual no editor, uma execução pela API e uma execução de um app publicado nunca ficam limitadas ao ramo de um gatilho.

## Ver a execução no canvas
Quando o workflow está aberto no editor, uma execução iniciada por uma mensagem aparece no canvas do mesmo jeito que uma execução que você inicia.

- O nó Gatilho do Telegram mostra **Processando uma mensagem…** enquanto a execução continua.
- Os nós que a execução alcança mostram o progresso, e os resultados ficam neles quando a execução termina. A própria mensagem fica em **Execuções**.
- O editor procura novas execuções de mensagens a cada 10 segundos, mais ou menos.
- A barra de execução mostra a execução, e o menu de parada funciona como em qualquer execução. Veja [Interromper uma execução](https://nodaro.ai/docs/concepts/running-workflows#stop-a-run).

Quando você abre o workflow mais tarde, os nós mostram a execução de mensagem mais recente que terminou, a menos que você tenha executado algo no editor depois dela. Uma execução interrompida ou descartada não aparece, nem um resultado que você limpou depois da execução.

Só as execuções de mensagens aparecem no canvas. As execuções iniciadas por um agendamento, um webhook ou a API ficam só em **Execuções**.

## Créditos
O Gatilho do Telegram é gratuito. Cada execução paga pelos nós que executa.

## Solução de problemas
- **O salvamento avisa que o gatilho não pôde ser registrado.** O Telegram recusou o registro, e o aviso diz o motivo. Uma causa comum é um token de bot que foi revogado depois que você conectou o bot. Outra é uma instalação self-hosted cuja `PUBLIC_URL` não é um endereço HTTPS que o Telegram consiga alcançar. Nenhum gatilho é criado quando o registro falha.
- **Nada acontece com mensagens em um grupo.** Um bot só recebe as mensagens de grupo endereçadas a ele, a menos que o modo de privacidade em grupos esteja desativado para o bot no BotFather.
- **A mídia não aparece na execução.** O Telegram permite que bots baixem arquivos de até 20 MB. Um arquivo maior chega como uma mensagem sem mídia.

## Frequently asked questions

### Como inicio um workflow a partir de uma mensagem do Telegram?

Conecte o seu bot do Telegram em “Integrações”, adicione um “Gatilho do Telegram”, escolha o bot, clique em “Ativar gatilho” e salve o workflow. Cada mensagem que o bot recebe passa a iniciar uma execução.

### Vários workflows podem ouvir o mesmo bot?

Sim. Cada mensagem recebida é comparada com os filtros de todos os gatilhos daquele bot, e cada gatilho que corresponde inicia a própria execução. Remover um gatilho nunca interrompe os outros.

### Por que o meu bot não reage a mensagens em um grupo?

Um bot do Telegram só recebe as mensagens de grupo endereçadas a ele, a menos que o modo de privacidade em grupos dele esteja desativado. Desative o modo de privacidade do bot no BotFather.

### Posso limitar o gatilho a um chat?

Sim. Insira o chat em “Filtro por ID do chat”, como @channel ou como um ID numérico, por exemplo -100 seguido de dígitos. Deixe o campo vazio para receber mensagens de todos os chats.

### O “Gatilho do Telegram” custa créditos?

Não. O gatilho em si é gratuito. Cada execução paga pelos nós que executa.