BlueBubbles (macOS REST)

Stato: plugin incluso che comunica con il server BlueBubbles macOS tramite HTTP. Consigliato per l’integrazione iMessage grazie alla sua API piu ricca e al setup piu semplice rispetto al canale imsg legacy.

Panoramica

• Funziona su macOS tramite l’app helper BlueBubbles (bluebubbles.app).
• Consigliato/testato: macOS Sequoia (15). macOS Tahoe (26) funziona; la modifica e attualmente rotta su Tahoe, e gli aggiornamenti delle icone di gruppo potrebbero riportare successo ma non sincronizzarsi.
• OpenClaw comunica attraverso la sua API REST (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• I messaggi in ingresso arrivano via webhook; le risposte in uscita, gli indicatori di digitazione, le conferme di lettura e le tapback sono chiamate REST.
• Allegati e sticker vengono ingeriti come media in ingresso (e mostrati all’agent quando possibile).
• Pairing/allowlist funziona come gli altri canali (/channels/pairing ecc.) con channels.bluebubbles.allowFrom + codici di pairing.
• Le reazioni sono mostrate come eventi di sistema proprio come Slack/Telegram cosi gli agent possono “menzionarle” prima di rispondere.
• Funzionalita avanzate: modifica, annullamento invio, threading risposte, effetti messaggio, gestione gruppi.

Avvio rapido

1. Installa il server BlueBubbles sul tuo Mac (segui le istruzioni su bluebubbles.app/install).

2. Nella configurazione BlueBubbles, abilita l’API web e imposta una password.

3. Esegui openclaw onboard e seleziona BlueBubbles, oppure configura manualmente:

   {
     channels: {
       bluebubbles: {
         enabled: true,
         serverUrl: "http://192.168.1.100:1234",
         password: "example-password",
         webhookPath: "/bluebubbles-webhook",
       },
     },
   }

4. Punta i webhook BlueBubbles al tuo gateway (esempio: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).

5. Avvia il gateway; registrera l’handler webhook e iniziera il pairing.

Nota di sicurezza:

• Imposta sempre una password webhook.
• L’autenticazione webhook e sempre obbligatoria. OpenClaw rifiuta le richieste webhook BlueBubbles a meno che non includano una password/guid che corrisponde a channels.bluebubbles.password (ad esempio ?password=<password> o x-password), indipendentemente dalla topologia loopback/proxy.
• L’autenticazione della password e controllata prima di leggere/analizzare i body completi dei webhook.

Mantenere Messages.app attiva (setup VM / headless)

Alcuni setup macOS VM / always-on possono portare Messages.app a diventare “inattiva” (gli eventi in ingresso si fermano finche l’app non viene aperta/portata in primo piano). Un semplice workaround e stimolare Messages ogni 5 minuti usando un AppleScript + LaunchAgent.

1) Salva l’AppleScript

Salvalo come:

• ~/Scripts/poke-messages.scpt

Script di esempio (non-interattivo; non ruba il focus):

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

2) Installa un LaunchAgent

Salvalo come:

• ~/Library/LaunchAgents/com.user.poke-messages.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

Note:

• Questo viene eseguito ogni 300 secondi e al login.
• La prima esecuzione potrebbe attivare prompt Automazione di macOS (osascript -> Messages). Approvali nella stessa sessione utente che esegue il LaunchAgent.

Caricalo:

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

Onboarding

BlueBubbles e disponibile nel wizard di setup interattivo:

openclaw onboard

Il wizard chiede:

• URL del server (obbligatorio): indirizzo del server BlueBubbles (es. http://192.168.1.100:1234)
• Password (obbligatorio): password API dalle impostazioni del Server BlueBubbles
• Percorso webhook (opzionale): predefinito /bluebubbles-webhook
• Policy DM: pairing, allowlist, open o disabled
• Allow list: numeri di telefono, email o target di chat

Puoi anche aggiungere BlueBubbles via CLI:

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

Controllo degli accessi (DM + gruppi)

DM:

• Predefinito: channels.bluebubbles.dmPolicy = "pairing".
• I mittenti sconosciuti ricevono un codice di pairing; i messaggi sono ignorati fino all’approvazione (i codici scadono dopo 1 ora).
• Approvazione tramite:
  • openclaw pairing list bluebubbles
  • openclaw pairing approve bluebubbles <CODE>
• Il pairing e lo scambio token predefinito. Dettagli: Pairing

Gruppi:

• channels.bluebubbles.groupPolicy = open | allowlist | disabled (predefinito: allowlist).
• channels.bluebubbles.groupAllowFrom controlla chi puo attivare il bot nei gruppi quando allowlist e impostato.

Gating menzione (gruppi)

BlueBubbles supporta il gating menzione per le chat di gruppo, con comportamento simile a iMessage/WhatsApp:

• Usa agents.list[].groupChat.mentionPatterns (o messages.groupChat.mentionPatterns) per rilevare le menzioni.
• Quando requireMention e abilitato per un gruppo, l’agent risponde solo quando menzionato.
• I comandi di controllo da mittenti autorizzati bypassano il gating menzione.

Configurazione per gruppo:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // predefinito per tutti i gruppi
        "iMessage;-;chat123": { requireMention: false }, // sovrascrittura per gruppo specifico
      },
    },
  },
}

