BlueBubbles (macOS REST)

Status: gebundelde plugin die communiceert met de BlueBubbles macOS-server via HTTP. Aanbevolen voor iMessage-integratie vanwege de rijkere API en eenvoudigere installatie vergeleken met het verouderde imsg-kanaal.

Overzicht

• Draait op macOS via de BlueBubbles-helper-app (bluebubbles.app).
• Aanbevolen/getest: macOS Sequoia (15). macOS Tahoe (26) werkt; bewerken is momenteel niet werkend op Tahoe, en groepsicoonupdates kunnen succes melden maar niet synchroniseren.
• OpenClaw communiceert via de REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
• Inkomende berichten komen binnen via webhooks; uitgaande antwoorden, typindicatoren, leesbevestigingen en tapbacks zijn REST-aanroepen.
• Bijlagen en stickers worden opgenomen als inkomende media (en waar mogelijk aan de agent getoond).
• Koppeling/allowlist werkt op dezelfde manier als andere kanalen (/channels/pairing etc.) met channels.bluebubbles.allowFrom + koppelingscodes.
• Reacties worden als systeemevents getoond, net als bij Slack/Telegram, zodat agents ze kunnen “vermelden” voordat ze antwoorden.
• Geavanceerde functies: bewerken, ongedaan maken, antwoord-threading, berichteffecten, groepsbeheer.

Snelle start

1. Installeer de BlueBubbles-server op je Mac (volg de instructies op bluebubbles.app/install).

2. Schakel in de BlueBubbles-configuratie de web-API in en stel een wachtwoord in.

3. Voer openclaw onboard uit en selecteer BlueBubbles, of configureer handmatig:

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

4. Wijs BlueBubbles-webhooks naar je gateway (voorbeeld: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).

5. Start de gateway; deze registreert de webhook-handler en begint met koppelen.

Beveiligingsopmerking:

• Stel altijd een webhook-wachtwoord in.
• Webhook-authenticatie is altijd vereist. OpenClaw weigert BlueBubbles-webhookverzoeken tenzij ze een wachtwoord/GUID bevatten dat overeenkomt met channels.bluebubbles.password (bijv. ?password=<password> of x-password), ongeacht loopback-/proxytopologie.
• Wachtwoordauthenticatie wordt gecontroleerd voordat volledige webhook-bodies worden gelezen/geparsed.

Messages.app actief houden (VM / headless setups)

Sommige macOS VM / altijd-aan setups kunnen ertoe leiden dat Messages.app “idle” gaat (inkomende events stoppen totdat de app wordt geopend/naar de voorgrond wordt gebracht). Een eenvoudige oplossing is om Messages elke 5 minuten aan te prikken met een AppleScript + LaunchAgent.

1) Sla het AppleScript op

Sla dit op als:

• ~/Scripts/poke-messages.scpt

Voorbeeldscript (niet-interactief; steelt geen 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) Installeer een LaunchAgent

Sla dit op als:

• ~/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>

Opmerkingen:

• Dit draait elke 300 seconden en bij inloggen.
• De eerste keer kan macOS Automatiseringsprompts triggeren (osascript -> Messages). Keur ze goed in dezelfde gebruikerssessie die de LaunchAgent draait.

Laden:

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

Onboarding

BlueBubbles is beschikbaar in de interactieve installatiewizard:

openclaw onboard

De wizard vraagt om:

• Server-URL (vereist): BlueBubbles-serveradres (bijv. http://192.168.1.100:1234)
• Wachtwoord (vereist): API-wachtwoord uit BlueBubbles Server-instellingen
• Webhook-pad (optioneel): standaard /bluebubbles-webhook
• DM-beleid: koppeling, allowlist, open of uitgeschakeld
• Allowlist: telefoonnummers, e-mails of chatdoelen

Je kunt BlueBubbles ook toevoegen via CLI:

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

Toegangscontrole (DM’s + groepen)

DM’s:

• Standaard: channels.bluebubbles.dmPolicy = "pairing".
• Onbekende afzenders ontvangen een koppelingscode; berichten worden genegeerd totdat goedgekeurd (codes verlopen na 1 uur).
• Goedkeuren via:
  • openclaw pairing list bluebubbles
  • openclaw pairing approve bluebubbles <CODE>
• Koppeling is de standaard tokenuitwisseling. Details: Koppeling

Groepen:

• channels.bluebubbles.groupPolicy = open | allowlist | disabled (standaard: allowlist).
• channels.bluebubbles.groupAllowFrom bepaalt wie kan triggeren in groepen wanneer allowlist is ingesteld.

Mention-gating (groepen)

BlueBubbles ondersteunt mention-gating voor groepschats, overeenkomend met iMessage/WhatsApp-gedrag:

• Gebruikt agents.list[].groupChat.mentionPatterns (of messages.groupChat.mentionPatterns) om vermeldingen te detecteren.
• Wanneer requireMention is ingeschakeld voor een groep, antwoordt de agent alleen wanneer vermeld.
• Besturingscommando’s van geautoriseerde afzenders omzeilen mention-gating.

Per-groepsconfiguratie:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

Commando-gating

• Besturingscommando’s (bijv. /config, /model) vereisen autorisatie.
• Gebruikt allowFrom en groupAllowFrom om commandoautorisatie te bepalen.
• Geautoriseerde afzenders kunnen besturingscommando’s uitvoeren zelfs zonder vermelding in groepen.

Typindicatoren + leesbevestigingen

• Typindicatoren: worden automatisch verzonden voor en tijdens het genereren van antwoorden.
• Leesbevestigingen: beheerd door channels.bluebubbles.sendReadReceipts (standaard: true).
• Typindicatoren: OpenClaw stuurt typ-startevents; BlueBubbles wist typen automatisch bij verzenden of time-out (handmatige stop via DELETE is onbetrouwbaar).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

Geavanceerde acties

BlueBubbles ondersteunt geavanceerde berichtacties wanneer ingeschakeld in de configuratie:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

Beschikbare acties:

• react: Tapback-reacties toevoegen/verwijderen (messageId, emoji, remove)
• edit: Een verzonden bericht bewerken (messageId, text)
• unsend: Een bericht ongedaan maken (messageId)
• reply: Antwoorden op een specifiek bericht (messageId, text, to)
• sendWithEffect: Verzenden met iMessage-effect (text, to, effectId)
• renameGroup: Een groepschat hernoemen (chatGuid, displayName)
• setGroupIcon: Het icoon/foto van een groepschat instellen (chatGuid, media) — onstabiel op macOS 26 Tahoe (API kan succes melden maar het icoon synchroniseert niet).
• addParticipant: Iemand toevoegen aan een groep (chatGuid, address)
• removeParticipant: Iemand verwijderen uit een groep (chatGuid, address)
• leaveGroup: Een groepschat verlaten (chatGuid)
• sendAttachment: Media/bestanden verzenden (to, buffer, filename, asVoice)
  • Spraakberichten: stel asVoice: true in met MP3- of CAF-audio om als iMessage-spraakbericht te verzenden. BlueBubbles converteert MP3 naar CAF bij het verzenden van spraakberichten.

Bericht-ID’s (kort vs. volledig)

OpenClaw kan korte bericht-ID’s tonen (bijv. 1, 2) om tokens te besparen.

• MessageSid / ReplyToId kunnen korte ID’s zijn.
• MessageSidFull / ReplyToIdFull bevatten de volledige provider-ID’s.
• Korte ID’s zijn in-memory; ze kunnen verlopen bij herstart of cache-evictie.
• Acties accepteren korte of volledige messageId, maar korte ID’s geven een fout als ze niet meer beschikbaar zijn.

Gebruik volledige ID’s voor duurzame automatiseringen en opslag:

• Templates: {{MessageSidFull}}, {{ReplyToIdFull}}
• Context: MessageSidFull / ReplyToIdFull in inkomende payloads

Zie Configuratie voor templatevariabelen.

Blokstreaming

Bepaal of antwoorden als een enkel bericht of gestreamd in blokken worden verzonden:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

Media + limieten

• Inkomende bijlagen worden gedownload en opgeslagen in de mediacache.
• Medialimiet via channels.bluebubbles.mediaMaxMb voor inkomende en uitgaande media (standaard: 8 MB).
• Uitgaande tekst wordt opgesplitst bij channels.bluebubbles.textChunkLimit (standaard: 4000 tekens).

Configuratiereferentie

Volledige configuratie: Configuratie

Provideropties:

• channels.bluebubbles.enabled: het kanaal in-/uitschakelen.
• channels.bluebubbles.serverUrl: BlueBubbles REST API basis-URL.
• channels.bluebubbles.password: API-wachtwoord.
• channels.bluebubbles.webhookPath: webhook-eindpuntpad (standaard: /bluebubbles-webhook).
• channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (standaard: pairing).
• channels.bluebubbles.allowFrom: DM-allowlist (handles, e-mails, E.164-nummers, chat_id:*, chat_guid:*).
• channels.bluebubbles.groupPolicy: open | allowlist | disabled (standaard: allowlist).
• channels.bluebubbles.groupAllowFrom: groepsafzender-allowlist.
• channels.bluebubbles.groups: per-groepsconfiguratie (requireMention, etc.).
• channels.bluebubbles.sendReadReceipts: leesbevestigingen verzenden (standaard: true).
• channels.bluebubbles.blockStreaming: blokstreaming inschakelen (standaard: false; vereist voor streaming-antwoorden).
• channels.bluebubbles.textChunkLimit: uitgaande chunkgrootte in tekens (standaard: 4000).
• channels.bluebubbles.chunkMode: length (standaard) splitst alleen bij overschrijding van textChunkLimit; newline splitst op lege regels (alineagrenzen) voor lengteopsplitsing.
• channels.bluebubbles.mediaMaxMb: inkomende/uitgaande medialimiet in MB (standaard: 8).
• channels.bluebubbles.mediaLocalRoots: expliciete allowlist van absolute lokale mappen toegestaan voor uitgaande lokale mediapaden. Lokale padverzendingen worden standaard geweigerd tenzij dit is geconfigureerd. Per-account-overschrijving: channels.bluebubbles.accounts.<accountId>.mediaLocalRoots.
• channels.bluebubbles.historyLimit: maximaal aantal groepsberichten voor context (0 schakelt uit).
• channels.bluebubbles.dmHistoryLimit: DM-geschiedenislimiet.
• channels.bluebubbles.actions: specifieke acties in-/uitschakelen.
• channels.bluebubbles.accounts: multi-account-configuratie.

Gerelateerde globale opties:

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

Adressering / afleveringsdoelen

Gebruik bij voorkeur chat_guid voor stabiele routering:

• chat_guid:iMessage;-;+15555550123 (voorkeur voor groepen)
• chat_id:123
• chat_identifier:...
• Directe handles: +15555550123, [email protected]
  • Als een directe handle geen bestaande DM-chat heeft, maakt OpenClaw er een aan via POST /api/v1/chat/new. Dit vereist dat de BlueBubbles Private API is ingeschakeld.

Beveiliging

• Webhookverzoeken worden geauthenticeerd door guid/password queryparameters of headers te vergelijken met channels.bluebubbles.password. Verzoeken vanaf localhost worden ook geaccepteerd.
• Houd het API-wachtwoord en webhook-eindpunt geheim (behandel ze als credentials).
• Localhost-vertrouwen betekent dat een same-host reverse proxy onbedoeld het wachtwoord kan omzeilen. Als je de gateway proxyt, vereis authenticatie bij de proxy en configureer gateway.trustedProxies. Zie Gateway-beveiliging.
• Schakel HTTPS + firewallregels in op de BlueBubbles-server als je deze buiten je LAN blootstelt.

Probleemoplossing

• Als typ-/leesevents stoppen met werken, controleer dan de BlueBubbles-webhooklogs en verifieer dat het gatewaypad overeenkomt met channels.bluebubbles.webhookPath.
• Koppelingscodes verlopen na een uur; gebruik openclaw pairing list bluebubbles en openclaw pairing approve bluebubbles <code>.
• Reacties vereisen de BlueBubbles private API (POST /api/v1/message/react); zorg ervoor dat de serverversie deze blootstelt.
• Bewerken/ongedaan maken vereist macOS 13+ en een compatibele BlueBubbles-serverversie. Op macOS 26 (Tahoe) is bewerken momenteel niet werkend door privé-API-wijzigingen.
• Groepsicoonupdates kunnen onstabiel zijn op macOS 26 (Tahoe): de API kan succes melden maar het nieuwe icoon synchroniseert niet.
• OpenClaw verbergt automatisch bekend-niet-werkende acties op basis van de macOS-versie van de BlueBubbles-server. Als bewerken nog steeds verschijnt op macOS 26 (Tahoe), schakel het handmatig uit met channels.bluebubbles.actions.edit=false.
• Voor status-/gezondheidsinformatie: openclaw status --all of openclaw status --deep.

Voor algemene kanaalworkflowreferentie, zie Kanalen en de Plugins-gids.