Por que preciso de um Mac para o BlueBubbles?

O iMessage é um serviço exclusivo da Apple que requer macOS e um Apple ID. O BlueBubbles roda no Mac para acessar diretamente o framework Messages. Não há como se conectar ao iMessage sem um Mac — um Mac Mini dedicado ou uma VM macOS é a configuração típica para operação permanente.

Qual é a diferença entre o BlueBubbles e o antigo canal iMessage?

O BlueBubbles usa uma API REST moderna com suporte a webhook, oferecendo recursos ricos como reações tapback, edição de mensagens, efeitos e gerenciamento de grupos. O antigo canal iMessage (imsg CLI) está obsoleto e tem funcionalidade limitada. O BlueBubbles é a abordagem recomendada para todas as novas integrações iMessage.

O BlueBubbles requer a API privada?

Mensagens de texto básicas funcionam sem a API privada, mas recursos avançados como reações tapback, edição de mensagens, cancelamento, gerenciamento de grupos e envio de efeitos requerem a habilitação da API privada do BlueBubbles. Recomenda-se habilitá-la para o conjunto completo de recursos.

Posso usar o BlueBubbles com múltiplos Apple IDs?

Cada instância do servidor BlueBubbles está vinculada a um Apple ID. Se precisar conectar múltiplos Apple IDs, precisará de instâncias Mac separadas executando BlueBubbles, cada uma configurada como uma conta diferente no OpenClaw.

O que acontece se meu Mac ficar offline?

Se o Mac executando BlueBubbles ficar offline, os iMessages recebidos serão enfileirados nos servidores da Apple. Quando o Mac voltar a ficar online, as mensagens enfileiradas serão entregues. No entanto, eventos de webhook durante o tempo de inatividade são perdidos — o Gateway não receberá essas notificações. Mensagens durante a inatividade aparecerão no Messages.app mas não acionarão respostas de IA.

Como funcionam os códigos de pareamento?

Quando dmPolicy é 'pairing' (padrão), remetentes desconhecidos recebem um código de pareamento aleatório ao enviar sua primeira mensagem. O código expira após 1 hora. Aprove com 'openclaw pairing approve bluebubbles ' no seu terminal. Uma vez aprovado, o remetente pode conversar livremente sem verificação adicional.

OpenClaw GuideOpenClaw

Começar

Canal BlueBubbles do OpenClaw

Mensagens

Médio

Conecte o OpenClaw ao iMessage através da API REST do BlueBubbles. Esta integração transforma seu Mac em um gateway iMessage — instale o aplicativo servidor BlueBubbles, habilite a API Web, e seu assistente de IA poderá enviar e receber mensagens iMessage, reações tapback e anexos de mídia. BlueBubbles é o canal iMessage recomendado, substituindo a abordagem legada imsg CLI.

Info rápida

DificuldadeMédio

CategoriaMensagens

Recursos suportados4 / 6

BlueBubbles Recursos suportados

Mensagens de texto

Suportado

Mídia e arquivos

Suportado

Reações

Suportado

Threads

Não suportado

Mensagens de voz

Não suportado

Chat em grupo

Suportado

BlueBubbles Pré-requisitos

Um Mac executando macOS High Sierra (10.13) ou posterior (Ventura 13+ recomendado para funcionalidade completa; Tahoe 26 suportado com limitações)
Aplicativo servidor BlueBubbles instalado a partir de bluebubbles.app
API Web habilitada com senha definida na configuração do BlueBubbles
OpenClaw Gateway em execução e configurado

BlueBubbles Configuração rápida

Instalar o servidor BlueBubbles no seu Mac

Baixe e instale o aplicativo servidor BlueBubbles de bluebubbles.app/install. Inicie o aplicativo, faça login com seu Apple ID e complete a configuração inicial. Certifique-se de que o iMessage esteja funcionando corretamente no Mac.

Habilitar a API Web

Nas configurações do servidor BlueBubbles, habilite a API Web/REST e defina uma senha forte. Anote a URL do servidor (ex: http://localhost:1234) — você precisará dela para a configuração do OpenClaw.

Adicionar configuração do canal BlueBubbles

Execute 'openclaw onboard' e selecione BlueBubbles, ou adicione manualmente a configuração do canal em ~/.openclaw/openclaw.json com seu serverUrl e password. Configure o webhookPath se necessário.

Configurar webhook e testar

Aponte os webhooks do BlueBubbles para seu Gateway: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>. Inicie o Gateway e envie um iMessage de teste para verificar a conexão. Se usar a política de pareamento, aprove o remetente com 'openclaw pairing approve bluebubbles <code>'.

BlueBubbles Exemplo de configuração

config.json

{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://localhost:1234",
      "password": "YOUR_BLUEBUBBLES_PASSWORD",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "pairing"
    }
  }
}

