Como Conectar o HappyCapy ao Telegram: Rode um Agente de IA Completo em Qualquer Chat
Seu agente HappyCapy — com todas as suas ferramentas, skills e capacidades — acessível diretamente pelo Telegram.
A maioria dos bots do Telegram responde perguntas. A ponte de Telegram do HappyCapy executa claude --print — cada mensagem que você envia dispara uma sessão completa do Claude Code com acesso a Bash, operações de arquivos, busca na web, geração de imagens e mais de 300.000 Skills. Peça para ele extrair dados de um site, escrever um script em Python e executá-lo, ou gerar um vídeo. Ele fará. Isso não é um chatbot. É um agente que por acaso vive no seu chat do Telegram.
Por Que Isso É Diferente de um Bot do Telegram
Construir um bot do Telegram é um projeto de fim de semana. Você se registra com o BotFather, obtém um token, chama a API de Bot do Telegram, passa as mensagens recebidas para uma API de LLM, retorna a resposta. O resultado é uma máquina sofisticada de autocompletar. Ela não tem sistema de arquivos. Não consegue executar código. Não consegue disparar workflows. Não consegue fazer nada que a API do LLM não consiga fazer em uma única resposta sem estado.
A arquitetura do HappyCapy é diferente em cada camada. O HappyCapy roda como um sandbox Linux sempre ativo no Fly.io — acesso root, Python 3.11, Node.js v24, armazenamento de arquivos persistente. Quando sua mensagem do Telegram chega, a ponte chama claude --print com sua mensagem como entrada. Essa invocação tem acesso completo a ferramentas: execução de Bash, leitura/escrita de arquivos, busca 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 um novo shell, executar um script, ler a saída e enviá-la de volta para você — tudo dentro do mesmo turno de conversa.
A diferença prática entre essas duas abordagens não é incremental. Um bot genérico do Telegram consegue dizer a previsão do tempo. O bot do Telegram do HappyCapy consegue escrever código para buscar dados meteorológicos de três APIs, compará-los, plotar um gráfico, salvá-lo como PNG e enviá-lo a você como uma imagem — em uma única mensagem, sem que você precise sair do Telegram.
| Recurso | Bot Genérico do Telegram | Bot do Telegram do HappyCapy |
|---|---|---|
| Responde perguntas | Sim | Sim |
| Executa comandos Bash | Não | Sim |
| Escreve e executa código | Não | Sim |
| Acessa arquivos persistentes | Não | Sim |
| Gera imagens com IA | Não (precisa de integração separada) | Sim, nativamente |
| Gera vídeo | Não | Sim |
| Extração de dados da web | Não | Sim |
| Acesso a mais de 300.000 Skills | Não | Sim |
| Roda 24/7 sem seu computador | Não | Sim (Fly.io sempre ativo) |
| Histórico de conversa por usuário | Limitado | Completo, persistente |
O Que Você Pode Realmente Fazer
A lista de capacidades não é teórica. Estas são coisas que usuários fazem hoje:
- Pedir ao bot para extrair dados de um site e retorná-los como uma tabela estruturada ou JSON
- Fazer com que ele escreva um script Python, o execute no sandbox e retorne o stdout — sem necessidade de IDE
- Gerar uma imagem com IA a partir de um prompt e recebê-la diretamente no chat do Telegram
- Disparar qualquer uma das mais de 300.000 Skills do HappyCapy no meio da conversa — geração de PDF, criação de planilhas, slides PPTX, síntese de áudio
- Pesquisar na web, ler várias fontes e retornar um resumo sintetizado com citações
- Criar e salvar arquivos em armazenamento persistente, depois recuperá-los ou atualizá-los em mensagens posteriores
- Executar tarefas agendadas: o agente pode rodar um script toda manhã e enviar a você a saída
- Monitorar uma URL ou endpoint de API e alertá-lo quando algo mudar
- Processar documentos enviados — cole um link de CSV, receba a análise de volta
- Encadear workflows de múltiplas etapas que de outra forma exigiriam alternar entre cinco ferramentas diferentes
Prós
- Sempre ativo, sem necessidade de laptop. O sandbox roda na infraestrutura do Fly.io. Você pode mandar mensagem para o bot do seu celular às 2h da manhã e ele executará código em um servidor que você nunca precisa tocar.
- Interface única para tudo. Em vez de abrir o Claude, depois um editor de código, depois um navegador, depois uma ferramenta de imagem — uma única mensagem no Telegram dispara tudo isso.
- O contexto persiste. O histórico de conversa é armazenado por usuário. Você pode se referir a algo que perguntou três dias atrás sem precisar reexplicar o contexto.
- Acesso root completo no sandbox. O agente pode instalar pacotes, escrever arquivos e executar qualquer comando Unix. Sem 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 do HappyCapy está a uma frase de distância.
- Compartilhável. Dê o nome de usuário do bot para um colega ou cliente. Vários usuários podem interagir simultaneamente, cada um com histórico de conversa isolado.
- Camada gratuita disponível. A própria ponte de Telegram não adiciona custo algum além do seu plano HappyCapy existente.
Casos de Uso Reais
O desenvolvedor freelancer que esqueceu o laptop no escritório. Você enviou um commit, notou um bug nos logs de deploy, e já está saindo pela porta. Do seu celular, você manda mensagem ao bot: "Puxe os logs de deploy mais recentes do servidor e me diga do que a linha 847 está reclamando." Trinta segundos depois você tem a resposta. Você responde: "Escreva um patch e abra um PR." Pronto. Nenhum laptop aberto.
O pequeno empresário que monitora métricas diariamente. Em vez de fazer login em cinco dashboards toda manhã, o bot executa um resumo agendado. Todo dia às 8h: ele puxa dados de receita do Stripe, contagem de visitantes de uma API de analytics e níveis de estoque do Shopify. Ele formata o resumo e o envia como uma mensagem no Telegram antes do primeiro café acabar. A configuração levou apenas uma conversa com o bot.
O pesquisador que precisa de extração rápida de dados. Você está lendo um artigo e quer cruzar referências de um conjunto de dados com três outras fontes. Mudar para um navegador, navegar até cada fonte, baixar CSVs e fazer uma comparação leva 20 minutos. Mandar mensagem ao bot com as URLs e uma descrição do que você precisa leva dois. O bot extrai, processa, compara e retorna uma tabela.
O pai que configurou um assistente de lição de casa. Os filhos já têm uma conta no Telegram. O bot do HappyCapy foi adicionado a um grupo familiar. Ele consegue explicar problemas de matemática passo a passo, gerar diagramas, escrever questões de prática e conferir respostas — sem anúncios, sem criação de conta, e sem o ciclo de distração de um chatbot de consumo. O pai mantém o token de administrador; os filhos ganham uma ferramenta focada.
Como Configurar
A configuração leva menos de cinco minutos se você tiver uma conta HappyCapy. O processo começa com o BotFather do Telegram: mande mensagem para @BotFather, execute /newbot, escolha um nome e receba um token de bot — uma string parecida com 7384920156:AAF.... Esse token é tudo que o HappyCapy precisa saber para rotear conversas.
Dentro do HappyCapy, a skill do Telegram cuida do resto. Execute a skill, cole seu token de bot quando solicitado, e a ponte estará ativa. A skill inicia um loop de polling no sandbox que escuta mensagens recebidas do Telegram e as roteia através de claude --print com acesso completo a ferramentas. O histórico de conversa é armazenado por ID de usuário do Telegram, então cada pessoa que manda mensagem para o seu bot recebe 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 permissão de usuários está disponível em github.com/ndpvt-web/happycapy-telegram. Se você quiser um entendimento mais profundo de por que a arquitetura de agente do HappyCapy difere de uma configuração de chatbot típica antes de começar, AI Agent vs Chatbot cobre a distinção em detalhes. E se você está pensando em rodar sua própria infraestrutura de IA persistente em vez de depender do Fly.io, vale a pena ler antes a análise do Mac Mini as AI Server 2026.
Perguntas Frequentes
O bot roda 24/7 ou apenas quando meu computador está ligado? Ele roda 24/7. O sandbox vive na infraestrutura do Fly.io, não na sua máquina local. Depois que você implanta a skill do Telegram, ela continua ativa sem que seu computador esteja ligado ou mesmo conectado à internet.
O bot pode acessar meus arquivos e ferramentas do HappyCapy? Sim. O bot roda dentro do seu sandbox HappyCapy, o que significa que ele tem acesso a tudo naquele ambiente: arquivos que você armazenou, skills que você instalou, variáveis de ambiente que você configurou e quaisquer integrações que você conectou. É o seu agente, acessível através de uma interface diferente.
Isso é gratuito para usar? A própria skill de ponte do Telegram é gratuita. Seus custos são determinados pelo seu plano HappyCapy, que cobre o processamento do sandbox e o uso 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 usuário? Cada ID de usuário do Telegram recebe sua própria thread de conversa armazenada no sandbox. Quando o usuário A envia uma mensagem, o bot carrega o histórico do usuário A e anexa o novo turno. As mensagens do usuário B são completamente isoladas. O histórico é persistente entre sessões — uma conversa que você teve há uma semana ainda está acessível no contexto, a menos que você a limpe explicitamente.
Posso restringir quem pode usar o bot? Sim. A skill suporta uma configuração de lista de permissões. Você pode especificar uma lista de IDs de usuário ou nomes de usuário do Telegram que têm permissão para interagir com o bot. Mensagens de usuários que não estão na lista de permissões são silenciosamente ignoradas ou retornam uma mensagem de rejeição personalizada — sua escolha.
O que acontece se o Telegram limitar a taxa do meu bot? A skill lida com limitação de taxa com backoff exponencial. Se o Telegram retornar uma resposta 429, a ponte pausa, aguarda o período de nova tentativa necessário e retoma automaticamente. Você não perderá mensagens. Na prática, os limites de taxa só são acionados sob carga simultânea pesada, o que é configurável nas configurações da skill.
Várias pessoas podem usar o bot simultaneamente? Sim. O loop de polling processa mensagens de forma assíncrona, e cada sessão de usuário é independente. Não há fila que bloqueie um usuário enquanto outro está sendo atendido. Sob carga muito alta, você pode escalar a instância do sandbox no Fly.io para lidar com mais sessões simultâneas — a documentação da skill cobre essa configuração.
Considerações Finais
A integração com o Telegram não é um recurso por si só — ela remove o último ponto de atrito entre você e um agente de IA totalmente capaz. Seu sandbox HappyCapy já executa código, gera mídia e orquestra mais de 300.000 Skills. A ponte de Telegram significa que você acessa tudo isso de onde quer que já esteja, sem troca de contexto. Seja isso útil às 2h da manhã quando você está depurando remotamente ou útil toda manhã quando você quer um briefing estruturado antes de abrir seu laptop — é o mesmo agente, agora disponível em cada bolso.
