OpenClaw iMessage private API actions

Once the imsg bridge is injected into Messages, an OpenClaw agent stops being a text bot: it can tapback, reply in a thread, send with confetti, edit its own message, run a native poll and manage a group. Every one of those is a message-tool action with its own gate. Here is the action list, the ID rules, the detection logic, and the two places reactions do real work: approvals and questions.

The actions

• When the launch command is running and the status probe reports the private API as available, the message tool gains iMessage-native actions, all enabled by default and individually switchable under the channel actions block: reactions, edit, unsend, reply, send with effect, send attachment, rename group, set group icon, add and remove participant, leave group, and polls.
• React adds or removes tapbacks by message ID and emoji with the six supported kinds, love, like, dislike, laugh, emphasize and question, and removing without an emoji clears whichever was set; reply sends a threaded reply to an existing message addressed by chat GUID, chat ID, chat identifier or handle, where a local reply with an attachment needs an imsg build whose rich send supports a file and a remote imsg uses JSON-RPC for whole-message or first-part attachment replies only; send-with-effect takes an effect by name from slam, loud, gentle, invisible ink, confetti, lasers, fireworks, balloon, heart, echo, happy birthday, shooting star, sparkles and spotlight.
• Edit and unsend work on supported macOS and private API versions and only on messages the gateway itself sent; upload-file sends media from a base64 buffer or a hydrated path with a filename and an optional voice flag, with the old send-attachment name as an alias; and the group actions, rename, icon, add, remove and leave, apply when the current target is a group and, because they mutate the host's Messages identity, require an owner sender or an admin gateway client.
• Poll creates a native Apple Messages poll with a question and two to twelve options, seen and voted natively on the newest iOS, iPadOS and macOS releases and shown as a sent-a-poll text on older ones, requiring the poll payload selector; poll-vote votes by poll or message ID with exactly one of an option index, ID or text, requires the vote selector and the vote RPC method, and remote imsg accepts only the option ID; accepted inbound polls are rendered for the agent with question, options, counts and the poll message ID, and remote accounts add each stable option ID.

Only messages the gateway itself sent can be edited.

IDs, detection, receipts, tapbacks

Inbound context carries both short message IDs and full GUIDs when available: short IDs are scoped to the recent SQLite-backed reply cache and checked against the current chat before use, an expired short ID is retried with its full GUID while targeting the conversation that supplied it, full IDs do not bypass conversation or account binding, so an ID from another chat must be replaced with one from the current target, and remote delegated calls can reject stale full IDs when current-conversation evidence is unavailable. OpenClaw hides private API actions only when the cached probe status says the bridge is unavailable; with an unknown status the actions stay visible and dispatch probes lazily, so the first action can succeed right after the launch command without a manual refresh. When the bridge is up, accepted inbound chats are marked read and direct chats show a typing bubble as soon as the turn is accepted, read marking can be disabled with the read-receipts key, and older imsg builds that predate the per-method capability list gate typing and read off silently with a one-time warning per restart. Inbound tapbacks are routed as system events rather than message text so a user tapback never triggers a reply loop, with the notification mode own by default for reactions to bot-authored messages, all for every authorised sender's tapbacks, off to ignore them, and per-account overrides.

Approvals and questions

• When exec or plugin approvals are enabled and a request routes natively to iMessage, the prompt arrives with native controls: on a probed bridge with poll and caption-suppression support it includes a Messages poll with each allowed decision, older releases without the no-comment poll send stay on text controls, and when polls are disabled, unsupported, failing or fewer than two decisions exist the prompt keeps text and tapback controls, where a like maps to allow once, a dislike to deny, and the approve command lines include allow-always when permitted.
• Poll votes and reactions require the acting user's handle to be an explicit approver read from the channel or account allowlist as an E.164 number or Apple ID email, chat targets are not valid approver entries, the wildcard is honoured but lets anyone approve, an empty list disables the shortcuts entirely, and these shortcuts bypass the reaction notification mode, the DM policy and the group sender list because the explicit approver list is the only gate for approvals; native poll controls stay limited to the originating session or an approver DM while explicit forwarding targets keep the forwarded message, the approve command follows the same list with an explicit denial for senders on the DM allowlist but not the approver list, and with an empty approver list the same-chat fallback authorises anyone the DM allowlist permits.
• Bindings live in memory and in the persistent keyed store with a TTL matching the approval expiry, pending prompts are polled for tapbacks, a tap on an old control after a restart is recognised and swallowed while the in-flight command is over and needs a new request, the operator's own from-me tapback resolves an approval when that handle is an approver, prompts route into a group only with explicit approvers configured, and legacy text-style tapbacks cannot resolve approvals because they carry no GUID; separately, a single-select ask-user prompt with one to four options gets numbered emoji choices answered by reacting with the matching number on the bot-authored message, recognised even when reaction notifications are off, while multi-question, multi-select and free-text prompts stay text-only.

OpenClaw on iMessage is the channel post these actions extend, and OpenClaw iMessage private API how the bridge that enables them is switched on.

A tapback as a vote

Letting a thumbs-up approve a command sounds casual until you see the gate: only handles on the explicit approver list count, chat targets never do, and an empty list turns the shortcut off. OpenClaw reactions covers the cross-channel reaction semantics the tapbacks map to, and OpenClaw exec approvals the approval model the polls resolve.

On Diali

iMessage is not among the channels Diali connects today: WhatsApp, Telegram, Discord, Slack, Mattermost, Matrix, SMS and voice. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary that applies to each connected channel.

• Twelve actions, all on by default, each with a gate.
• Short IDs come from the reply cache; retry with the full GUID.
• Approval tapbacks need an explicit approver handle.