BlueBubbles Documentação Detalhada

Visão geral da arquitetura

O OpenClaw se conecta ao iMessage através do aplicativo servidor BlueBubbles executando em um Mac. O BlueBubbles expõe uma API REST que o Gateway usa para enviar mensagens, reações e gerenciar chats. Mensagens recebidas são entregues via webhooks — o BlueBubbles envia eventos de novas mensagens para o endpoint webhook do Gateway. O fluxo da arquitetura é: iMessage chega no Mac → Servidor BlueBubbles → Push webhook para o Gateway → OpenClaw processa com IA → Chamada API REST para BlueBubbles → iMessage entregue. Esta abordagem requer um Mac permanentemente online (físico ou VM), pois o iMessage é um serviço exclusivo da Apple. O Mac atua como ponte entre o ecossistema de mensagens da Apple e seu assistente OpenClaw.

Um Mac Mini dedicado ou uma VM macOS é ideal para executar o BlueBubbles como gateway iMessage permanente.

O BlueBubbles suporta a API privada para recursos avançados como reações tapback, edição de mensagens e cancelamento — certifique-se de habilitá-la nas configurações do BlueBubbles.

Configuração do servidor BlueBubbles

Configurar o BlueBubbles requer a instalação do aplicativo servidor no seu Mac: 1. Baixe o BlueBubbles de bluebubbles.app/install e inicie o aplicativo. 2. Faça login com seu Apple ID e verifique se o iMessage funciona no Mac. 3. Habilite a API Web/REST nas configurações do BlueBubbles. 4. Defina uma senha de API forte — esta senha autentica todas as requisições de API e entregas de webhook. 5. Anote a URL do servidor exibida no aplicativo (padrão: http://localhost:1234). 6. Opcional: habilite a API privada para recursos avançados (reações, edição, cancelamento). O servidor deve permanecer em execução para que a ponte iMessage funcione. Configure o BlueBubbles para iniciar automaticamente para maior confiabilidade.

webhook URL

# Formato de URL webhook para seu Gateway
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD

Mantenha sua senha da API BlueBubbles segura. Se o servidor estiver exposto na rede, habilite HTTPS no BlueBubbles e use regras de firewall para restringir o acesso. Proxies reversos no mesmo host ignoram a autenticação por senha — adicione autenticação no nível do proxy e configure gateway.trustedProxies.

Políticas de DM

As políticas de DM (Mensagem Direta) controlam quem pode interagir com seu assistente de IA via iMessage. O OpenClaw suporta quatro políticas: • pairing (padrão) — Remetentes desconhecidos recebem um código de pareamento com tempo limitado (expira após 1 hora). Aprove ou rejeite com 'openclaw pairing approve bluebubbles <CODE>'. Uma vez aprovado, podem conversar livremente. • allowlist — Apenas números de telefone e endereços de e-mail listados em allowFrom podem enviar mensagens. Os demais são silenciosamente ignorados. Formato E.164 suportado para números de telefone. • open — Qualquer pessoa que envie uma mensagem recebe resposta. Use com cautela. • disabled — O processamento de DM está completamente desativado.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "user@example.com"]
    }
  }
}

O campo allowFrom aceita tanto números de telefone (formato E.164, ex: +15551234567) quanto endereços de e-mail para roteamento iMessage.

Gerenciamento de chats em grupo

O OpenClaw suporta chats em grupo do iMessage através do BlueBubbles com controle de acesso flexível: • groupPolicy controla quem pode acionar o bot em chats de grupo: - open — Qualquer membro do grupo pode interagir - allowlist — Apenas endereços de groupAllowFrom podem acionar - disabled (padrão) — Mensagens de grupo são ignoradas • Detecção de menção — Quando requireMention é true (padrão para grupos), o bot só responde quando mencionado. Padrões de menção são configurados em agents.list[].groupChat.mentionPatterns. • Configuração por grupo — Use o objeto groups para definir regras requireMention diferentes para chats específicos.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "iMessage;+;chat123456": {
          "requireMention": false
        }
      }
    }
  }
}

