BlueBubbles

Status: gebundelde legacy-plugin die via HTTP met de BlueBubbles macOS-server praat. Bestaande BlueBubbles-setups blijven werken, maar nieuwe OpenClaw iMessage-implementaties zouden de native iMessage-plugin moeten verkiezen wanneer de vereisten bij je host passen.

# Overzicht

• Draait op macOS via de BlueBubbles-helper-app (bluebubbles.app).
• Legacy-terugval voor installaties die al afhankelijk zijn van BlueBubbles-kanaal-ID's, webhookstatus, groepsdoelen, cronbezorging of werkruimte-routering.
• Aanbevolen/getest: macOS Sequoia (15). macOS Tahoe (26) werkt; bewerken is momenteel kapot op Tahoe, en updates van groepspictogrammen kunnen succes melden maar niet synchroniseren.
• OpenClaw praat ermee 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 aangeboden).
• Auto-TTS-antwoorden die MP3- of CAF-audio synthetiseren, worden bezorgd als iMessage-spraakmemobubbels in plaats van gewone bestandsbijlagen.
• Koppelen/toestaanlijst werkt op dezelfde manier als andere kanalen (/channels/pairing enz.) met channels.bluebubbles.allowFrom + koppelcodes.
• Reacties worden als systeemgebeurtenissen aangeboden, net als bij Slack/Telegram, zodat agents ze kunnen "vermelden" voordat ze antwoorden.
• Geavanceerde functies: bewerken, verzenden ongedaan maken, antwoordthreads, berichteffecten, groepsbeheer.

# Snel starten

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

# Messages.app actief houden (VM / headless setups)

Sommige macOS-VM- / altijd-aan-setups kunnen eindigen met Messages.app die "idle" wordt (inkomende gebeurtenissen stoppen totdat de app wordt geopend/naar de voorgrond wordt gehaald). Een eenvoudige workaround is om Messages elke 5 minuten aan te tikken met een AppleScript + LaunchAgent.

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

<?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>

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 interactieve onboarding:

openclaw onboard

De wizard vraagt om:

Je kunt BlueBubbles ook toevoegen via de CLI:

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

# Toegangscontrole (DM's + groepen)

# Verrijking van contactnamen (macOS, optioneel)

BlueBubbles-groepswebhooks bevatten vaak alleen ruwe deelnemersadressen. Als je wilt dat de GroupMembers-context in plaats daarvan lokale contactnamen toont, kun je je aanmelden voor lokale Contacts-verrijking op macOS:

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true schakelt de lookup in. Standaard: false.
• Lookups worden alleen uitgevoerd nadat groepstoegang, commandoautorisatie en vermeldingsgating het bericht hebben doorgelaten.
• Alleen naamloze telefoondeelnemers worden verrijkt.
• Ruwe telefoonnummers blijven de fallback wanneer er geen lokale match wordt gevonden.

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

# Vermeldingsgating (groepen)

BlueBubbles ondersteunt vermeldingsgating voor groepschats, passend bij 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 die wordt vermeld.
• Controlecommando's van geautoriseerde afzenders omzeilen vermeldingsgating.

Configuratie per groep:

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

# Commandogating

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

# Systeemprompt per groep

Elke vermelding onder channels.bluebubbles.groups.* accepteert een optionele systemPrompt-string. De waarde wordt geïnjecteerd in de systeemprompt van de agent bij elke beurt die een bericht in die groep behandelt, zodat je per groep persona- of gedragsregels kunt instellen zonder agentprompts te bewerken:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;-;chat123": {
          systemPrompt: "Keep responses under 3 sentences. Mirror the group's casual tone.",
        },
      },
    },
  },
}

De sleutel komt overeen met wat BlueBubbles meldt als chatGuid / chatIdentifier / numerieke chatId voor de groep, en een "*"-wildcardvermelding biedt een standaard voor elke groep zonder exacte match (hetzelfde patroon dat wordt gebruikt door requireMention en toolbeleid per groep). Exacte matches winnen altijd van de wildcard. DM's negeren dit veld; gebruik in plaats daarvan promptaanpassing op agent- of accountniveau.

# Uitgewerkt voorbeeld: gethreadde antwoorden en tapback-reacties (private API)

