MÓDULO 4.1 / 7 DE 8
Telegram como interface de trabalho
Executar um bot restrito de consulta e entender onde a IA entra.
1Telegram é a interface, não o agente
O que é
Um bot recebe mensagens pela API do Telegram e devolve respostas. A inteligência pode vir de regras, de um programa ou de uma chamada a modelo. O aplicativo no celular não executa sozinho suas tarefas no servidor: existe um programa intermediário com permissões definidas.
Por que aprender
Separar interface e execução evita chamar qualquer resposta automática de agente inteligente. Primeiro construa um caminho confiável para receber e responder; depois conecte a capacidade necessária.
Conceitos-chave
Mensagem; Bot API; programa; agente; resultado.
Na prática
/status consulta o estado do bot sem IA. /relatorio calcula vendas fictícias sem IA. Um resumo em linguagem natural poderia ser acrescentado depois, preservando os números calculados.
✓ Faça
Desenhe: celular → Telegram → bot → função permitida → resposta. Marque em que etapa uma futura chamada a IA seria realmente útil.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
2Crie o bot e proteja o token
O que é
No Telegram, encontre o BotFather oficial e use /newbot. Escolha nome e identificador conforme as instruções mostradas. O token gerado autentica seu programa perante o Telegram. Guarde-o como TELEGRAM_BOT_TOKEN em um arquivo privado; o kit tem apenas valores de exemplo.
Por que aprender
Quem controla o token pode operar o bot. Capturas de tela do processo e URLs contendo o token podem vazar acesso. Se houver exposição, revogue o token no BotFather antes de continuar.
Conceitos-chave
BotFather; token; variável de ambiente; rotação.
Na prática
A professora cria um bot para uso pessoal. Ela não coloca o token no README e não envia o arquivo de credenciais para os alunos. Cada instalação usa suas próprias credenciais.
3Autorize pessoas e ações
O que é
O bot do kit aceita apenas conversas privadas e IDs configurados. Também aceita somente os comandos conhecidos. Verificar o ID é diferente de verificar o nome visível: nomes podem mudar. Uma mensagem de desconhecido não deve acionar leitura de arquivos ou comandos do sistema.
Por que aprender
Um bot encontrado na internet pode receber mensagens inesperadas. Autenticação do programa com token não significa autorização de qualquer pessoa que fale com ele. São controles distintos.
Conceitos-chave
ID numérico; lista de acesso; conversa privada; comandos fixos.
Na prática
O dono escreve /relatorio e recebe totais fictícios. Um usuário fora da lista não recebe dados. Mesmo o dono não pode escrever um comando de shell e esperar que o bot o execute.
Sequência para experimentar
- Prepare uma cópia de treino.
- Leia a função handle_message do kit. Localize a conferência de ID e chat privado antes do despacho dos comandos.
- Registre o resultado observado e a próxima correção.
4Comece com long polling
O que é
Long polling é o programa perguntar ao Telegram por mensagens e esperar um pouco quando não há novidades. É simples para aprender e não exige abrir uma porta pública de entrada. Webhook é outra estratégia, em que o Telegram chama um endereço HTTPS seu; não é necessária neste laboratório.
Por que aprender
Escolher um único modo reduz problemas de configuração. Mantenha uma única instância buscando mensagens para um bot: processos duplicados podem disputar atualizações.
Conceitos-chave
getUpdates; offset; timeout; instância única; acesso de saída.
Na prática
O processo aguarda até 25 segundos por uma mensagem. Ao recebê-la, atualiza o offset para não repetir a mesma consulta. Após uma falha de rede, espera antes de tentar de novo.
✓ Faça
Inicie com python3 bot.py. Use Ctrl+C para encerrar. Se surgir conflito, confira se outro processo usa o mesmo token ou se existe webhook configurado.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
5Conecte capacidades em etapas
O que é
O kit deliberadamente separa transporte e funções de trabalho. Começa determinístico: status e relatório de dados fictícios. Para acoplar IA, defina uma função com entrada limitada, timeout, teto de saída e revisão. Não exponha codex exec diretamente a mensagens públicas nem desative proteções para fazê-lo funcionar.
Por que aprender
Um programa previsível permite testar a base sem gastar API. Depois, você avalia se a IA melhora interpretação, resumo ou classificação e mede o resultado com uma referência conhecida.
Conceitos-chave
Função de domínio; limites; timeout; revisão; dados mínimos.
Na prática
Uma função de resumo pode receber apenas o total e três categorias, em vez de todo o diretório de projetos. O texto gerado nunca altera o total calculado pelo programa.
6Teste operação e falhas
O que é
Teste remetente permitido, bloqueado, grupo, comando desconhecido e dados ausentes. Logs devem informar tipo de falha e horário, sem token nem mensagens privadas completas. No laboratório, desligar o processo deve parar as respostas: isso prova que o programa local está no caminho.
Por que aprender
Uma resposta correta não prova que o bot está restrito nem que recupera rede. Um conjunto pequeno de cenários demonstra as propriedades importantes antes de migrar para uma VPS.
Conceitos-chave
Autoteste; falha de rede; logs sem segredo; interrupção; diagnóstico.
Na prática
Se /status funciona e /relatorio falha, investigue o arquivo de dados. Se nenhum funciona, confira processo, autenticação e conexão. Não troque o modelo: esses comandos nem usam IA.
Critérios para revisar sua entrega
Use esta rubrica depois do laboratório. Cada linha pede uma evidência; marcar leitura não significa que a prática foi executada.
| Critério | Evidência esperada | Se não passou |
|---|---|---|
| Escopo | A entrega corresponde ao objetivo desta aula. | Reduza a tarefa e nomeie um único resultado. |
| Entradas | Você sabe quais arquivos ou dados foram usados. | Liste as fontes e remova material sem relação. |
| Execução | O procedimento foi realizado no ambiente de treino. | Diferencie o que foi planejado do que foi feito. |
| Conferência | Um resultado foi comparado com uma referência. | Abra o arquivo ou repita a consulta verificável. |
| Segredos | Nenhum token, senha ou dado privado foi compartilhado. | Revise a cópia de trabalho antes de qualquer envio. |
| Continuidade | Outra pessoa consegue encontrar o próximo passo. | Atualize README e registre uma pendência concreta. |
MÃO NA MASSA / ~15 MIN OU EM ETAPAS
Um bot que responde sem executar mensagens
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Bot · dentro de materiais/bot
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
python3 bot.py --self-test
cp .env.example .env
chmod 600 .env
# Edite .env localmente; nunca compartilhe valores.
python3 bot.py --identify
# Preencha ALLOWED_USER_IDS com seu ID e encerre identificação.
python3 bot.py
Critério de pronto
Executar um bot restrito de consulta e entender onde a IA entra. Registre o arquivo produzido, o teste executado e o resultado observado.
Abrir arquivos e modelos do laboratórioConfira o que ficou
Uma mensagem do Telegram pode ser passada diretamente para o shell?
Ver resposta comentada
Não. O bot deve mapear comandos permitidos a funções definidas e verificar o remetente.
Se sua resposta foi diferente, volte ao tópico correspondente e escreva a diferença em uma frase. A checagem não bloqueia seu estudo.
Resumo do módulo
- Mensagem; Bot API; programa; agente; resultado.
- BotFather; token; variável de ambiente; rotação.
- ID numérico; lista de acesso; conversa privada; comandos fixos.
- getUpdates; offset; timeout; instância única; acesso de saída.
- Função de domínio; limites; timeout; revisão; dados mínimos.
- Autoteste; falha de rede; logs sem segredo; interrupção; diagnóstico.
Consulte a fonte
Ferramentas verificadas em 20/09/2026; nomes de telas e disponibilidade podem mudar.