Ações e efeitos do iMessage

O BlueBubbles expõe um rico conjunto de ações nativas do iMessage através da API privada. Cada ação pode ser ativada/desativada individualmente: • reactions — Enviar e receber reações tapback (coração, curtir, não curtir, riso, ênfase, pergunta) • edit — Modificar mensagens enviadas (requer macOS 13+; atualmente quebrado no macOS Tahoe) • unsend — Cancelar mensagens enviadas (macOS 13+) • reply — Threading de mensagens por GUID • sendWithEffect — Enviar mensagens com efeitos de bolha (slam, alto, suave, tinta invisível, etc.) • sendAttachment — Enviar arquivos de mídia e memos de voz (formato MP3/CAF para voz; BlueBubbles lida com conversão MP3→CAF) Ações de gerenciamento de grupo: • renameGroup — Renomear chats de grupo • setGroupIcon — Definir foto do grupo (instável no macOS Tahoe) • addParticipant / removeParticipant / leaveGroup — Gerenciar membros do grupo

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "actions": {
        "reactions": true,
        "edit": true,
        "unsend": true,
        "reply": true,
        "sendWithEffect": true,
        "sendAttachment": true
      }
    }
  }
}

No macOS Tahoe (26), a ação edit está atualmente quebrada devido a mudanças na API privada, e setGroupIcon não é confiável (a API retorna sucesso mas o ícone não sincroniza). Se estiver executando Tahoe, desative essas ações manualmente.

Entrega e fragmentação de mensagens

O OpenClaw oferece entrega configurável por fragmentos para respostas longas de IA: • textChunkLimit — Caracteres máximos por fragmento de mensagem (padrão: 4000). O iMessage não tem um limite estrito, mas mensagens muito longas podem não ser exibidas corretamente em todos os dispositivos. • chunkMode — Controla o método de fragmentação do texto: - length (padrão) — Divisão forçada em textChunkLimit caracteres - newline — Divisão nos limites de parágrafo para leitura mais natural • blockStreaming — Quando true, as respostas são enviadas em blocos durante a geração, sem esperar a resposta completa. Confirmações de leitura são enviadas por padrão para manter um fluxo de conversa natural. Indicadores de digitação são enviados automaticamente antes e durante a geração de respostas de IA.

openclaw.json

{
  "channels": {
    "bluebubbles": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": false,
      "sendReadReceipts": true
    }
  }
}

Mídia e anexos

O BlueBubbles suporta envio e recebimento de mídia através do iMessage: • Anexos recebidos são baixados e armazenados em cache automaticamente pelo Gateway. O tamanho máximo de arquivo recebido é controlado por mediaMaxMb (padrão: 8 MB). • Memos de voz podem ser enviados com a ação sendAttachment usando asVoice: true. O BlueBubbles converte MP3 para CAF automaticamente para reprodução nativa de memos de voz do iMessage. • Mídia de saída é enviada via ação sendAttachment com parâmetros buffer, filename e tipo mime opcional.

Para memos de voz, use formato MP3 ou CAF. O BlueBubbles converterá MP3 para CAF automaticamente para reprodução nativa no iMessage.

Ajuste mediaMaxMb se precisar lidar com anexos maiores — o padrão de 8 MB cobre a maioria das fotos e vídeos curtos.

Gerenciamento de ID de mensagem

O BlueBubbles usa dois tipos de identificadores de mensagem: • IDs curtos — Tokens temporários em memória (como 1, 2, 3). Rápidos mas efêmeros. Expiram ao reiniciar o Gateway ou na limpeza do cache. • IDs completos — Identificadores persistentes do provedor (MessageSidFull, ReplyToIdFull). Sobrevivem a reinicializações e são estáveis para referências de longo prazo. Ambos os formatos são aceitos nos parâmetros de ação (messageId, replyTo, etc.). Para automações duráveis que precisam referenciar mensagens entre reinicializações, sempre use IDs completos.

Use IDs de mensagem completos para qualquer automação que precise sobreviver a reinicializações do Gateway. IDs curtos são convenientes para uso interativo mas se tornam inválidos após reinicialização.

Endereçamento e roteamento

O BlueBubbles suporta múltiplos formatos de endereçamento para entrega de mensagens. Ordem de roteamento preferida por estabilidade: 1. chat_guid — Formato mais estável: chat_guid:iMessage;-;+15555550123 2. chat_id — Identificador numérico do chat: chat_id:123 3. chat_identifier — String de identificador do chat 4. Endereços diretos — Número de telefone (+15555550123) ou e-mail (user@example.com) Ao enviar para um endereço direto sem chat existente, o BlueBubbles cria automaticamente um novo DM via POST /api/v1/chat/new (requer API privada).

