Files

T

marco c0b87c40a4 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.

2026-08-17 18:50:41 -03:00

8.4 KiB

Raw Blame History

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

Abra o Telegram e pesquise por @BotFather ou acesse https://t.me/BotFather.
Clique em Iniciar ou envie o comando /start.

1.2. Criar o novo bot

Envie o comando /newbot.
Escolha um nome para o seu bot (ex: ThorAgentIA Bot). Este é o nome de exibição.
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

No Telegram, clique no ícone de menu (três linhas) e selecione Novo grupo.
Adicione pelo menos um contato inicial para criar o grupo (você pode removê-lo depois).
Defina um nome para o grupo (ex: Insights ThorAgentIA).
(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

Clique no nome do grupo no topo.
Clique em Grupo (ou Editar grupo).
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)

Abra o grupo e clique no nome do grupo no topo.
Clique em Administradores.
Clique em Adicionar administrador.
Pesquise pelo username do bot (ex: @thoragentia_bot).
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

Abra o grupo.
Clique no nome do grupo no topo para abrir as informações.
Clique em Administradores.
Na lista, clique no nome do seu bot.
Role até a seção Permissões de administrador.
Ative a opção Enviar mensagens.
Clique em Salvar no final da tela.

Telegram Android / iOS

Abra o grupo.
Toque no nome do grupo no topo para abrir as informações.
Toque em Administradores.
Na lista, toque no seu bot.
Ative a opção Enviar mensagens.
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:

Abra o grupo e clique no nome do grupo no topo.
Vá em Permissões do grupo (ou Tipo de grupo / Permissões).
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

Abra o grupo e clique no nome do grupo no topo.
Clique em Adicionar membro.
Pesquise pelo usuário (username ou nome).
Selecione o usuário e confirme.

4.2. Compartilhar link de convite

Abra o grupo e clique no nome do grupo no topo.
Clique em Convite para o grupo (ou Link do grupo).
Clique em Copiar link ou Convidar por link.
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

Acesse o BotFather.
Clique no bot criado (ex: @thoragentia_bot).
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

Adicione o bot ao grupo (veja seção 3).
Envie uma mensagem qualquer no grupo (ex: /start).
Acesse a seguinte URL no navegador (substitua SEU_TOKEN pelo token do bot):

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

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

Adicione o bot @myidbot ao grupo.
Envie o comando /myid.
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:

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:

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

Abra o grupo e clique no nome do grupo.
Vá em Membros.
Clique no usuário que deseja remover.
Selecione Remover membro.

7.3. Promover usuários a administradores

Abra o grupo e clique no nome do grupo.
Vá em Administradores.
Clique em Adicionar administrador.
Pesquise e selecione o usuário.
Defina as permissões desejadas.

8. Solução de Problemas

O bot não envia mensagens para o grupo

Verifique se o bot é administrador do grupo.
Verifique se a permissão Enviar mensagens está ativada para o bot.
Confirme se o TELEGRAM_BOT_TOKEN e TELEGRAM_CHAT_ID estão corretos no .env.
Verifique os logs do script para identificar erros.

Usuários não recebem as mensagens

Certifique-se de que os usuários são membros do grupo.
Verifique se o grupo não está no modo "Somente administradores" para enviar mensagens.
Para grupos grandes, verifique se o bot não foi silenciado pelos usuários.

O bot não responde a comandos no grupo

Verifique se o bot está ativo no grupo.
Confira se o token do bot está correto.
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).

8.4 KiB Raw Blame History