## §OIP SYSTEM ARTICLE — IMSG (34 operations)
A generated article for one OIP shelf. It lists every operation in this API/CLI/MCP/device/model/core subsystem, links each leaf article, and gives the ledger path for proof.

### Read Order
- scan operations
- open a leaf doc
- run via run_now or POST /api/dispatch
- open receipt
- repair/replay if needed

### Operations
- **IMSG_SEARCH** — Search the owner's entire iMessage/SMS history (673k messages) by text. JSON lines with chat_id, chat_guid, se
  when: find a message, link, code or conversation by what was said.
  args: $1 = text to find, $2 = max results, optional, default 20
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_SEARCH&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_SEARCH&body=invoice%7C10&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_SEARCH
- **IMSG_CHATS** — List the owner's most recent iMessage/SMS conversations from the Mac's own Messages store. JSON lines: id (cha
  when: you need a chat_id for IMSG_HISTORY / IMSG_SEND_CHAT, or want to see who the owner talks to most recently.
  args: $1 = how many recent chats, optional, default 20
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_CHATS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_CHATS&body=10&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_CHATS
- **IMSG_UNREAD** — List only the conversations with unread inbound messages (same shape as IMSG_CHATS, with unread_count).
  when: triage: what is waiting for the owner right now.
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_UNREAD&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_UNREAD&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_UNREAD
- **IMSG_HISTORY** — Read a conversation: the last N messages of one chat with decoded bodies (imsg decodes the attributedBody blob
  when: read what was said in a thread before replying, summarising or extracting.
  args: $1 = chat rowid from IMSG_CHATS, $2 = messages to return, optional, default 30
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_HISTORY&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_HISTORY&body=2803%7C20&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_HISTORY
- **IMSG_STATS** — Aggregate message statistics: totals by service, by chat, by sender, by date; media counts.
  when: how much does the owner message, with whom, how often.
  args: $1 = chat rowid, optional; empty = whole account
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_STATS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_STATS&body=2803&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_STATS
- **IMSG_GROUP** — Identity of one chat: guid, identifier, display name, service, is_group, participants.
  when: you have a chat_id and need its guid or participants.
  args: $1 = chat rowid
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_GROUP&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_GROUP&body=2807&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_GROUP
- **IMSG_WHOIS** — Is this handle known to the owner's Messages history and which service (imessage/sms) it uses. Local, no netwo
  when: before sending: pick service, confirm the contact exists in history.
  args: $1 = phone number in E.164 or email
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_WHOIS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_WHOIS&body=%2B14155551212&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_WHOIS
- **IMSG_ACCOUNT** — The iMessage account(s) signed in on the Mac and their chat counts.
  when: confirm which identity a send will go out under.
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_ACCOUNT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_ACCOUNT&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_ACCOUNT
- **IMSG_STATUS** — Health of the iMessage executor: imsg version, database ready, features (reactions, scheduled, unread), SIP st
  when: diagnose before blaming a send or read.
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_STATUS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_STATUS&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_STATUS
- **IMSG_SCHEDULED** — Messages the owner scheduled with Send Later that have not gone out yet (read-only).
  when: what is queued to send.
  args: $1 = max rows, optional, default 20
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_SCHEDULED&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_SCHEDULED&body=20&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_SCHEDULED
- **IMSG_AFTER** — Cursor feed of every message after a rowid, including reactions and edits, with next_rowid and has_more. This 
  when: an agent or flow wants everything that happened in Messages since it last looked.
  args: $1 = message rowid cursor; 0 = oldest, $2 = max messages, optional, default 50
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_AFTER&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_AFTER&body=677270%7C50&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_AFTER
- **IMSG_SEND_STATUS** — Delivery state of a sent message: send_state (sent/delivered/read), delivered_at, date_read, error.
  when: prove a send landed before claiming it did.
  args: $1 = message guid returned by IMSG_SEND
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_SEND_STATUS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_SEND_STATUS&body=63BBA90F-1238-4A76-807C-24C1FCB46FE0&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_SEND_STATUS
- **IMSG_SEND** — Send a text message from the owner's own Apple identity to a phone number or email. Returns the new message id
  when: the owner asked to text someone, or a flow reached its 'notify by text' step.
  args: $1 = phone number in E.164 or email, $2 = message body, $3 = imessage|sms|auto, optional, default auto
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_SEND&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_SEND&body=%2B14155551212%7COn%20my%20way&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_SEND
- **IMSG_SEND_CHAT** — Send a text into an existing conversation (direct or group) by chat rowid.
  when: reply inside a known thread or a group chat.
  args: $1 = chat rowid from IMSG_CHATS, $2 = message body
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_SEND_CHAT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_SEND_CHAT&body=2807%7CRunning%2010%20minutes%20late&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_SEND_CHAT
- **IMSG_SEND_FILE** — Send a file (image, PDF, audio as voice message) to a recipient from the owner's identity.
  when: deliver an artifact by iMessage.
  args: $1 = phone number or email, $2 = absolute file path on the Mac, $3 = caption, optional
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_SEND_FILE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_SEND_FILE&body=%2B14155551212%7C%2Ftmp%2Freport.pdf%7CHere%20is%20the%20report&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_SEND_FILE
- **IMSG_REACT_LATEST** — Tapback on the most recent incoming message of a chat (imsg, UI-verified).
  when: acknowledge the last message without words.
  args: $1 = chat rowid, $2 = love|like|dislike|laugh|emphasis|question
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_REACT_LATEST&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_REACT_LATEST&body=2803%7Clike&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_REACT_LATEST
- **IMSG_MESSAGES** — List messages of a chat with delivery/read flags, reactions and reply threads (Beeper view, message ids usable
  when: you need message ids to act on specific messages.
  args: $1 = chat id like any;-;+14155551212, or a bare phone/email
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_MESSAGES&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_MESSAGES&body=%2B14155551212&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_MESSAGES
- **IMSG_MESSAGE** — Fetch one message by id with its full metadata.
  when: inspect a single message.
  args: $1 = message guid
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_MESSAGE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_MESSAGE&body=63BBA90F-1238-4A76-807C-24C1FCB46FE0&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_MESSAGE
- **IMSG_REACT** — Add a tapback or emoji reaction to any message by id.
  when: react to a specific message, not just the latest.
  args: $1 = message guid, or latest / latest-N, $2 = heart|like|dislike|laugh|emphasize|question or any emoji
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_REACT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_REACT&body=latest-1%7Cheart&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_REACT
- **IMSG_UNREACT** — Remove a reaction from a message.
  when: undo a tapback.
  args: $1 = message guid or latest-N, $2 = the reaction to remove
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_UNREACT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_UNREACT&body=latest-1%7Cheart&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_UNREACT
- **IMSG_REPLY** — Reply to a specific message as a threaded (quoted) reply.
  when: answer one message in a busy thread.
  args: $1 = message guid, or latest / latest-N, $2 = reply body
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_REPLY&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_REPLY&body=latest%7CSounds%20good&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_REPLY
- **IMSG_EDIT** — Edit a message the owner sent (within Apple's edit window).
  when: fix a typo or a wrong number after sending.
  args: $1 = guid of a message the owner sent, or latest, $2 = new text
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_EDIT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_EDIT&body=latest%7CSounds%20good%2C%203pm&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_EDIT
- **IMSG_UNSEND** — Unsend a message the owner sent within the last two minutes.
  when: retract a message sent by mistake.
  args: $1 = guid of a message the owner sent, or latest
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_UNSEND&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_UNSEND&body=latest&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_UNSEND
- **IMSG_TYPING** — Show or clear the typing indicator in a chat.
  when: signal that a reply is coming while a longer step runs.
  args: $1 = chat id or phone/email, $2 = on|off, optional, default on
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_TYPING&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_TYPING&body=%2B14155551212%7Con&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_TYPING
- **IMSG_MARK_READ** — Mark a chat as read (sends the read receipt if enabled).
  when: clear a thread after handling it.
  args: $1 = chat id or phone/email
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_MARK_READ&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_MARK_READ&body=%2B14155551212&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_MARK_READ
- **IMSG_MARK_UNREAD** — Mark a chat as unread so it surfaces again for the owner.
  when: leave something for the owner to see.
  args: $1 = chat id or phone/email
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_MARK_UNREAD&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_MARK_UNREAD&body=%2B14155551212&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_MARK_UNREAD
- **IMSG_ACTIVITY** — Is the other party typing, and their Focus/Do Not Disturb state for this chat.
  when: decide whether to wait or notify anyway.
  args: $1 = chat id or phone/email
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_ACTIVITY&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_ACTIVITY&body=%2B14155551212&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_ACTIVITY
- **IMSG_LOAD_ATTACHMENT** — Force-download an attachment that iCloud has offloaded so its file exists on disk.
  when: an attachment path from IMSG_HISTORY is missing.
  args: $1 = message guid or latest-N
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_LOAD_ATTACHMENT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_LOAD_ATTACHMENT&body=latest-1&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_LOAD_ATTACHMENT
- **IMSG_CREATE_CHAT** — Start a new conversation (direct or group) with people the owner may never have messaged, sending the first me
  when: open a thread with someone new or create a group.
  args: $1 = space-separated phone numbers or emails, $2 = first message
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_CREATE_CHAT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_CREATE_CHAT&body=%2B14155551212%20%2B14155551213%7CHi%20both&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_CREATE_CHAT
- **IMSG_CURRENT_USER** — The owner's iMessage identity (email and phone) as Messages sees it.
  when: confirm the sending identity.
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_CURRENT_USER&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_CURRENT_USER&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_CURRENT_USER
- **IMSG_INBOX** — Tail the inbound event log written by the Mac's iMessage watcher: every new message (in or out) as full JSON, 
  when: what just came in, without polling chat.db.
  args: $1 = how many latest events, optional, default 20
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_INBOX&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_INBOX&body=20&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_INBOX
- **IMSG_INBOX_SINCE** — Every watched message created after a timestamp, full JSON.
  when: catch up a flow or agent on everything since it last ran.
  args: $1 = ISO-8601 timestamp, e.g. 2026-09-08T19:00:00Z
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_INBOX_SINCE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_INBOX_SINCE&body=2026-09-08T19%3A00%3A00Z&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_INBOX_SINCE
- **IMSG_WATCH_STATUS** — Is the inbound watcher running, its cursor, and how many events it has logged.
  when: health check of the inbound bus.
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_WATCH_STATUS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_WATCH_STATUS&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_WATCH_STATUS
- **IMSG_VERBS** — List every verb the Mac's iMessage API wrapper supports.
  when: discover the surface.
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=IMSG_VERBS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=IMSG_VERBS&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=IMSG_VERBS

### Troubleshooting
- If a row's example has placeholders, replace only the placeholder values and preserve separators.
- If a call fails, open its receipt and repair it with POST /api/dispatch {key, body, repairs:'inv_ID'}.
- If token scope denies this system, ask the owner for a row:/rows:/pfx: token scoped to the exact operation set.

Back to the tree: https://miscsubjects.com/api/dispatch?map=1&format=markdown