ThorAgentIA/TELEGRAM_SETUP.md

# Como criar um Bot no Telegram e configurar um Canal

Este guia explica passo a passo como criar um bot no Telegram, configurar um canal, adicionar administradores e configurar tudo para que o canal receba as mensagens do bot.

---

## 1. Criar o Bot no Telegram

### 1.1. Acessar o BotFather

1. Abra o Telegram e pesquise por **@BotFather** ou acesse [https://t.me/BotFather](https://t.me/BotFather).
2. Clique em **Iniciar** ou envie o comando `/start`.

### 1.2. Criar o novo bot

1. Envie o comando `/newbot`.
2. Escolha um nome para o seu bot (ex: `ThorAgentIA Bot`). Este é o nome de exibição.
3. Escolha um username para o bot (ex: `thoragentia_bot`). O username deve terminar com `bot` e ser único no Telegram.

### 1.3. Obter o Token

Após criar o bot, o BotFather irá enviar uma mensagem semelhante a:

```
Usuário: @thoragentia_bot
Token: 1234567890:ABCdefGhIJKlmNoPQRsTUVwxyz1234567890
```

**Guarde este token com segurança.** Ele será usado na variável `TELEGRAM_BOT_TOKEN` do arquivo `.env`.

> ⚠️ Nunca compartilhe o token publicamente. Qualquer pessoa com acesso ao token pode controlar o bot.

---

## 2. Criar um Canal no Telegram

### 2.1. Criar o canal

1. No Telegram, clique no ícone de **menu** (três linhas) e selecione **Novo canal**.
2. Defina um nome para o canal (ex: `Insights ThorAgentIA`).
3. (Opcional) Adicione uma descrição e foto.
4. Clique em **Criar**.

### 2.2. Tornar o canal público ou privado

- **Canal público**: Qualquer pessoa pode encontrar o canal pelo username.
- **Canal privado**: Apenas usuários convidados podem acessar.

Recomenda-se usar canal **público** se desejar que o bot envie mensagens usando apenas o username. Para canais privados, será necessário usar o ID numérico.

### 2.3. Configurar permissões do canal

1. Clique no nome do canal no topo.
2. Clique em **Gerenciar canal** (ou **Editar canal**).
3. Ajuste as permissões conforme necessidade.

Para canais, o foco principal é garantir que o bot possa publicar mensagens.

---

## 3. Adicionar o Bot ao Canal

### 3.1. Adicionar como administrador (recomendado)

1. Abra o canal e clique no nome do canal no topo.
2. Clique em **Administradores**.
3. Clique em **Adicionar administrador**.
4. Pesquise pelo username do bot (ex: `@thoragentia_bot`).
5. Selecione o bot e confirme.

> **Nota**: Para canais públicos, o bot também pode ser adicionado sem ser administrador, mas para enviar mensagens proativamente é necessário ser administrador com permissão de postar mensagens.

### 3.2. Conceder permissões ao bot

Para que o bot possa enviar mensagens no canal, ele precisa ter a permissão **Postar mensagens** ou **Enviar mensagens**.

#### Como localizar essa permissão no Telegram

**Telegram Desktop / Web**
1. Abra o canal.
2. Clique no **nome do canal** no topo para abrir as informações.
3. Clique em **Administradores**.
4. Na lista, clique no nome do seu bot.
5. Role até a seção **Permissões de administrador**.
6. Ative a opção **Postar mensagens** (ou **Enviar mensagens**).
7. Clique em **Salvar** no final da tela.

**Telegram Android / iOS**
1. Abra o canal.
2. Toque no **nome do canal** no topo para abrir as informações.
3. Toque em **Administradores**.
4. Na lista, toque no seu bot.
5. Ative a opção **Postar mensagens** (ou **Enviar mensagens**).
6. Toque no ícone de **confirmar/check** no canto superior direito para salvar.

#### Importante sobre a permissão "Postar mensagens"

Essa permissão controla se o administrador pode publicar mensagens no canal. Se estiver desativada, o bot será adicionado como administrador, mas não conseguirá enviar mensagens por conta própria.

> **Nota**: Se o bot não for administrador, ele só poderá responder a comandos ou mensagens enviadas diretamente para ele. Para enviar mensagens proativamente, ele precisa ser administrador com essa permissão ativada.

---

## 4. Obter o Identificador do Canal

Para configurar o bot para enviar mensagens para o canal, você precisa do **identificador do canal**, que pode ser o username no formato `@nome_do_canal` ou o ID numérico `-100xxxxxxxxxx`.

### 4.1. Método 1: Usar o username do canal

Se o canal for público e tiver um username definido, basta usar o formato `@nome_do_canal` em `TELEGRAM_CHAT_ID`.

### 4.2. Método 2: Usar a API do Telegram

1. Adicione o bot ao canal (veja seção 3).
2. Envie uma mensagem do canal ou adicione o bot como administrador.
3. Acesse a seguinte URL no navegador (substitua `SEU_TOKEN` pelo token do bot):

```
https://api.telegram.org/botSEU_TOKEN/getUpdates
```

4. Procure por `"chat":{"id":-100XXXXXXXXXX` na resposta JSON. O número negativo é o ID do canal.

> **Dica**: Você também pode executar o comando abaixo no terminal para consultar os updates do bot:

```bash
python3 -c "
import requests, os
from dotenv import load_dotenv
load_dotenv()
token = os.getenv('TELEGRAM_BOT_TOKEN')
r = requests.get(f'https://api.telegram.org/bot{token}/getUpdates', timeout=15)
print(r.text)
"
```

### 4.3. Método 3: Usar um bot auxiliar

1. Adicione o bot **@myidbot** ao canal.
2. Envie o comando `/myid`.
3. O bot irá responder com o identificador do canal.

---

## 5. Obter o Identificador do Canal

Para configurar o bot para enviar mensagens para o canal, você precisa do **identificador do canal**, que pode ser o username no formato `@nome_do_canal` ou o ID numérico `-100xxxxxxxxxx`.

### 5.1. Método 1: Usando o BotFather

1. Acesse o BotFather.
2. Clique no bot criado (ex: `@thoragentia_bot`).
3. O BotFather irá exibir as informações do bot, incluindo o identificador do canal se houver.

### 5.2. Método 2: Usando a API do Telegram

1. Adicione o bot ao canal (veja seção 3).
2. Envie uma mensagem qualquer no canal ou adicione o bot como administrador.
3. Acesse a seguinte URL no navegador (substitua `SEU_TOKEN` pelo token do bot):

```
https://api.telegram.org/botSEU_TOKEN/getUpdates
```

4. Procure por `"chat":{"id":-100XXXXXXXXXX` na resposta JSON. O número negativo é o ID do canal.

### 5.3. Método 3: Usando um bot auxiliar

1. Adicione o bot **@myidbot** ao canal.
2. Envie o comando `/myid`.
3. O bot irá responder com o identificador do canal.

---

## 6. Configurar o ThorAgentIA para o Canal

### 6.1. Configurar o arquivo `.env`

Edite o arquivo `.env` do projeto ThorAgentIA com o token e identificador do canal obtidos:

```env
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGhIJKlmNoPQRsTUVwxyz1234567890
TELEGRAM_CHAT_ID=@nome_do_canal
```

> **Importante**: Para canais públicos, use o formato `@nome_do_canal`. Para canais privados, use o ID numérico `-100xxxxxxxxxx`.

### 6.2. Testar a conexão

Execute o script principal para verificar se o bot envia mensagens corretamente para o canal:

```bash
source venv/bin/activate
python3 main.py
```

Se configurado corretamente, o bot começará a enviar insights automaticamente para o canal nos horários definidos.

---

## 7. Gerenciar Membros e Permissões

### 7.1. Adicionar novos membros

- Use o link de convite do canal (se o canal for privado).
- Ou adicione diretamente pelo menu do canal.

### 7.2. Remover membros

1. Abra o canal e clique no nome do canal.
2. Vá em **Membros**.
3. Clique no membro que deseja remover.
4. Selecione **Remover membro**.

### 7.3. Promover membros a administradores

1. Abra o canal e clique no nome do canal.
2. Vá em **Administradores**.
3. Clique em **Adicionar administrador**.
4. Pesquise e selecione o membro.
5. Defina as permissões desejadas.

---

## 8. Solução de Problemas

### O bot não envia mensagens para o canal

1. Verifique se o bot é administrador do canal.
2. Verifique se a permissão **Postar mensagens** está ativada para o bot.
3. Confirme se o `TELEGRAM_BOT_TOKEN` e `TELEGRAM_CHAT_ID` estão corretos no `.env`.
4. Verifique os logs do script para identificar erros.

### Usuários não recebem as mensagens

1. Certifique-se de que os usuários são membros do canal.
2. Para canais privados, verifique se os usuários foram convidados corretamente.
3. Para canais grandes, verifique se o bot não foi silenciado pelos usuários.

### O bot não responde a comandos no canal

1. Verifique se o bot está ativo no canal.
2. Confira se o token do bot está correto.
3. Verifique se há restrições de permissão no canal.

---

## 9. Boas Práticas

- Nunca compartilhe o token do bot publicamente.
- Revise regularmente os administradores do canal para manter a segurança.
- Defina horários adequados para envio de mensagens (evite horários muito cedo ou tarde).
- Para canais grandes, considere usar um plano de distribuição mais espaçado.
- Documente as configurações do canal em um arquivo seguro (não no `.env`).

---

## Referências

- [Documentação oficial do Telegram Bot API](https://core.telegram.org/bots/api)
- [BotFather](https://t.me/BotFather)
- [myidbot](https://t.me/myidbot)