Como Ligar o HappyCapy ao iMessage: Um Agente de IA Completo no Apple Messages
BlueBubbles + capy-bridge da HappyCapy: a mesma stack utilizada pelo Hermes Agent — agora disponível como skill de um clique.
A Apple nunca lançou uma API do iMessage. Nem em 2015. Nem em 2020. Nem hoje. Durante anos, construir um agente de IA que vive dentro das suas iMessages exigia um jailbreak, um plano empresarial de 200 dólares/mês, ou um profundo conhecimento de protocolos não documentados. Em junho de 2026, um caminho gratuito e de código aberto finalmente funciona de forma fiável — e é a mesma arquitetura que o projeto Hermes Agent, com 188 000 estrelas, utiliza em produção.
Porque É que o iMessage É a Plataforma Mais Difícil (E Porque Isso Importa)
A maioria das plataformas de mensagens tem uma API. O Telegram publicou a sua em 2015. O Slack tem webhooks desde o primeiro dia. O WhatsApp abriu a sua Business API em 2018. O iMessage nunca teve nada disto, e isso não é um descuido.
O protocolo iMessage da Apple utiliza encriptação de ponta a ponta diretamente ligada a Apple IDs e chaves específicas do dispositivo. Essas chaves são geradas no hardware da Apple e nunca saem dele. Cada mensagem é encriptada e desencriptada num dispositivo físico da Apple. Não existe uma API do lado do servidor porque não existe nenhum servidor que detenha o conteúdo desencriptado. Trata-se de uma restrição criptográfica rígida — não uma decisão política que a Apple pudesse reverter com um comunicado de imprensa.
A consequência prática: nenhum processo Linux, nenhum contentor Docker, nenhuma VM na cloud consegue enviar ou receber iMessages de forma nativa. Nem com acesso root. Nem com um Apple ID válido. O protocolo simplesmente não funciona fora do hardware da Apple.
Para os programadores de agentes de IA, isto significa que a integração com o iMessage exige sempre um Mac no circuito. Essa é a resposta honesta, e é ela que molda tudo o resto neste artigo.
O reverso da moeda também é verdade: para os utilizadores Apple, esta arquitetura significa que o bot vive dentro da própria Messages.app. Sem aplicações de terceiros para instalar. Sem contas novas para criar. A IA responde através da mesma interface que a sua família e colegas já utilizam. Quando os seus contactos lhe enviam uma mensagem, não têm noção de que algo mudou — veem respostas provenientes do seu Apple ID, formatadas como iMessages nativas, com confirmações de leitura.
Essa combinação — fricção zero para o destinatário, privacidade criptográfica, e a plataforma em que os utilizadores Apple já confiam — é a razão pela qual o iMessage vale a complexidade adicional.
Como Funciona Na Realidade
A solução gratuita e de código aberto é o BlueBubbles. Trata-se de uma aplicação servidor para Mac com licença MIT, que corre no seu Mac, se regista com o seu Apple ID e expõe uma API REST local. O BlueBubbles funciona como uma ponte entre o protocolo iMessage (que exige macOS) e qualquer serviço externo capaz de fazer pedidos HTTP.
O capy-bridge da HappyCapy liga-se a essa API REST. Quando chega uma mensagem ao seu Apple ID, esta é a sequência exata:
| Passo | O Que Acontece |
|---|---|
| 1. iMessage recebida | A Apple entrega a mensagem ao seu Mac através do protocolo iMessage padrão |
| 2. O BlueBubbles intercepta | O servidor BlueBubbles no seu Mac lê a mensagem recebida |
| 3. Webhook POST | O BlueBubbles envia um POST com a payload da mensagem para o endpoint capy-bridge da HappyCapy |
| 4. A ponte processa | O capy-bridge analisa o remetente, o texto da mensagem e o histórico da conversa |
5. claude --print | A ponte inicia o Claude Code CLI com acesso total a ferramentas |
| 6. O Claude executa | O Claude executa ferramentas — bash, pesquisa web, operações de ficheiros, qualquer Skill instalada |
| 7. Resposta enviada | A resposta é enviada de volta através da API REST do BlueBubbles para a conversa original do iMessage |
| 8. iMessage entregue | O destinatário vê uma resposta na sua Messages.app em segundos |
Esta é a mesma arquitetura que o Hermes Agent utiliza. O projeto Hermes Agent — 188 000 estrelas no GitHub, construído pela Nous Research — encaminha a sua integração com o iMessage através do BlueBubbles na sua configuração de produção. A arquitetura foi testada sob stress em grande escala.
O detalhe fundamental no passo 5 é o claude --print. A HappyCapy não envia a sua mensagem para um chatbot que responde com texto. Ela executa o Claude Code CLI, que tem acesso total a ferramentas: execução de bash, leitura/escrita de ficheiros, pesquisa web, geração de imagens, e acesso à biblioteca de mais de 300 000 Skills da HappyCapy. O bot não se limita a responder — ele age.
O Que Pode Fazer
Depois de a ponte estar a funcionar, cada iMessage enviada para o seu Apple ID torna-se uma interface de comandos para a sua sandbox HappyCapy:
- Executar tarefas remotamente — envie uma tarefa a partir do seu iPhone e receba de volta um resultado totalmente executado, com o respetivo output
- Pedir ficheiros — peça um relatório em PDF, uma imagem gerada ou um script, e receba-o
- Pesquisar e resumir — peça ao agente para pesquisar na web e devolver um resumo estruturado
- Acionar mais de 300 000 Skills — todas as Skills da biblioteca da HappyCapy estão acessíveis a partir da Messages.app
- Executar bash na sua sandbox —
run ls /var/logexecuta no seu ambiente Linux da HappyCapy e devolve o output - Histórico por contacto — cada Apple ID ou número de telefone tem a sua própria conversa; o contexto mantém-se entre mensagens
- Funciona a partir de qualquer dispositivo Apple — iPhone, iPad, Mac, Apple Watch — qualquer coisa que envie iMessages consegue alcançar o bot
Vantagens
- Experiência Apple nativa — as respostas aparecem na conversa padrão da Messages.app; os destinatários não precisam de instalar nada
- Nenhuma aplicação de terceiros no dispositivo do destinatário — o bot comunica através da infraestrutura iMessage já existente
- Funciona com qualquer Apple ID — qualquer contacto que consiga enviar-lhe iMessages pode interagir com o bot
- Encriptação de ponta a ponta — o BlueBubbles não quebra a encriptação da Apple; lê as mensagens depois de estas serem desencriptadas no seu Mac
- Gratuito e de código aberto — o BlueBubbles tem licença MIT; não há custos de subscrição
- Arquitetura validada pelo Hermes — a mesma stack que sustenta um projeto de agente em produção com 188 000 estrelas
- Capacidade total de agente — o
claude --printdá ao bot acesso a bash, pesquisa web, operações de ficheiros e mais de 300 000 Skills
Casos de Uso Reais
Programador em movimento com o iPhone. Está longe do seu portátil e precisa de verificar se uma cron job foi executada, ver o final de um ficheiro de log ou reiniciar um serviço na sua sandbox HappyCapy. Envia o comando a partir da Messages.app no seu iPhone. A ponte executa-o e devolve o output como resposta. Sem cliente SSH, sem VPN, sem mudança de contexto.
Agregado familiar só com Apple. O seu parceiro, pais ou colegas de casa usam apenas iMessages e mais nada. Em vez de lhes pedir para instalarem o Telegram ou aprenderem uma nova interface, aponta o bot para o seu Apple ID existente. Todos interagem através da aplicação que já têm no dispositivo.
Empresário com clientes no iMessage. Comunica com clientes através do iMessage — é o que eles usam, e mudá-los para outra plataforma não é realista. Com a ponte a funcionar, pode pedir ao agente para resumir uma conversa longa, redigir uma resposta na sua voz, consultar o histórico de encomendas de um cliente, ou obter um relatório. A IA permanece no canal onde a relação já existe.
Investigador com um Mac. Mantém um Mac ligado na sua secretária. Quer um agente de IA sempre acessível — a partir do iPhone durante a viagem para o trabalho, do iPad numa reunião, ou do Mac de um colega numa emergência. O iMessage já está sincronizado em todos os dispositivos Apple que possui. O bot herda esse alcance automaticamente.
O Requisito do Mac — Uma Avaliação Honesta
A configuração exige um Mac com o BlueBubbles instalado e em execução, ligado à HappyCapy através do capy-bridge. O Mac tem de estar ativo e ligado à internet para que a ponte funcione. Se entrar em suspensão, o bot fica offline.
Esta é uma restrição real. Se não possui um Mac, ou se o seu Mac é um portátil que transporta consigo e fecha regularmente, o iMessage é o canal errado para si. As integrações do Telegram e do Slack da HappyCapy funcionam numa infraestrutura totalmente nativa em Linux, sem qualquer dependência de hardware.
Para quem já mantém um Mac sempre ligado — um Mac Mini debaixo da televisão, um Mac Studio num escritório em casa, um MacBook mais antigo ligado à corrente numa prateleira — a configuração é feita uma única vez e depois é inteiramente automática. O BlueBubbles arranca no login. O daemon capy-bridge arranca no login. O Mac continua a funcionar, e o bot também.
Se está a considerar hardware dedicado para este fim, o Mac Mini M4 de 2026, modelo base (799 dólares), é a opção mais prática. Consome cerca de 6 a 10 watts em repouso, suporta funcionamento 24 horas por dia, 7 dias por semana, sem ruído de ventoinha, e cabe num espaço mais pequeno do que um livro de bolso. Para uma análise completa das configurações do Mac Mini como servidor de IA, consulte Mac Mini as an AI Server in 2026.
Como Configurar
A configuração completa demora aproximadamente 10 minutos:
- Descarregue o BlueBubbles em bluebubbles.app — gratuito, licença MIT, código aberto
- Execute o assistente de configuração — inicie sessão com o seu Apple ID e conceda as permissões de Acessibilidade e Acesso Total ao Disco
- Anote o URL e a palavra-passe do BlueBubbles no ecrã de definições do BlueBubbles
- Instale o capy-bridge — execute
bash /app/export-port.sh 8766na HappyCapy para obter o seu URL de webhook, e depois execute a skill/happycapy-imessagena HappyCapy - Complete o assistente da HappyCapy — cole o URL do BlueBubbles, a palavra-passe e o URL do webhook; a ponte regista-se automaticamente
- Teste — envie uma iMessage a partir de outro dispositivo; deverá receber uma resposta em segundos
A documentação completa da skill e o código-fonte estão em github.com/ndpvt-web/happycapy-imessage.
Perguntas Frequentes
Preciso de manter o meu Mac ligado o tempo todo? Sim, para disponibilidade 24 horas por dia, 7 dias por semana. O Mac tem de estar ativo e ligado à internet para que o BlueBubbles e o capy-bridge recebam mensagens. Se quiser que o bot esteja disponível a qualquer hora, utilize hardware que possa permanecer ligado — um Mac Mini ou Mac Studio é ideal. Ative "Prevent display sleep" nas definições do BlueBubbles e desative a suspensão no Poupador de Energia do macOS (modo Transformador de Corrente).
Isto também funciona com SMS, ou apenas com iMessage? O BlueBubbles suporta tanto o iMessage (balões azuis) como o SMS (balões verdes), se o seu Mac tiver um iPhone ligado e o Hotspot Pessoal configurado para permitir o encaminhamento de SMS. Para a maioria das configurações, usar apenas iMessage é mais simples e fiável.
A Apple consegue ver as minhas mensagens através do BlueBubbles? Não. O BlueBubbles não quebra a encriptação de ponta a ponta da Apple. As mensagens são desencriptadas pelo macOS na sua máquina local, tal como sempre acontece, e depois o BlueBubbles lê-as a partir desse estado local desencriptado. Os servidores da Apple nunca veem conteúdo em texto simples — o mesmo que acontece ao usar a Messages.app normalmente.
O BlueBubbles é gratuito? Sim. O BlueBubbles tem licença MIT e é gratuito. Não há custos de subscrição. A aplicação servidor para Mac, o código-fonte e a documentação estão todos publicamente disponíveis em bluebubbles.app.
O que acontece se o meu Mac entrar em suspensão?
A ponte fica offline. As mensagens enviadas enquanto o Mac está suspenso não são processadas e não são respondidas retroativamente quando o Mac acorda. Para evitar isto: ative "Prevent display sleep" no BlueBubbles, desative a suspensão do sistema no Poupador de Energia do macOS para o modo Transformador de Corrente, ou execute caffeinate -di & num terminal. Para configurações sempre ativas, os Macs de secretária (Mini, Studio, Pro) são preferíveis aos portáteis.
Várias pessoas podem enviar mensagens ao bot a partir de Apple IDs diferentes? Sim. A ponte guarda um histórico de conversa separado por cada identificador do remetente. Cada Apple ID ou número de telefone tem a sua própria janela de contexto. Pode configurar uma lista de permissões (apenas identificadores específicos) ou deixá-la aberta a todas as iMessages recebidas.
Isto viola os termos de serviço da Apple? O BlueBubbles está numa zona cinzenta: a Apple não aprovou explicitamente pontes de terceiros para o iMessage, mas também não tomou qualquer ação contra o BlueBubbles nos mais de quatro anos em que este está em funcionamento. O projeto lê mensagens a partir do seu próprio Mac, sob o seu próprio Apple ID, da mesma forma que qualquer processo com Acesso Total ao Disco conseguiria. Utilizá-lo para a sua própria automação — e não para envio comercial em massa ou spam — está em linha com a forma como dezenas de milhares de programadores o utilizam. O projeto Hermes Agent inclui a integração com o BlueBubbles na sua configuração predefinida a partir de 2026.
Considerações Finais
Dos quatro canais de mensagens que a HappyCapy suporta — Telegram, Slack, WhatsApp e iMessage — o iMessage é o mais exigente a nível técnico para configurar. Exige um Mac, um servidor BlueBubbles em funcionamento, e uma ligação persistente entre o seu hardware e a sua sandbox HappyCapy. Isso representa mais peças móveis do que os outros canais.
Para utilizadores Apple que já vivem nesse ecossistema, é também o resultado mais fluido: um agente de IA completo que responde através da aplicação Messages que os seus contactos usam todos os dias, sem novas aplicações para instalar e sem novas contas para criar. A arquitetura está comprovada — a mesma stack por trás das 188 000 estrelas do Hermes Agent — e a HappyCapy encapsula-a numa skill de um só clique.
Se tem um Mac que fica sempre ligado, a configuração vale os 10 minutos.