Met de BlueBubbles private API ingeschakeld komen inkomende berichten binnen met korte bericht-ID's (bijvoorbeeld [[reply_to:5]]) en kan de agent action=reply aanroepen om in een specifiek bericht te threaden of action=react om een tapback te plaatsen. Een systemPrompt per groep is een betrouwbare manier om de agent de juiste tool te laten kiezen:

{
  channels: {
    bluebubbles: {
      groups: {
        "iMessage;+;chat-family": {
          systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
        },
      },
    },
  },
}

Tapback-reacties en gethreadde antwoorden vereisen beide de BlueBubbles private API; zie Geavanceerde acties en Bericht-ID's voor de onderliggende mechanismen.

# ACP-gespreksbindingen

BlueBubbles-chats kunnen worden omgezet in duurzame ACP-werkruimten zonder de transportlaag te wijzigen.

Snelle operatorflow:

• Voer /acp spawn codex --bind here uit in de DM of toegestane groepschat.
• Toekomstige berichten in datzelfde BlueBubbles-gesprek worden naar de gespawnde ACP-sessie gerouteerd.
• /new en /reset resetten dezelfde gebonden ACP-sessie ter plekke.
• /acp close sluit de ACP-sessie en verwijdert de binding.

Geconfigureerde persistente bindingen worden ook ondersteund via top-level bindings[]-vermeldingen met type: "acp" en match.channel: "bluebubbles".

match.peer.id kan elke ondersteunde BlueBubbles-doelvorm gebruiken:

• genormaliseerde DM-handle zoals +15555550123 of [email protected]
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

Voor stabiele groepskoppelingen geef je de voorkeur aan chat_id:* of chat_identifier:*.

Voorbeeld:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

Zie ACP-agenten voor gedeeld gedrag van ACP-koppelingen.

# Typen + leesbevestigingen

• Typindicatoren: Worden automatisch verzonden vóór en tijdens het genereren van antwoorden.
• Leesbevestigingen: Beheerd door channels.bluebubbles.sendReadReceipts (standaard: true).
• Typindicatoren: OpenClaw verzendt gebeurtenissen voor starten met typen; BlueBubbles wist typen automatisch bij verzenden of timeout (handmatig stoppen via DELETE is onbetrouwbaar).

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

# Geavanceerde acties

BlueBubbles ondersteunt geavanceerde berichtacties wanneer deze zijn 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
      },
    },
  },
}

# Bericht-ID's (kort versus volledig)

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

• MessageSid / ReplyToId kunnen korte ID's zijn.
• MessageSidFull / ReplyToIdFull bevatten de volledige ID's van de provider.
• Korte ID's bevinden zich in het geheugen; ze kunnen verlopen bij een herstart of cacheverwijdering.
• Acties accepteren korte of volledige messageId, maar korte ID's geven een fout als ze niet langer beschikbaar zijn.

Gebruik volledige ID's voor duurzame automatiseringen en opslag:

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

Zie Configuratie voor sjabloonvariabelen.

# Gesplitst verzonden DM's samenvoegen (opdracht + URL in één compositie)

Wanneer een gebruiker in iMessage een opdracht en een URL samen typt - bijvoorbeeld Dump https://example.com/article - splitst Apple de verzending in twee afzonderlijke Webhook-leveringen:

1. Een tekstbericht ("Dump").
2. Een URL-voorbeeldballon ("https://...") met OG-voorbeeldafbeeldingen als bijlagen.

De twee Webhooks komen bij de meeste configuraties ~0,8-2,0 s na elkaar binnen bij OpenClaw. Zonder samenvoeging ontvangt de agent alleen de opdracht in beurt 1, antwoordt deze (vaak "stuur me de URL") en ziet hij de URL pas in beurt 2 - waarna de opdrachtcontext al verloren is.

channels.bluebubbles.coalesceSameSenderDms laat een DM opeenvolgende Webhooks van dezelfde afzender samenvoegen tot één agentbeurt. Groepschats blijven per bericht sleutel gebruiken, zodat de beurtstructuur met meerdere gebruikers behouden blijft.

{
  channels: {
    bluebubbles: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is slow
        // or under memory pressure (observed gap can stretch past 2 s then).
        bluebubbles: 2500,
      },
    },
  },
}

# Scenario's en wat de agent ziet