Use o formato chat_guid em automações para o roteamento de mensagens mais confiável.

Segurança e autenticação webhook

O BlueBubbles autentica as entregas de webhook com a senha configurada. O Gateway verifica se o parâmetro de senha (via query string ou cabeçalho) corresponde à configuração channels.bluebubbles.password. Considerações de segurança: • Requisições localhost são automaticamente confiáveis e ignoram a verificação de senha. • Proxies reversos no mesmo host também ignoram a verificação — se usar um proxy reverso na mesma máquina, adicione autenticação no nível do proxy e configure gateway.trustedProxies. • Habilite HTTPS no servidor BlueBubbles para criptografar as comunicações. • Use regras de firewall para restringir o acesso externo à porta da API do BlueBubbles. Para implantações em produção, sempre use HTTPS e garanta que o endpoint webhook não seja acessível publicamente sem autenticação.

Proxies reversos no mesmo host ignoram a autenticação por senha do BlueBubbles. Ao usar um proxy reverso, sempre configure autenticação no nível do proxy e defina gateway.trustedProxies.

Manter Messages.app ativo (Headless/VM)

Se executar o BlueBubbles em um Mac headless ou VM, o Messages.app pode entrar em modo ocioso e parar de processar mensagens. A solução é configurar um LaunchAgent que execute um AppleScript a cada 5 minutos para tocar a interface de scripting do Messages. Este script de manutenção ignora com segurança erros transitórios e não rouba o foco de outros aplicativos. É essencial para a operação confiável não assistida da ponte iMessage. Configure um plist de macOS LaunchAgent para executar o AppleScript periodicamente e manter a responsividade do Messages.app.

Isso só é necessário para ambientes headless/VM. Se seu Mac tem uma sessão de desktop ativa com Messages.app visível, a manutenção não é necessária.

Use launchctl para gerenciar o LaunchAgent — carregue na inicialização para operação completamente não assistida.

BlueBubbles Referência de Configuração

