Como Conectar o HappyCapy ao iMessage: Um Agente de IA Completo no Apple Messages
BlueBubbles + capy-bridge da HappyCapy: a mesma stack usada pelo Hermes Agent — agora disponível como uma skill de um clique.
Apple nunca lançou uma API do iMessage. Nem em 2015. Nem em 2020. Nem hoje. Por anos, criar um agente de IA que vive dentro das suas iMessages exigia um jailbreak, um plano empresarial de US$ 200/mês, ou um profundo entendimento de protocolos não documentados. Em junho de 2026, um caminho gratuito e open-source finalmente funciona de forma confiável — e é a mesma arquitetura que o projeto Hermes Agent, com 188.000 estrelas, usa em produção.
Por que o iMessage é a plataforma mais difícil (e por que 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 sua Business API em 2018. O iMessage não tem nada disso, e isso não é um descuido.
O protocolo do iMessage da Apple usa criptografia de ponta a ponta vinculada diretamente a Apple IDs e chaves específicas de cada dispositivo. Essas chaves são geradas no hardware da Apple e nunca saem dele. Toda mensagem é criptografada e descriptografada em um dispositivo Apple físico. Não existe uma API do lado do servidor porque não existe um servidor que armazene o conteúdo descriptografado. Essa é uma restrição criptográfica rígida — não uma decisão de política que a Apple poderia reverter com um comunicado de imprensa.
A consequência prática: nenhum processo Linux, nenhum contêiner Docker, nenhuma VM na nuvem consegue enviar ou receber iMessages nativamente. Nem com acesso root. Nem com um Apple ID válido. O protocolo simplesmente não funciona fora do hardware da Apple.
Para desenvolvedores de agentes de IA, isso significa que a integração com o iMessage sempre exige um Mac no meio do processo. Essa é a resposta honesta, e ela molda tudo mais neste artigo.
O outro lado da moeda também é verdadeiro: para usuários Apple, essa arquitetura significa que o bot vive dentro do próprio Messages.app. Nenhum aplicativo de terceiros para instalar. Nenhuma nova conta para criar. A IA responde pela mesma interface que sua família e colegas já usam. Quando seus contatos te enviam mensagem, eles não percebem que nada mudou — veem respostas vindas do seu Apple ID, formatadas como iMessages nativas, com confirmações de leitura.
Essa combinação — zero atrito para o destinatário, privacidade criptográfica, na plataforma em que usuários Apple já confiam — é o motivo pelo qual o iMessage vale a complexidade adicional.
Como Funciona na Prática
A solução gratuita e open-source é o BlueBubbles. É uma aplicação de servidor para Mac licenciada sob MIT que roda no seu Mac, se registra com seu Apple ID e expõe uma API REST local. O BlueBubbles atua como uma ponte entre o protocolo do iMessage (que exige macOS) e qualquer serviço externo capaz de fazer requisições HTTP.
O capy-bridge do HappyCapy se conecta a essa API REST. Quando uma mensagem chega ao seu Apple ID, esta é a sequência exata:
| Etapa | O Que Acontece |
|---|---|
| 1. iMessage recebido | A Apple entrega a mensagem ao seu Mac via o protocolo padrão do iMessage |
| 2. BlueBubbles intercepta | O servidor BlueBubbles no seu Mac lê a mensagem recebida |
| 3. Webhook POST | O BlueBubbles envia um POST com o payload da mensagem para o endpoint capy-bridge do 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 a Claude Code CLI com acesso completo a ferramentas |
| 6. Claude executa | O Claude executa ferramentas — bash, busca na web, operações em arquivos, qualquer Skill instalada |
| 7. Resposta enviada | A resposta é enviada de volta pela API REST do BlueBubbles para a thread original do iMessage |
| 8. iMessage entregue | O destinatário vê uma resposta no Messages.app em segundos |
Essa é a mesma arquitetura que o Hermes Agent usa. O projeto Hermes Agent — 188.000 estrelas no GitHub, construído pela Nous Research — encaminha sua integração com o iMessage pelo BlueBubbles em sua configuração de produção. A arquitetura já foi testada em escala.
O detalhe-chave na etapa 5 é o claude --print. O HappyCapy não envia sua mensagem para um chatbot que responde com texto. Ele executa a Claude Code CLI, que tem acesso completo a ferramentas: execução de bash, leitura/escrita de arquivos, busca na web, geração de imagens e acesso à biblioteca de mais de 300.000 Skills do HappyCapy. O bot não apenas responde — ele age.
O Que Você Pode Fazer
Uma vez que a ponte esteja rodando, cada iMessage enviada ao seu Apple ID se torna uma interface de comando para o seu sandbox HappyCapy:
- Executar tarefas remotamente — envie uma tarefa do seu iPhone, receba de volta um resultado totalmente executado com saída
- Solicitar arquivos — peça um relatório em PDF, uma imagem gerada ou um script, e receba-o
- Buscar e resumir — peça ao agente para buscar na web e retornar um resumo estruturado
- Acionar mais de 300.000 Skills — todas as Skills na biblioteca do HappyCapy são acessíveis pelo Messages.app
- Executar bash no seu sandbox —
run ls /var/logexecuta no seu ambiente Linux HappyCapy e retorna a saída - Histórico por contato — cada Apple ID ou número de telefone tem sua própria thread de conversa; o contexto é mantido entre mensagens
- Funciona em qualquer dispositivo Apple — iPhone, iPad, Mac, Apple Watch — qualquer coisa que envie iMessages alcança o bot
Prós
- Experiência Apple nativa — as respostas aparecem na thread padrão do Messages.app; os destinatários não precisam instalar nada
- Nenhum aplicativo de terceiros no dispositivo do destinatário — o bot se comunica através da infraestrutura existente do iMessage
- Funciona com qualquer Apple ID — qualquer contato que consiga te enviar iMessage pode interagir com o bot
- Criptografia de ponta a ponta — o BlueBubbles não quebra a criptografia da Apple; ele lê as mensagens depois que elas são descriptografadas no seu Mac
- Gratuito e open-source — o BlueBubbles é licenciado sob MIT; não há taxas de assinatura
- Arquitetura validada pelo Hermes — a mesma stack que alimenta um projeto de agente em produção com 188.000 estrelas
- Capacidade completa de agente — o
claude --printdá ao bot acesso a bash, busca na web, operações em arquivos e mais de 300.000 Skills
Casos de Uso Reais
Desenvolvedor no iPhone. Você está longe do seu laptop e precisa verificar se um cron job rodou, acompanhar um arquivo de log ou reiniciar um serviço no seu sandbox HappyCapy. Você envia o comando pelo Messages.app no seu iPhone. A ponte o executa e retorna a saída como resposta. Sem cliente SSH, sem VPN, sem troca de contexto.
Residência só com Apple. Seu parceiro, pais ou colegas de casa usam apenas iMessages. Em vez de pedir que instalem o Telegram ou aprendam uma nova interface, você aponta o bot para o seu Apple ID existente. Todo mundo interage pelo aplicativo que já está no dispositivo deles.
Proprietário de negócio com clientes no iMessage. Você se comunica com clientes pelo iMessage — é o que eles usam, e migrá-los para outra plataforma não é realista. Com a ponte rodando, você pode pedir ao agente para resumir uma thread longa, redigir uma resposta na sua voz, consultar o histórico de pedidos de um cliente ou puxar um relatório. A IA permanece no canal onde o relacionamento já existe.
Pesquisador com um Mac. Você mantém um Mac ligado na sua mesa. Você quer um agente de IA sempre acessível — do seu iPhone durante o trajeto, do seu iPad em uma reunião, do Mac de um colega em uma emergência. O iMessage já é sincronizado em todos os dispositivos Apple que você possui. O bot herda esse alcance automaticamente.
A Exigência do Mac — Avaliação Honesta
A configuração exige um Mac com o BlueBubbles instalado e em execução, conectado ao HappyCapy via capy-bridge. O Mac precisa estar acordado e online para que a ponte funcione. Se ele entrar em suspensão, o bot fica offline.
Essa é uma restrição real. Se você não tem um Mac, ou se o seu Mac é um laptop que você carrega e fecha regularmente, o iMessage é o canal errado para você. As integrações do HappyCapy com Telegram e Slack funcionam em infraestrutura totalmente nativa Linux, sem dependência de hardware.
Para quem já mantém um Mac sempre ligado — um Mac Mini embaixo da TV, um Mac Studio em um home office, um MacBook antigo conectado na tomada em uma prateleira — a configuração é feita uma única vez e depois é totalmente automática. O BlueBubbles inicia no login. O daemon do capy-bridge inicia no login. O Mac continua rodando, e o bot também.
Se você está considerando um hardware dedicado para esse propósito, o Mac Mini M4 de 2026, modelo base (US$ 799), é a opção mais prática. Ele consome cerca de 6–10 watts em repouso, suporta operação 24/7 sem ruído de ventoinha e cabe em um espaço menor que um livro de bolso. Para uma análise completa de configurações de Mac Mini como servidor de IA, veja Mac Mini as an AI Server in 2026.
Como Configurar
A configuração completa leva aproximadamente 10 minutos:
- Baixe o BlueBubbles em bluebubbles.app — gratuito, licenciado sob MIT, open-source
- Execute o assistente de configuração — faça login com seu Apple ID e conceda as permissões de Acessibilidade + Acesso Total ao Disco
- Anote a URL e a senha do seu BlueBubbles na tela de configurações do BlueBubbles
- Instale o capy-bridge — execute
bash /app/export-port.sh 8766no HappyCapy para obter sua URL de webhook, depois execute a skill/happycapy-imessageno HappyCapy - Complete o assistente do HappyCapy — cole a URL, a senha e a URL de webhook do seu BlueBubbles; a ponte se registra automaticamente
- Teste — envie um iMessage de outro dispositivo; você deve 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 manter meu Mac ligado o tempo todo? Sim, para disponibilidade 24/7. O Mac precisa estar acordado e online para que o BlueBubbles e o capy-bridge recebam as mensagens. Se você quiser que o bot fique disponível o tempo todo, use um hardware que possa ficar sempre ligado — um Mac Mini ou Mac Studio é ideal. Ative "Prevent display sleep" nas configurações do BlueBubbles e desative a suspensão no Economizador de Energia do macOS (modo Adaptador de Energia).
Isso funciona com SMS também, ou só com iMessage? O BlueBubbles suporta tanto iMessage (bolhas azuis) quanto SMS (bolhas verdes) se o seu Mac tiver um iPhone conectado e o Personal Hotspot configurado para habilitar o encaminhamento de SMS. Para a maioria das configurações, usar apenas iMessage é mais simples e confiável.
A Apple consegue ver minhas mensagens através do BlueBubbles? Não. O BlueBubbles não quebra a criptografia de ponta a ponta da Apple. As mensagens são descriptografadas pelo macOS na sua máquina local, como sempre acontece, e então o BlueBubbles as lê a partir desse estado local já descriptografado. Os servidores da Apple nunca veem o conteúdo em texto simples — o mesmo que ao usar o Messages.app normalmente.
O BlueBubbles é gratuito? Sim. O BlueBubbles é licenciado sob MIT e gratuito para uso. Não há taxas de assinatura. O aplicativo servidor para Mac, o código-fonte e a documentação estão todos disponíveis publicamente em bluebubbles.app.
O que acontece se meu Mac entrar em suspensão?
A ponte fica offline. Mensagens enviadas enquanto o Mac está em suspensão não são processadas e não são respondidas retroativamente quando o Mac desperta. Para evitar isso: ative "Prevent display sleep" no BlueBubbles, desative a suspensão do sistema no Economizador de Energia do macOS para uso com Adaptador de Energia, ou execute caffeinate -di & em um terminal. Para configurações sempre ativas, Macs de mesa (Mini, Studio, Pro) são preferíveis a laptops.
Várias pessoas podem enviar mensagens ao bot a partir de Apple IDs diferentes? Sim. A ponte armazena um histórico de conversa separado por identificador de remetente. Cada Apple ID ou número de telefone tem sua própria janela de contexto. Você pode configurar uma lista de permissões (apenas identificadores específicos) ou deixá-la aberta para todos os iMessages recebidos.
Isso viola os termos de serviço da Apple? O BlueBubbles está em uma zona cinzenta: a Apple não aprovou explicitamente pontes de terceiros para o iMessage, mas também não tomou nenhuma ação contra o BlueBubbles nos mais de quatro anos em que ele está em operação. O projeto lê mensagens do seu próprio Mac, sob o seu próprio Apple ID, da mesma forma que qualquer processo com Acesso Total ao Disco poderia fazer. Usá-lo para sua própria automação — não para envio comercial em massa ou spam — é consistente com a forma como dezenas de milhares de desenvolvedores o utilizam. O projeto Hermes Agent inclui a integração com o BlueBubbles em sua configuração padrão a partir de 2026.
Considerações Finais
Dos quatro canais de mensagens que o HappyCapy suporta — Telegram, Slack, WhatsApp e iMessage — o iMessage é o mais exigente tecnicamente para configurar. Ele requer um Mac, um servidor BlueBubbles em execução e uma conexão persistente entre o seu hardware e o seu sandbox HappyCapy. São mais peças móveis do que os demais.
Para usuários Apple que já vivem nesse ecossistema, também é o resultado mais fluido: um agente de IA completo que responde pelo aplicativo Messages que seus contatos usam todos os dias, sem novos aplicativos para instalar e sem novas contas para criar. A arquitetura é comprovada — a mesma stack por trás das 188.000 estrelas do Hermes Agent — e o HappyCapy a envolve em uma skill de um clique.
Se você tem um Mac que fica sempre ligado, a configuração vale os 10 minutos.