# Probleemoplossing voor samenvoeging van gesplitste verzendingen

Als de vlag aan staat en gesplitste verzendingen nog steeds als twee beurten binnenkomen, controleer dan elke laag:

grep coalesceSameSenderDms ~/.openclaw/openclaw.json

grep -E "Dispatching event to webhook" main.log | tail -20

# Blokstreaming

Bepaal of antwoorden als één bericht worden verzonden of in blokken worden gestreamd:

{
  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 volgens channels.bluebubbles.textChunkLimit (standaard: 4000 tekens).

# Configuratiereferentie

Volledige configuratie: Configuratie

Gerelateerde globale opties:

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

# Adressering / afleveringsdoelen

Geef de voorkeur aan chat_guid voor stabiele routering:

• chat_guid:iMessage;-;+15555550123 (aanbevolen 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 via POST /api/v1/chat/new. Hiervoor moet de BlueBubbles Private API zijn ingeschakeld.

# Routering via iMessage versus SMS

Wanneer dezelfde handle zowel een iMessage- als een SMS-chat op de Mac heeft (bijvoorbeeld een telefoonnummer dat voor iMessage is geregistreerd maar ook green-bubble fallbacks heeft ontvangen), geeft OpenClaw de voorkeur aan de iMessage-chat en degradeert het nooit stilzwijgend naar SMS. Gebruik een expliciet sms:-doelprefix om de SMS-chat te forceren (bijvoorbeeld sms:+15555550123). Handles zonder overeenkomende iMessage-chat worden nog steeds verzonden via de chat die BlueBubbles rapporteert.

# Beveiliging

• Webhook-aanvragen worden geauthenticeerd door guid/password-queryparameters of headers te vergelijken met channels.bluebubbles.password.
• Houd het API-wachtwoord en het Webhook-eindpunt geheim (behandel ze als referenties).
• Er is geen localhost-bypass voor BlueBubbles Webhook-authenticatie. Als je Webhook-verkeer proxyt, houd dan het BlueBubbles-wachtwoord end-to-end op de aanvraag. gateway.trustedProxies vervangt hier channels.bluebubbles.password niet. Zie Gateway-beveiliging.
• Schakel HTTPS + firewallregels in op de BlueBubbles-server als je deze buiten je LAN beschikbaar maakt.

# Probleemoplossing

• Als typ-/leesgebeurtenissen niet meer werken, controleer dan de BlueBubbles Webhook-logs en verifieer dat het Gateway-pad overeenkomt met channels.bluebubbles.webhookPath.
• Koppelingscodes verlopen na één 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 beschikbaar stelt.
• Bewerken/verzenden ongedaan maken vereist macOS 13+ en een compatibele BlueBubbles-serverversie. Op macOS 26 (Tahoe) werkt bewerken momenteel niet door wijzigingen in de private API.
• Updates van groepspictogrammen kunnen onbetrouwbaar zijn op macOS 26 (Tahoe): de API kan succes retourneren terwijl het nieuwe pictogram niet synchroniseert.
• OpenClaw verbergt automatisch bekende defecte acties op basis van de macOS-versie van de BlueBubbles-server. Als bewerken nog steeds verschijnt op macOS 26 (Tahoe), schakel het dan handmatig uit met channels.bluebubbles.actions.edit=false.
• coalesceSameSenderDms ingeschakeld maar gesplitste verzendingen (bijv. Dump + URL) komen nog steeds als twee beurten binnen: zie de controlelijst voor probleemoplossing voor samenvoegen van gesplitste verzendingen - veelvoorkomende oorzaken zijn een te krap debouncevenster, sessielogtijdstempels die worden verward met Webhook-aankomst, of een verzending met antwoordcitaat (die replyToBody gebruikt, geen tweede Webhook).
• Voor status-/gezondheidsinformatie: openclaw status --all of openclaw status --deep.

Zie voor algemene referentie over kanaalworkflows Kanalen en de gids Plugins.

# Gerelateerd

• Kanaalroutering - sessieroutering voor berichten
• Overzicht van kanalen - alle ondersteunde kanalen
• Groepen - gedrag van groepschats en mention-gating
• Koppeling - DM-authenticatie en koppelingsflow
• Beveiliging - toegangsmodel en verharding