Gating comandi

• I comandi di controllo (es. /config, /model) richiedono autorizzazione.
• Usa allowFrom e groupAllowFrom per determinare l’autorizzazione ai comandi.
• I mittenti autorizzati possono eseguire comandi di controllo anche senza menzionare nei gruppi.

Digitazione + conferme di lettura

• Indicatori di digitazione: Inviati automaticamente prima e durante la generazione della risposta.
• Conferme di lettura: Controllate da channels.bluebubbles.sendReadReceipts (predefinito: true).
• Indicatori di digitazione: OpenClaw invia eventi di inizio digitazione; BlueBubbles cancella la digitazione automaticamente all’invio o al timeout (lo stop manuale via DELETE non e affidabile).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disabilita le conferme di lettura
    },
  },
}

Azioni avanzate

BlueBubbles supporta azioni avanzate sui messaggi quando abilitate nella configurazione:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapback (predefinito: true)
        edit: true, // modifica messaggi inviati (macOS 13+, rotto su macOS 26 Tahoe)
        unsend: true, // annulla invio messaggi (macOS 13+)
        reply: true, // threading risposte tramite GUID messaggio
        sendWithEffect: true, // effetti messaggio (slam, loud, ecc.)
        renameGroup: true, // rinomina chat di gruppo
        setGroupIcon: true, // imposta icona/foto chat di gruppo (instabile su macOS 26 Tahoe)
        addParticipant: true, // aggiungi partecipanti ai gruppi
        removeParticipant: true, // rimuovi partecipanti dai gruppi
        leaveGroup: true, // abbandona chat di gruppo
        sendAttachment: true, // invia allegati/media
      },
    },
  },
}

Azioni disponibili:

• react: Aggiungi/rimuovi reazioni tapback (messageId, emoji, remove)
• edit: Modifica un messaggio inviato (messageId, text)
• unsend: Annulla l’invio di un messaggio (messageId)
• reply: Rispondi a un messaggio specifico (messageId, text, to)
• sendWithEffect: Invia con effetto iMessage (text, to, effectId)
• renameGroup: Rinomina una chat di gruppo (chatGuid, displayName)
• setGroupIcon: Imposta l’icona/foto di una chat di gruppo (chatGuid, media) — instabile su macOS 26 Tahoe (l’API potrebbe restituire successo ma l’icona non si sincronizza).
• addParticipant: Aggiungi qualcuno a un gruppo (chatGuid, address)
• removeParticipant: Rimuovi qualcuno da un gruppo (chatGuid, address)
• leaveGroup: Abbandona una chat di gruppo (chatGuid)
• sendAttachment: Invia media/file (to, buffer, filename, asVoice)
  • Messaggi vocali: imposta asVoice: true con audio MP3 o CAF per inviare come messaggio vocale iMessage. BlueBubbles converte MP3 -> CAF quando invia messaggi vocali.

ID messaggio (brevi vs completi)

OpenClaw potrebbe mostrare ID messaggio brevi (es. 1, 2) per risparmiare token.

• MessageSid / ReplyToId possono essere ID brevi.
• MessageSidFull / ReplyToIdFull contengono gli ID completi del provider.
• Gli ID brevi sono in memoria; possono scadere al riavvio o all’evizione dalla cache.
• Le azioni accettano messageId breve o completo, ma gli ID brevi restituiranno errore se non piu disponibili.

Usa ID completi per automazioni durevoli e storage:

• Template: {{MessageSidFull}}, {{ReplyToIdFull}}
• Contesto: MessageSidFull / ReplyToIdFull nei payload in ingresso

Vedi Configurazione per le variabili template.

Streaming a blocchi

Controlla se le risposte vengono inviate come messaggio singolo o in streaming a blocchi:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // abilita lo streaming a blocchi (disattivato per impostazione predefinita)
    },
  },
}

Media + limiti

• Gli allegati in ingresso vengono scaricati e salvati nella cache media.
• Limite media via channels.bluebubbles.mediaMaxMb per media in ingresso e uscita (predefinito: 8 MB).
• Il testo in uscita e segmentato a channels.bluebubbles.textChunkLimit (predefinito: 4000 caratteri).

