From c0b87c40a4e0c7be776bdad70fcc1b406f0ada50 Mon Sep 17 00:00:00 2001 From: marco Date: Mon, 17 Aug 2026 18:50:41 -0300 Subject: [PATCH] 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. --- .env | 2 +- TELEGRAM_SETUP.md | 253 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 TELEGRAM_SETUP.md diff --git a/.env b/.env index 929fd9b..dfed1f1 100644 --- a/.env +++ b/.env @@ -31,7 +31,7 @@ LLAMACPP_MODEL=qwen2.5-coder-3b-instruct-q4_k_m.gguf # Configuração do Telegram TELEGRAM_BOT_TOKEN=8638829617:AAEXTF0a7g66XRPcUb9gvw8t2StUPstX6VI -TELEGRAM_CHAT_ID=7889499475 +TELEGRAM_CHAT_ID=-1004366529212 # Idioma LANGUAGE=pt-BR diff --git a/TELEGRAM_SETUP.md b/TELEGRAM_SETUP.md new file mode 100644 index 0000000..0a008e3 --- /dev/null +++ b/TELEGRAM_SETUP.md @@ -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)