ContextQMD
Back to Eliza

iMessage Plugin

packages/docs/plugin-registry/platform/imessage.md

2.0.13.2 KB
Original Source

The iMessage plugin connects Eliza agents to iMessage on macOS, supporting both iMessage and SMS conversations with configurable service selection and attachment handling.

Package: @elizaos/plugin-imessage

Installation

bash
eliza plugins install @elizaos/plugin-imessage

Setup

1. Prerequisites

  • macOS with iMessage configured and signed in
  • Full Disk Access granted to the terminal or application running Eliza (for chat database access)

2. Configure Eliza

json
{
  "connectors": {
    "imessage": {
      "cliPath": "/usr/local/bin/imessage",
      "service": "auto",
      "dmPolicy": "pairing"
    }
  }
}

Configuration

FieldRequiredDescription
cliPathYesPath to the iMessage CLI tool executable (required to trigger auto-enable)
serviceNoService type: "imessage", "sms", or "auto"
dbPathNoPath to iMessage database (default: ~/Library/Messages/chat.db)
remoteHostNoRemote Mac hostname for SSH-based iMessage access
regionNoRegion configuration for phone number formatting
includeAttachmentsNoInclude attachments in messages
dmPolicyNoDM access policy: "pairing", "allowlist", "open", or "disabled" (default: "pairing")

Features

  • Service selection — Choose between iMessage, SMS, or automatic detection
  • Database access — Direct access to macOS iMessage database for message history
  • Remote host — Connect to iMessage on a remote Mac via SSH
  • Attachments — Send and receive media attachments
  • Per-group config — Configure mention requirements and tool access per group
  • Multi-account — Supports multiple accounts via accounts map

Environment Variables

VariableRequiredDescription
IMESSAGE_ENABLEDNoEnable or disable the connector
IMESSAGE_CLI_PATHNoPath to the iMessage CLI tool executable
IMESSAGE_DB_PATHNoPath to iMessage database (default: ~/Library/Messages/chat.db)
IMESSAGE_DM_POLICYNoDM access policy
IMESSAGE_ALLOW_FROMNoComma-separated allowed phone numbers/emails
IMESSAGE_GROUP_POLICYNoGroup message policy
IMESSAGE_POLL_INTERVAL_MSNoPolling interval in milliseconds

Auto-Enable

The plugin auto-enables when the connectors.imessage block contains a cliPath:

json
{
  "connectors": {
    "imessage": {
      "cliPath": "/usr/local/bin/imessage"
    }
  }
}

Troubleshooting

Full Disk Access

If message retrieval fails, ensure Full Disk Access is granted:

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Add the terminal application or Eliza process

Database Path

The default iMessage database is at ~/Library/Messages/chat.db. If using a non-standard location, set dbPath explicitly.