Como Ligar o HappyCapy ao Telegram: Execute um Agente de IA Completo em Qualquer Conversa
O seu agente HappyCapy — com todas as suas ferramentas, competências e capacidades — acessível diretamente a partir do Telegram.
Most Telegram bots respondem a perguntas. A ponte Telegram da HappyCapy executa claude --print — cada mensagem que envia desencadeia uma sessão completa do Claude Code com acesso a Bash, operações de ficheiros, pesquisa na web, geração de imagens e mais de 300 000 Skills. Peça-lhe para fazer scraping a um website, escrever um script em Python e executá-lo, ou gerar um vídeo. Ele fá-lo-á. Isto não é um chatbot. É um agente que, por acaso, vive no seu chat do Telegram.
Porque É Diferente de um Bot do Telegram
Construir um bot do Telegram é um projeto de fim de semana. Regista-se com o BotFather, obtém um token, chama a Telegram Bot API, passa as mensagens recebidas a uma API de LLM, devolve a resposta. O resultado é uma máquina de autocompletar sofisticada. Não tem sistema de ficheiros. Não consegue executar código. Não consegue desencadear workflows. Não consegue fazer nada que a API do LLM não consiga fazer numa única resposta sem estado.
A arquitetura da HappyCapy é diferente em todas as camadas. A HappyCapy corre como uma sandbox Linux sempre ativa no Fly.io — acesso root, Python 3.11, Node.js v24, armazenamento de ficheiros persistente. Quando a sua mensagem do Telegram chega, a ponte chama claude --print com a sua mensagem como entrada. Essa invocação tem acesso total a ferramentas: execução de Bash, leitura/escrita de ficheiros, pesquisa na web, geração de imagens, geração de vídeo e toda a biblioteca de mais de 300 000 Skills. O agente pode abrir uma nova shell, executar um script, ler o resultado e enviá-lo de volta — tudo dentro da mesma interação da conversa.
A diferença prática entre estas duas abordagens não é incremental. Um bot genérico do Telegram consegue dizer-lhe as condições meteorológicas. O bot do Telegram da HappyCapy consegue escrever código para obter dados meteorológicos de três APIs, compará-los, criar um gráfico, guardá-lo como PNG e enviar-lho como imagem — numa única mensagem, sem sair do Telegram.
| Funcionalidade | Bot Genérico do Telegram | Bot Telegram da HappyCapy |
|---|---|---|
| Responde a perguntas | Sim | Sim |
| Executa comandos Bash | Não | Sim |
| Escreve e executa código | Não | Sim |
| Acede a ficheiros persistentes | Não | Sim |
| Gera imagens com IA | Não (precisa de integração separada) | Sim, nativamente |
| Gera vídeo | Não | Sim |
| Web scraping | Não | Sim |
| Acesso a mais de 300 000 Skills | Não | Sim |
| Funciona 24 horas por dia sem o seu computador | Não | Sim (Fly.io sempre ativo) |
| Histórico de conversa por utilizador | Limitado | Completo e persistente |
O Que Pode Realmente Fazer
A lista de capacidades não é teórica. São coisas que os utilizadores fazem hoje:
- Pedir ao bot para fazer scraping a um website e devolver dados estruturados como tabela ou JSON
- Fazê-lo escrever um script em Python, executá-lo na sandbox e devolver o stdout — sem necessidade de um IDE
- Gerar uma imagem com IA a partir de um prompt e recebê-la diretamente no chat do Telegram
- Desencadear qualquer uma das mais de 300 000 Skills da HappyCapy a meio da conversa — geração de PDF, criação de folhas de cálculo, slides PPTX, síntese de áudio
- Pesquisar na web, ler várias fontes e devolver um resumo sintetizado com citações
- Criar e guardar ficheiros em armazenamento persistente, e depois recuperá-los ou atualizá-los em mensagens posteriores
- Executar tarefas agendadas: o agente pode correr um script todas as manhãs e enviar-lhe o resultado por mensagem
- Monitorizar um URL ou endpoint de API e avisá-lo quando algo muda
- Processar documentos carregados — cole um link de CSV e receba a análise de volta
- Encadear workflows de vários passos que de outra forma exigiriam alternar entre cinco ferramentas diferentes
Vantagens
- Sempre ativo, sem necessidade de portátil. A sandbox corre na infraestrutura do Fly.io. Pode enviar uma mensagem ao bot a partir do seu telemóvel às 2 da manhã e ele executará código num servidor que nunca precisa de tocar.
- Interface única para tudo. Em vez de abrir o Claude, depois um editor de código, depois um browser, depois uma ferramenta de imagem — uma única mensagem do Telegram desencadeia tudo isso.
- O contexto persiste. O histórico de conversa é guardado por utilizador. Pode referir-se a algo que perguntou há três dias sem ter de reexplicar o contexto.
- Acesso root total na sandbox. O agente pode instalar pacotes, escrever ficheiros e executar qualquer comando Unix. Sem as restrições que um chatbot de consumo imporia.
- Mais de 300 000 Skills disponíveis instantaneamente. Qualquer workflow que tenha sido empacotado como uma Skill da HappyCapy está a uma frase de distância.
- Partilhável. Dê o nome de utilizador do bot a um colega ou cliente. Vários utilizadores podem interagir em simultâneo, cada um com um histórico de conversa isolado.
- Nível gratuito disponível. A própria ponte do Telegram não acrescenta qualquer custo ao seu plano existente da HappyCapy.
Casos de Uso Reais
O programador freelancer que deixou o portátil no escritório. Fez um push de um commit, detetou um bug nos logs de deploy e já está a sair pela porta. A partir do telemóvel, envia uma mensagem ao bot: "Vai buscar os últimos logs de deploy do servidor e diz-me do que se está a queixar a linha 847." Trinta segundos depois, tem a resposta. Responde: "Escreve um patch e abre um PR." Feito. Sem abrir o portátil.
O empresário que monitoriza métricas diariamente. Em vez de entrar em cinco dashboards todas as manhãs, o bot executa um resumo agendado. Todos os dias às 8h: recolhe dados de receita do Stripe, contagens de visitantes de uma API de análise e níveis de inventário do Shopify. Formata o resumo e envia-o como mensagem do Telegram antes de terminar o primeiro café. A configuração levou uma única conversa com o bot.
O investigador que precisa de extração rápida de dados. Está a ler um artigo e quer cruzar um conjunto de dados com três outras fontes. Mudar para um browser, navegar até cada fonte, descarregar CSVs e fazer uma comparação demora 20 minutos. Enviar uma mensagem ao bot com os URLs e uma descrição do que precisa demora dois. O bot faz scraping, analisa, compara e devolve uma tabela.
O pai que criou um assistente de trabalhos de casa. Os filhos já têm uma conta do Telegram. O bot da HappyCapy foi adicionado a um grupo familiar. Consegue explicar problemas de matemática passo a passo, gerar diagramas, escrever perguntas de prática e verificar respostas — sem anúncios, sem criação de conta e sem o ciclo de distração de um chatbot de consumo. O pai fica com o token de administrador; os filhos ficam com uma ferramenta focada.
Como Configurar
A configuração demora menos de cinco minutos se tiver uma conta HappyCapy. O processo começa com o BotFather do Telegram: envie uma mensagem a @BotFather, execute /newbot, escolha um nome e receba um token de bot — uma string com o aspeto 7384920156:AAF.... Esse token é tudo o que a HappyCapy precisa para saber para onde encaminhar as conversas.
Dentro da HappyCapy, a skill do Telegram trata do resto. Execute a skill, cole o token do seu bot quando for solicitado, e a ponte fica ativa. A skill inicia um ciclo de polling na sandbox que escuta mensagens recebidas do Telegram e encaminha-as através do claude --print com acesso total a ferramentas. O histórico de conversa é guardado por ID de utilizador do Telegram, pelo que cada pessoa que envia uma mensagem ao seu bot obtém a sua própria sessão persistente.
A skill completa, com scripts de configuração, documentação de variáveis de ambiente e opções de configuração para limitação de taxa e listas de utilizadores permitidos, está disponível em github.com/ndpvt-web/happycapy-telegram. Se quiser uma compreensão mais profunda de porque a arquitetura de agente da HappyCapy difere de uma configuração típica de chatbot antes de começar, AI Agent vs Chatbot aborda a distinção em detalhe. E se está a pensar em executar a sua própria infraestrutura de IA persistente em vez de depender do Fly.io, vale a pena ler primeiro a análise Mac Mini as AI Server 2026.
Perguntas Frequentes
O bot funciona 24 horas por dia ou só quando o meu computador está ligado? Funciona 24 horas por dia. A sandbox vive na infraestrutura do Fly.io, não na sua máquina local. Depois de implementar a skill do Telegram, ele mantém-se ativo sem que o seu computador esteja ligado ou sequer conectado à internet.
O bot consegue aceder aos meus ficheiros e ferramentas da HappyCapy? Sim. O bot corre dentro da sua sandbox da HappyCapy, o que significa que tem acesso a tudo nesse ambiente: ficheiros que guardou, skills que instalou, variáveis de ambiente que definiu e quaisquer integrações que tenha ligado. É o seu agente, acessível através de uma interface diferente.
Isto é gratuito? A própria skill da ponte do Telegram é gratuita. Os seus custos são determinados pelo seu plano HappyCapy, que cobre a computação da sandbox e a utilização do modelo de IA. Não há taxas adicionais para a camada de integração do Telegram.
Como funciona o histórico de conversa por utilizador? Cada ID de utilizador do Telegram obtém a sua própria thread de conversa guardada na sandbox. Quando o utilizador A envia uma mensagem, o bot carrega o histórico do utilizador A e acrescenta a nova interação. As mensagens do utilizador B ficam completamente isoladas. O histórico é persistente entre sessões — uma conversa que teve há uma semana continua acessível no contexto, a menos que a limpe explicitamente.
Posso restringir quem pode usar o bot? Sim. A skill suporta uma configuração de lista de permissões. Pode especificar uma lista de IDs ou nomes de utilizador do Telegram autorizados a interagir com o bot. As mensagens de utilizadores fora da lista de permissões são ignoradas silenciosamente ou recebem uma mensagem de rejeição personalizada — à sua escolha.
O que acontece se o Telegram aplicar limitação de taxa ao meu bot? A skill trata da limitação de taxa com recuo exponencial. Se o Telegram devolver uma resposta 429, a ponte pausa, aguarda o período de repetição necessário e retoma automaticamente. Não perderá mensagens. Na prática, os limites de taxa só são acionados sob carga simultânea elevada, o que é configurável nas definições da skill.
Várias pessoas podem usar o bot simultaneamente? Sim. O ciclo de polling processa mensagens de forma assíncrona, e cada sessão de utilizador é independente. Não há fila que bloqueie um utilizador enquanto outro está a ser atendido. Sob carga muito elevada, pode escalar a instância da sandbox no Fly.io para gerir mais sessões simultâneas — a documentação da skill aborda esta configuração.
Considerações Finais
A integração com o Telegram não é uma funcionalidade pelo simples facto de existir — remove o último ponto de fricção entre si e um agente de IA totalmente capaz. A sua sandbox da HappyCapy já executa código, gera media e orquestra mais de 300 000 Skills. A ponte do Telegram significa que acede a tudo isso a partir de onde já está, sem mudança de contexto. Quer isso seja útil às 2 da manhã quando está a fazer debugging remotamente, quer seja útil todas as manhãs quando quer um briefing estruturado antes de abrir o portátil — é o mesmo agente, agora disponível em qualquer bolso.