Riferimento configurazione

Configurazione completa: Configurazione

Opzioni del provider:

• channels.bluebubbles.enabled: Abilita/disabilita il canale.
• channels.bluebubbles.serverUrl: URL base API REST BlueBubbles.
• channels.bluebubbles.password: Password API.
• channels.bluebubbles.webhookPath: Percorso endpoint webhook (predefinito: /bluebubbles-webhook).
• channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (predefinito: pairing).
• channels.bluebubbles.allowFrom: Allowlist DM (handle, email, numeri E.164, chat_id:*, chat_guid:*).
• channels.bluebubbles.groupPolicy: open | allowlist | disabled (predefinito: allowlist).
• channels.bluebubbles.groupAllowFrom: Allowlist mittenti gruppi.
• channels.bluebubbles.groups: Configurazione per gruppo (requireMention, ecc.).
• channels.bluebubbles.sendReadReceipts: Invia conferme di lettura (predefinito: true).
• channels.bluebubbles.blockStreaming: Abilita streaming a blocchi (predefinito: false; necessario per risposte in streaming).
• channels.bluebubbles.textChunkLimit: Dimensione segmento in uscita in caratteri (predefinito: 4000).
• channels.bluebubbles.chunkMode: length (predefinito) divide solo quando supera textChunkLimit; newline divide sulle righe vuote (confini di paragrafo) prima della segmentazione per lunghezza.
• channels.bluebubbles.mediaMaxMb: Limite media in ingresso/uscita in MB (predefinito: 8).
• channels.bluebubbles.mediaLocalRoots: Allowlist esplicita di directory locali assolute permesse per percorsi media locali in uscita. Gli invii da percorso locale sono negati per impostazione predefinita a meno che non sia configurato. Sovrascrittura per account: channels.bluebubbles.accounts.<accountId>.mediaLocalRoots.
• channels.bluebubbles.historyLimit: Massimo messaggi di gruppo per contesto (0 disabilita).
• channels.bluebubbles.dmHistoryLimit: Limite storico DM.
• channels.bluebubbles.actions: Abilita/disabilita azioni specifiche.
• channels.bluebubbles.accounts: Configurazione multi-account.

Opzioni globali correlate:

• agents.list[].groupChat.mentionPatterns (o messages.groupChat.mentionPatterns).
• messages.responsePrefix.

Indirizzamento / target di consegna

Preferisci chat_guid per routing stabile:

• chat_guid:iMessage;-;+15555550123 (preferito per i gruppi)
• chat_id:123
• chat_identifier:...
• Handle diretti: +15555550123, [email protected]
  • Se un handle diretto non ha una chat DM esistente, OpenClaw ne creera una via POST /api/v1/chat/new. Questo richiede che la Private API di BlueBubbles sia abilitata.

Sicurezza

• Le richieste webhook sono autenticate confrontando i parametri query guid/password o gli header con channels.bluebubbles.password. Anche le richieste da localhost sono accettate.
• Mantieni la password API e l’endpoint webhook segreti (trattali come credenziali).
• La fiducia localhost significa che un reverse proxy sullo stesso host puo involontariamente bypassare la password. Se fai il proxy del gateway, richiedi l’autenticazione al proxy e configura gateway.trustedProxies. Vedi Sicurezza gateway.
• Abilita HTTPS + regole firewall sul server BlueBubbles se lo esponi fuori dalla tua LAN.

Risoluzione problemi

• Se gli eventi di digitazione/lettura smettono di funzionare, controlla i log webhook di BlueBubbles e verifica che il percorso del gateway corrisponda a channels.bluebubbles.webhookPath.
• I codici di pairing scadono dopo un’ora; usa openclaw pairing list bluebubbles e openclaw pairing approve bluebubbles <code>.
• Le reazioni richiedono la private API di BlueBubbles (POST /api/v1/message/react); assicurati che la versione del server la esponga.
• Modifica/annullamento invio richiedono macOS 13+ e una versione compatibile del server BlueBubbles. Su macOS 26 (Tahoe), la modifica e attualmente rotta a causa di cambiamenti nella private API.
• Gli aggiornamenti delle icone di gruppo possono essere instabili su macOS 26 (Tahoe): l’API potrebbe restituire successo ma la nuova icona non si sincronizza.
• OpenClaw nasconde automaticamente le azioni note come rotte in base alla versione macOS del server BlueBubbles. Se la modifica appare ancora su macOS 26 (Tahoe), disabilitala manualmente con channels.bluebubbles.actions.edit=false.
• Per info stato/salute: openclaw status --all o openclaw status --deep.

Per il riferimento generale del flusso canali, vedi Canali e la guida Plugin.