BlueBubbles (iMessage)

Conecte o Hermes ao Apple iMessage pelo BlueBubbles — um servidor macOS gratuito e de código aberto que faz a ponte entre o iMessage e qualquer dispositivo.

Pré-requisitos

• Um Mac (sempre ligado) rodando o BlueBubbles Server
• Apple ID conectado no Messages.app desse Mac
• BlueBubbles Server v1.0.0+ (os webhooks exigem essa versão)
• Conectividade de rede entre o Hermes e o servidor BlueBubbles

Configuração

1. Instale o BlueBubbles Server

Baixe e instale em bluebubbles.app. Conclua o assistente de configuração — entre com seu Apple ID e escolha um método de conexão (rede local, Ngrok, Cloudflare ou DNS dinâmico).

2. Pegue a URL e a senha do servidor

No BlueBubbles Server → Settings → API, anote:

• Server URL (por exemplo, http://192.168.1.10:1234)
• Server Password

3. Configure o Hermes

Rode o assistente de configuração:

hermes gateway setup

Escolha BlueBubbles (iMessage) e informe a URL e a senha do seu servidor.

Ou defina as variáveis de ambiente direto em ~/.hermes/.env:

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=senha-do-seu-servidor

Opcional: exigir menção em conversas de grupo

Por padrão, o Hermes responde a toda mensagem direta ou de grupo autorizada no BlueBubbles/iMessage. Para tornar as conversas de grupo opt-in, ative o controle por menção:

platforms:
  bluebubbles:
    enabled: true
    extra:
      require_mention: true

Com require_mention: true, as mensagens diretas continuam funcionando normalmente, mas as mensagens de grupo são ignoradas a menos que casem com um padrão de menção. Se você não configurar padrões próprios, o Hermes usa padrões conservadores para as variantes Hermes e @Hermes agent.

Para um nome de agente personalizado, defina padrões de regex:

platforms:
  bluebubbles:
    extra:
      require_mention: true
      mention_patterns:
        - '(?<![\w@])@?amos\b[,:\-]?'

4. Autorize usuários

Escolha uma das abordagens:

Pareamento por mensagem direta (recomendado): Quando alguém manda mensagem para o seu iMessage, o Hermes envia automaticamente um código de pareamento. Aprove com:

hermes pairing approve bluebubbles <CODIGO>

Use hermes pairing list para ver os códigos pendentes e os usuários aprovados.

Pré-autorizar usuários específicos (em ~/.hermes/.env):

BLUEBUBBLES_ALLOWED_USERS=usuario@icloud.com,+5511999998888

Acesso aberto (em ~/.hermes/.env):

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. Suba o gateway

hermes gateway run

O Hermes vai se conectar ao seu servidor BlueBubbles, registrar um webhook e começar a escutar as mensagens do iMessage.

Como funciona

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → API REST do BlueBubbles → Messages.app → iMessage

• Entrada: o BlueBubbles envia eventos de webhook para um listener local quando chegam mensagens novas. Sem polling — entrega instantânea.
• Saída: o Hermes envia mensagens pela API REST do BlueBubbles.
• Mídia: imagens, mensagens de voz, vídeos e documentos funcionam nas duas direções. Os anexos recebidos são baixados e guardados em cache local para o agente processar.

Variáveis de ambiente

Variável	Obrigatória	Padrão	Descrição
BLUEBUBBLES_SERVER_URL	Sim	—	URL do servidor BlueBubbles
BLUEBUBBLES_PASSWORD	Sim	—	Senha do servidor
BLUEBUBBLES_WEBHOOK_HOST	Não	127.0.0.1	Endereço de bind do listener de webhook
BLUEBUBBLES_WEBHOOK_PORT	Não	8645	Porta do listener de webhook
BLUEBUBBLES_WEBHOOK_PATH	Não	/bluebubbles-webhook	Caminho da URL do webhook
BLUEBUBBLES_HOME_CHANNEL	Não	—	Telefone/e-mail para entrega do cron
BLUEBUBBLES_ALLOWED_USERS	Não	—	Usuários autorizados, separados por vírgula
BLUEBUBBLES_ALLOW_ALL_USERS	Não	false	Libera todos os usuários
BLUEBUBBLES_REQUIRE_MENTION	Não	false	Exige um padrão de menção antes de responder em conversas de grupo
BLUEBUBBLES_MENTION_PATTERNS	Não	Palavras de ativação do Hermes	Array JSON, lista separada por quebra de linha ou por vírgula com os padrões de regex de menção em grupo

Marcar mensagens como lidas automaticamente é controlado pela chave send_read_receipts dentro de platforms.bluebubbles.extra no ~/.hermes/config.yaml (padrão: true). Não existe variável de ambiente correspondente.

Recursos

Mensagens de texto

Envie e receba iMessages. O Markdown é removido automaticamente para uma entrega limpa em texto puro.

Mídia rica

• Imagens: as fotos aparecem nativamente na conversa do iMessage
• Mensagens de voz: arquivos de áudio enviados como mensagens de voz do iMessage
• Vídeos: anexos de vídeo
• Documentos: arquivos enviados como anexos do iMessage

Reações Tapback

Reações de amor, curtida, descurtida, risada, ênfase e dúvida. Exige o helper da Private API do BlueBubbles.

Indicadores de digitação

Mostra "digitando..." na conversa do iMessage enquanto o agente processa. Exige a Private API.

Confirmações de leitura

Marca as mensagens como lidas automaticamente depois de processar. Exige a Private API.

Endereçamento de conversas

Você pode endereçar conversas por e-mail ou telefone — o Hermes resolve tudo para os GUIDs de conversa do BlueBubbles sozinho. Não precisa usar o formato bruto de GUID.

Private API

Alguns recursos exigem o helper da Private API do BlueBubbles:

• Reações Tapback
• Indicadores de digitação
• Confirmações de leitura
• Criar conversas novas por endereço

Sem a Private API, as mensagens de texto básicas e a mídia continuam funcionando.

Resolução de problemas

"Cannot reach server"

• Confira se a URL do servidor está correta e se o Mac está ligado
• Verifique se o BlueBubbles Server está rodando
• Garanta a conectividade de rede (firewall, encaminhamento de porta)

As mensagens não chegam

• Confira se o webhook está registrado em BlueBubbles Server → Settings → API → Webhooks
• Verifique se a URL do webhook é alcançável a partir do Mac
• Veja hermes logs gateway em busca de erros de webhook (ou hermes logs -f para acompanhar em tempo real)

"Private API helper not connected"

• Instale o helper da Private API: docs.bluebubbles.app
• As mensagens básicas funcionam sem ele — só as reações, a digitação e as confirmações de leitura precisam dele

---