docs(telegram): add setup guide and update chat ID
Adds comprehensive documentation for creating a Telegram bot, configuring a group, and setting permissions. Updates TELEGRAM_CHAT_ID in .env to the correct group identifier for automated messaging.
This commit is contained in:
marco
@@ -0,0 +1,253 @@
|
||||
# Como criar um Bot no Telegram e configurar um Grupo
|
||||
|
||||
Este guia explica passo a passo como criar um bot no Telegram, criar um grupo, adicionar usuários e configurar tudo para que os membros do grupo recebam 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 Grupo no Telegram
|
||||
|
||||
### 2.1. Criar o grupo
|
||||
|
||||
1. No Telegram, clique no ícone de **menu** (três linhas) e selecione **Novo grupo**.
|
||||
2. Adicione pelo menos um contato inicial para criar o grupo (você pode removê-lo depois).
|
||||
3. Defina um nome para o grupo (ex: `Insights ThorAgentIA`).
|
||||
4. (Opcional) Adicione uma foto e descrição.
|
||||
|
||||
### 2.2. Tornar o grupo público ou privado
|
||||
|
||||
- **Grupo público**: Qualquer pessoa pode encontrar e solicitar entrada.
|
||||
- **Grupo privado**: Apenas usuários convidados podem entrar.
|
||||
|
||||
Recomenda-se usar grupo **privado** para maior controle.
|
||||
|
||||
### 2.3. Configurar permissões do grupo
|
||||
|
||||
1. Clique no nome do grupo no topo.
|
||||
2. Clique em **Grupo** (ou **Editar grupo**).
|
||||
3. Ajuste as permissões:
|
||||
- **Enviar mensagens**: Permitido para todos os membros.
|
||||
- **Enviar fotos/vídeos**: Conforme necessidade.
|
||||
- **Adicionar membros**: Apenas administradores.
|
||||
|
||||
---
|
||||
|
||||
## 3. Adicionar o Bot ao Grupo
|
||||
|
||||
### 3.1. Adicionar como administrador (recomendado)
|
||||
|
||||
1. Abra o grupo e clique no nome do grupo 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.
|
||||
|
||||
### 3.2. Conceder permissões ao bot
|
||||
|
||||
Para que o bot possa enviar mensagens no grupo, ele precisa ter a permissão **Enviar mensagens**.
|
||||
|
||||
#### Como localizar essa permissão no Telegram
|
||||
|
||||
**Telegram Desktop / Web**
|
||||
1. Abra o grupo.
|
||||
2. Clique no **nome do grupo** 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 **Enviar mensagens**.
|
||||
7. Clique em **Salvar** no final da tela.
|
||||
|
||||
**Telegram Android / iOS**
|
||||
1. Abra o grupo.
|
||||
2. Toque no **nome do grupo** no topo para abrir as informações.
|
||||
3. Toque em **Administradores**.
|
||||
4. Na lista, toque no seu bot.
|
||||
5. Ative a opção **Enviar mensagens**.
|
||||
6. Toque no ícone de **confirmar/check** no canto superior direito para salvar.
|
||||
|
||||
#### Importante sobre a permissão "Enviar mensagens"
|
||||
|
||||
Essa permissão controla se o administrador pode postar mensagens no grupo. 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 no grupo. Para enviar mensagens proativamente, ele precisa ser administrador com essa permissão ativada.
|
||||
|
||||
#### Observação adicional: permissão padrão do grupo
|
||||
|
||||
Além da permissão do bot, verifique também a permissão geral do grupo para mensagens:
|
||||
1. Abra o grupo e clique no nome do grupo no topo.
|
||||
2. Vá em **Permissões do grupo** (ou **Tipo de grupo / Permissões**).
|
||||
3. Confira se **Enviar mensagens** está definida como **Todos os membros** ou, se for **Somente administradores**, certifique-se de que o bot está na lista de administradores.
|
||||
|
||||
Isso também influencia se os usuários comuns conseguem ver e interagir com as mensagens do bot.
|
||||
|
||||
---
|
||||
|
||||
## 4. Adicionar Usuários ao Grupo
|
||||
|
||||
### 4.1. Convidar usuários diretamente
|
||||
|
||||
1. Abra o grupo e clique no nome do grupo no topo.
|
||||
2. Clique em **Adicionar membro**.
|
||||
3. Pesquise pelo usuário (username ou nome).
|
||||
4. Selecione o usuário e confirme.
|
||||
|
||||
### 4.2. Compartilhar link de convite
|
||||
|
||||
1. Abra o grupo e clique no nome do grupo no topo.
|
||||
2. Clique em **Convite para o grupo** (ou **Link do grupo**).
|
||||
3. Clique em **Copiar link** ou **Convidar por link**.
|
||||
4. Compartilhe o link com os usuários que deseja adicionar.
|
||||
|
||||
> **Dica**: Para grupos privados, você pode definir um link de convite com data de expiração ou limite de uso.
|
||||
|
||||
### 4.3. Aprovar solicitações de entrada (grupos privados)
|
||||
|
||||
Se o grupo for privado, os usuários receberão uma solicitação de entrada. Os administradores devem aprovar essas solicitações.
|
||||
|
||||
---
|
||||
|
||||
## 5. Obter o Chat ID do Grupo
|
||||
|
||||
Para configurar o bot para enviar mensagens para o grupo, você precisa do **Chat ID** do grupo.
|
||||
|
||||
### 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 chat ID do grupo se houver.
|
||||
|
||||
### 5.2. Método 2: Usando a API do Telegram
|
||||
|
||||
1. Adicione o bot ao grupo (veja seção 3).
|
||||
2. Envie uma mensagem qualquer no grupo (ex: `/start`).
|
||||
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 Chat ID do grupo.
|
||||
|
||||
### 5.3. Método 3: Usando um bot auxiliar
|
||||
|
||||
1. Adicione o bot **@myidbot** ao grupo.
|
||||
2. Envie o comando `/myid`.
|
||||
3. O bot irá responder com o Chat ID do grupo.
|
||||
|
||||
---
|
||||
|
||||
## 6. Configurar o BotThorAgentIA para o Grupo
|
||||
|
||||
### 6.1. Configurar o arquivo `.env`
|
||||
|
||||
Edite o arquivo `.env` do projeto ThorAgentIA com o token e chat ID obtidos:
|
||||
|
||||
```env
|
||||
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGhIJKlmNoPQRsTUVwxyz1234567890
|
||||
TELEGRAM_CHAT_ID=-100XXXXXXXXXX
|
||||
```
|
||||
|
||||
> **Importante**: O Chat ID do grupo geralmente começa com `-100` (ex: `-1001234567890`).
|
||||
|
||||
### 6.2. Testar a conexão
|
||||
|
||||
Execute o script principal para verificar se o bot envia mensagens corretamente para o grupo:
|
||||
|
||||
```bash
|
||||
source venv/bin/activate
|
||||
python3 main.py
|
||||
```
|
||||
|
||||
Se configurado corretamente, o bot começará a enviar insights automaticamente para o grupo nos horários definidos.
|
||||
|
||||
---
|
||||
|
||||
## 7. Gerenciar Usuários e Permissões
|
||||
|
||||
### 7.1. Adicionar novos usuários
|
||||
|
||||
- Use o link de convite do grupo (seção 4.2).
|
||||
- Ou adicione diretamente pelo menu do grupo.
|
||||
|
||||
### 7.2. Remover usuários
|
||||
|
||||
1. Abra o grupo e clique no nome do grupo.
|
||||
2. Vá em **Membros**.
|
||||
3. Clique no usuário que deseja remover.
|
||||
4. Selecione **Remover membro**.
|
||||
|
||||
### 7.3. Promover usuários a administradores
|
||||
|
||||
1. Abra o grupo e clique no nome do grupo.
|
||||
2. Vá em **Administradores**.
|
||||
3. Clique em **Adicionar administrador**.
|
||||
4. Pesquise e selecione o usuário.
|
||||
5. Defina as permissões desejadas.
|
||||
|
||||
---
|
||||
|
||||
## 8. Solução de Problemas
|
||||
|
||||
### O bot não envia mensagens para o grupo
|
||||
|
||||
1. Verifique se o bot é administrador do grupo.
|
||||
2. Verifique se a permissão **Enviar 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 grupo.
|
||||
2. Verifique se o grupo não está no modo "Somente administradores" para enviar mensagens.
|
||||
3. Para grupos grandes, verifique se o bot não foi silenciado pelos usuários.
|
||||
|
||||
### O bot não responde a comandos no grupo
|
||||
|
||||
1. Verifique se o bot está ativo no grupo.
|
||||
2. Confira se o token do bot está correto.
|
||||
3. Verifique se há restrições de permissão no grupo.
|
||||
|
||||
---
|
||||
|
||||
## 9. Boas Práticas
|
||||
|
||||
- Nunca compartilhe o token do bot publicamente.
|
||||
- Revise regularmente os membros do grupo para manter a segurança.
|
||||
- Defina horários adequados para envio de mensagens (evite horários muito cedo ou tarde).
|
||||
- Para grupos grandes, considere usar um plano de distribuição mais espaçado.
|
||||
- Documente as configurações do grupo 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)
|
||||
Reference in New Issue
Block a user