---
name: automating-messages
description: Automates macOS Messages (iMessage/SMS) via JXA with reliable service→buddy resolution. Use when asked to "automate iMessage", "send Messages via script", "JXA Messages automation", or "read Messages history". Covers send-bug workarounds, UI scripting for attachments, chat.db forensics, and launchd polling bots.
allowed-tools:
  - Bash
  - Read
  - Write
---

# Automating Messages (JXA-first with UI/DB fallbacks)

## Contents
- [Permissions and scope](#permissions-and-scope)
- [Default workflow](#default-workflow-happy-path)
- [Quick recipe](#quick-recipe-defensive-send)
- [Attachments and UI fallback](#attachments-and-ui-fallback)
- [Data access and forensics](#data-access-and-forensics)
- [Validation Checklist](#validation-checklist)
- [When Not to Use](#when-not-to-use)
- [What to load](#what-to-load)

## Permissions and scope
- Grants needed: Automation + Accessibility; Full Disk Access for any `chat.db` reads.
- Keep automation scoped and auditable; avoid unsolicited sends and DB writes.
- Pairs with `automating-mac-apps` for common setup (permissions, osascript invocation, UI scripting basics).

## Default workflow (happy path)
1) [ ] Resolve transport: pick `serviceType` (`iMessage` or `SMS`) before targeting a buddy.
2) [ ] Identify recipient: filter buddies by `handle` (phone/email). Avoid ambiguous names.
3) [ ] Send via app-level `send`: pass Buddy object to `Messages.send()`.
4) [ ] Verify window context: activate Messages when mixing with UI steps.
5) [ ] Fallbacks: if send/attachments fail, use UI scripting; for history, use SQL.

## Quick recipe (defensive send)
```javascript
const Messages = Application('Messages');
Messages.includeStandardAdditions = true;

function safeSend(text, handle, svcType = 'iMessage') {
  const svc = Messages.services.whose({ serviceType: svcType })[0];
  if (!svc) throw new Error(`Service ${svcType} missing`);
  const buddy = svc.buddies.whose({ handle })[0];
  if (!buddy) throw new Error(`Buddy ${handle} missing on ${svcType}`);
  Messages.send(text, { to: buddy });
}
```
- Wrap with `try/catch` and log; add small delays when activating UI.
- For groups, target an existing chat by GUID or fall back to UI scripting; array sends are unreliable.

## Attachments and UI fallback
- Messages lacks a stable JXA attachment API; use clipboard + System Events paste/send.
- Ensure Accessibility permission, bring app forward, paste file, press Enter.
- See `references/ui-scripting-attachments.md` for the full flow and ObjC pasteboard snippet.

## Data access and forensics

**Reading messages limitation:** The AppleScript/JXA API for Messages is effectively **write-only**. While `send()` works reliably, reading messages via `chat.messages()` or similar methods is broken/unsupported in modern macOS. The only reliable way to read message history is via direct SQLite access to `~/Library/Messages/chat.db`.

**Security consideration:** Reading `chat.db` requires **Full Disk Access** permission, which grants broad filesystem access beyond just Messages. This is a significant security trade-off - granting Full Disk Access to scripts or applications exposes all user data. Consider whether reading message history is truly necessary before enabling this permission.

- Use SQL against `chat.db` for history; JXA `chat.messages()` is unreliable/non-functional.
- Requires: **System Settings > Privacy & Security > Full Disk Access** for your terminal/script.
- Remember Cocoa epoch conversion (nanoseconds since 2001-01-01); use `sqlite3 -json` for structured results.
- See `references/database-forensics.md` for schema notes, typedstream handling, and export tooling.

**Example read query (requires Full Disk Access):**
```sql
sqlite3 ~/Library/Messages/chat.db "SELECT
  CASE WHEN m.is_from_me = 1 THEN 'Me' ELSE 'Them' END as sender,
  m.text,
  datetime(m.date/1000000000 + 978307200, 'unixepoch', 'localtime') as date
FROM message m
JOIN handle h ON m.handle_id = h.rowid
WHERE h.id LIKE '%PHONE_NUMBER%'
ORDER BY m.date DESC LIMIT 10;"
```

## Bots and monitoring
- Implement polling daemons with `launchd` now that on-receive handlers are gone.
- Track `rowid`, query diffs, dispatch actions, and persist state.
- See `references/monitoring-daemons.md` for the polling pattern and plist notes.

## Validation Checklist
- [ ] Automation + Accessibility permissions granted
- [ ] Service resolves: `Messages.services.whose({ serviceType: 'iMessage' })[0]` returns object
- [ ] Buddy lookup works: `svc.buddies.whose({ handle })[0]` returns target
- [ ] Test send completes without errors
- [ ] Full Disk Access granted if using `chat.db` reads

## When Not to Use
- For reading message history without Full Disk Access (AppleScript/JXA cannot read messages)
- For cross-platform messaging (use platform APIs or third-party services)
- For business SMS automation (use Twilio or similar APIs)
- When iMessage/SMS features are not available on the target system
- For bulk messaging (rate limits and security restrictions apply)
- When security policy prohibits Full Disk Access grants (required for any read operations)

## What to load
- Control plane and send reliability: `references/control-plane.md`
- UI scripting + attachments fallback: `references/ui-scripting-attachments.md`
- SQL/history access: `references/database-forensics.md`
- Polling bots/launchd: `references/monitoring-daemons.md`


---
Source attribution: SpillwaveSolutions
Original project: https://github.com/SpillwaveSolutions/automating-mac-apps-plugin/blob/5f37bd4ecb1746fc86f3d618e8aa81fc6a61c486/plugins/automating-mac-apps-plugin/skills/automating-messages/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2024 Richard Hightower

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: SpillwaveSolutions
Original project: https://github.com/SpillwaveSolutions/automating-mac-apps-plugin/blob/5f37bd4ecb1746fc86f3d618e8aa81fc6a61c486/plugins/automating-mac-apps-plugin/skills/automating-messages/SKILL.md
Attribution basis: Recovered original package and original project license at a pinned revision

Fields of work: Sales, Customer Support
Roles: Customer Success Manager, Sales Development Rep (SDR), Technical Support
Specialties: API, Backend
Tools: Bash
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 237eba47bfefc04ae5bec2c7000ed3f560d72d0b9bf79d5ba454e2cedcee39f1
Metadata reviewed: 2026-10-27
This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.