Key	Type	Default	Description
enabled	boolean	false	Ativar ou desativar o canal BlueBubbles
serverUrl	string	""	URL base da API REST do BlueBubbles (ex: http://localhost:1234)
password	string	""	Senha da API BlueBubbles para autenticação
webhookPath	string	"/bluebubbles-webhook"	Caminho do endpoint webhook para receber mensagens
dmPolicy	string	"pairing"	Controla quem pode enviar DM ao bot. Opções: pairing, allowlist, open, disabled
allowFrom	string[]	[]	Números de telefone e e-mails autorizados a enviar mensagens (formato E.164 para telefones)
groupPolicy	string	"allowlist"	Política de chat em grupo. Opções: open, allowlist, disabled
groupAllowFrom	string[]	[]	Endereços de remetentes autorizados a acionar o bot em chats de grupo
sendReadReceipts	boolean	true	Enviar confirmação de leitura ao processar mensagens
blockStreaming	boolean	false	Habilitar streaming de resposta por blocos em vez de esperar a resposta completa
textChunkLimit	number	4000	Caracteres máximos por fragmento de mensagem de texto de saída
chunkMode	string	"length"	Modo de fragmentação de texto. Opções: length (por tamanho), newline (por parágrafo)
mediaMaxMb	number	8	Tamanho máximo de arquivo de anexos recebidos em megabytes
historyLimit	number	-	Máximo de mensagens de grupo incluídas como contexto de IA (0 para desativar)
dmHistoryLimit	number	-	Limite de histórico de conversa DM para contexto de IA
actions.reactions	boolean	true	Habilitar reações tapback (requer API privada)
actions.edit	boolean	true	Habilitar edição de mensagens (requer macOS 13+; quebrado no Tahoe)
actions.unsend	boolean	true	Habilitar cancelamento de mensagens (requer macOS 13+)
actions.reply	boolean	true	Habilitar threading de mensagens por GUID
actions.sendWithEffect	boolean	true	Habilitar efeitos de bolha iMessage (slam, alto, suave, etc.)
actions.sendAttachment	boolean	true	Habilitar entrega de mídia e memos de voz

enabled

Type: booleanDefault: false

Ativar ou desativar o canal BlueBubbles

serverUrl

Type: stringDefault: ""

URL base da API REST do BlueBubbles (ex: http://localhost:1234)

password

Type: stringDefault: ""

Senha da API BlueBubbles para autenticação

webhookPath

Type: stringDefault: "/bluebubbles-webhook"

Caminho do endpoint webhook para receber mensagens

dmPolicy

Type: stringDefault: "pairing"

Controla quem pode enviar DM ao bot. Opções: pairing, allowlist, open, disabled

allowFrom

Type: string[]Default: []

Números de telefone e e-mails autorizados a enviar mensagens (formato E.164 para telefones)

groupPolicy

Type: stringDefault: "allowlist"

Política de chat em grupo. Opções: open, allowlist, disabled

groupAllowFrom

Type: string[]Default: []

Endereços de remetentes autorizados a acionar o bot em chats de grupo

sendReadReceipts

Type: booleanDefault: true

Enviar confirmação de leitura ao processar mensagens

blockStreaming

Type: booleanDefault: false

Habilitar streaming de resposta por blocos em vez de esperar a resposta completa

textChunkLimit

Type: numberDefault: 4000

Caracteres máximos por fragmento de mensagem de texto de saída

chunkMode

Type: stringDefault: "length"

Modo de fragmentação de texto. Opções: length (por tamanho), newline (por parágrafo)

mediaMaxMb

Type: numberDefault: 8

Tamanho máximo de arquivo de anexos recebidos em megabytes

historyLimit

Type: numberDefault: -

Máximo de mensagens de grupo incluídas como contexto de IA (0 para desativar)

dmHistoryLimit

Type: numberDefault: -

Limite de histórico de conversa DM para contexto de IA

actions.reactions

Type: booleanDefault: true

Habilitar reações tapback (requer API privada)

actions.edit

Type: booleanDefault: true

Habilitar edição de mensagens (requer macOS 13+; quebrado no Tahoe)

actions.unsend

Type: booleanDefault: true

Habilitar cancelamento de mensagens (requer macOS 13+)

actions.reply

Type: booleanDefault: true

Habilitar threading de mensagens por GUID

actions.sendWithEffect

Type: booleanDefault: true

Habilitar efeitos de bolha iMessage (slam, alto, suave, etc.)

actions.sendAttachment

Type: booleanDefault: true

Habilitar entrega de mídia e memos de voz

BlueBubbles Perguntas Frequentes

BlueBubbles Solução de Problemas

Webhook não recebe mensagens

A URL do webhook no BlueBubbles não corresponde ao endpoint do Gateway, ou o parâmetro de senha está incorreto.

Verifique se a URL do webhook está definida como https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD. Confirme que channels.bluebubbles.webhookPath corresponde ao caminho na URL. Verifique os logs do Gateway para tentativas de webhook recebidas.

Gateway conectado mas ações falham (reações, edição, cancelamento)

A API privada do BlueBubbles não está habilitada, ou a versão do servidor não suporta os endpoints de API necessários.

Habilite a API privada nas configurações do servidor BlueBubbles. Atualize o BlueBubbles para a versão mais recente. Se ações específicas falharem no macOS Tahoe, desative-as individualmente: channels.bluebubbles.actions.edit=false.

Messages.app para de responder no Mac headless

O Messages.app entra em modo ocioso em configurações headless/VM e para de processar a interface de scripting.

Configure o LaunchAgent de manutenção AppleScript para tocar a interface de scripting do Messages a cada 5 minutos. Garanta que o LaunchAgent esteja carregado via launchctl e execute na inicialização.

Mensagens do bot não são iMessages (bolhas verdes)

O número de telefone ou e-mail do destinatário não está registrado no iMessage, ou o Apple ID no Mac tem o iMessage desativado.

Verifique se o iMessage está habilitado nas preferências do Messages.app no Mac. Confirme que o destinatário usa um dispositivo Apple com iMessage habilitado. Bolhas verdes indicam fallback para SMS, que o BlueBubbles pode não suportar dependendo da configuração.

Ação de edição falha no macOS Tahoe

Problema conhecido — macOS Tahoe (26) quebrou o endpoint da API privada para edição de mensagens.

Desative a ação de edição: defina channels.bluebubbles.actions.edit como false. Esta é uma limitação conhecida do BlueBubbles no Tahoe. Acompanhe os lançamentos do BlueBubbles para uma correção.

Ver documentação completa Voltar para todos os canais