elizaos--eliza/plugins/plugin-imessage/README.md

@elizaos/plugin-imessage

iMessage plugin for elizaOS agents. Enables chat integration with Apple's iMessage on macOS.

Note: This plugin only works on macOS systems.

Features

• Send Messages: Send text messages via iMessage
• Direct & Group Chats: Support for direct messages and group conversations
• Attachments: Send media attachments (via CLI tool)
• Message Polling: Receive incoming messages via polling
• Policy Controls: Configure DM and group policies

Requirements

• macOS: This plugin only works on macOS
• Messages App Access: Full Disk Access permission may be required
• Optional CLI Tool: For enhanced functionality, use an iMessage CLI tool

Installation

# npm
npm install @elizaos/plugin-imessage

# bun
bun add @elizaos/plugin-imessage

Configuration

Environment Variables

Variable	Description	Required
IMESSAGE_CLI_PATH	Path to iMessage CLI tool	No
IMESSAGE_DB_PATH	Path to iMessage database	No
IMESSAGE_POLL_INTERVAL_MS	Polling interval in ms	No
IMESSAGE_DM_POLICY	DM policy: open, pairing, allowlist, disabled	No
IMESSAGE_GROUP_POLICY	Group policy: open, allowlist, disabled	No
IMESSAGE_ALLOW_FROM	Comma-separated handles for allowlist	No
IMESSAGE_ENABLED	Enable/disable the plugin	No
IMESSAGE_BACKFILL	Rows before current DB tip to replay on startup	No

Agent Configuration

{
  "plugins": ["@elizaos/plugin-imessage"],
  "pluginParameters": {
    "IMESSAGE_DM_POLICY": "pairing",
    "IMESSAGE_GROUP_POLICY": "allowlist",
    "IMESSAGE_POLL_INTERVAL_MS": "5000"
  }
}

Setup

Permissions

1. Open System Settings > Privacy & Security > Full Disk Access
2. Grant Full Disk Access to:
   • Your terminal app (or the Eliza process)
3. Allow Messages app to be controlled via AppleScript (Automation permission)

CLI Tool (Optional)

For enhanced functionality, you can use an iMessage CLI tool (e.g. imsg). Set the path once installed:

IMESSAGE_CLI_PATH=/usr/local/bin/imsg

Usage

Actions

iMessage sending is exposed through the canonical message connector action. Use source: "imessage" when a request needs to target iMessage explicitly.

Primary action	Operation	Description
MESSAGE	send	Send a text message to a phone number, email, contact, or chat

Providers

iMessage does not register standalone planner providers. Chat and contact context is exposed through the iMessage message connector hooks.

How It Works

The plugin uses two methods to interact with iMessage:

1. AppleScript (default): Uses macOS's built-in scripting support to send messages through the Messages app
2. CLI Tool (optional): Uses a command-line tool for more features

AppleScript Method

tell application "Messages"
  set targetService to 1st account whose service type = iMessage
  set targetBuddy to participant "+1234567890" of targetService
  send "Hello!" to targetBuddy
end tell

Message Targets

iMessage supports multiple target types:

• Phone Numbers: +1234567890, 1234567890
• Email Addresses: user@example.com
• Chat IDs: chat_id:UUID (for existing chats)

Policies

DM Policies

Policy	Description
open	Accept DMs from anyone
pairing	Accept DMs and remember senders
allowlist	Only accept from IMESSAGE_ALLOW_FROM list
disabled	Don't accept any DMs

Group Policies

Policy	Description
open	Respond to anyone in groups
allowlist	Only respond to allowed users
disabled	Don't respond in groups

Limitations

• macOS Only: iMessage doesn't have an official API and only works on macOS
• No Official API: Sending still relies on AppleScript or CLI tools
• Permissions: Message history requires Full Disk Access, sending through Messages requires Automation, and contact resolution/editing requires Contacts access
• Rate Limits: Apple may throttle excessive automation

Development

Building

bun run --cwd plugins/plugin-imessage build

Testing

Testing requires a macOS environment with Messages app configured:

bun run --cwd plugins/plugin-imessage test

Troubleshooting

"Cannot access Messages app"

1. Ensure Full Disk Access is granted
2. Ensure Automation permissions are granted if sending through Messages fails
3. Try opening Messages app manually first

"Service not available"

1. Check that you're running on macOS
2. Verify the Messages app is installed and configured

Messages not sending

1. Check that iMessage is signed in and working
2. Verify the recipient has iMessage enabled
3. Check for rate limiting (try again later)