ContextQMD
Back to Eliza

iMessage Connector

packages/docs/connectors/imessage.md

2.0.17.3 KB
Original Source

iMessage Connector

Connect your agent to iMessage for private chats and group conversations on macOS using the @elizaos/plugin-imessage package.

Prerequisites

  • macOS with iMessage configured and signed in
  • Full Disk Access granted to the terminal or application running Eliza (for chat database access at ~/Library/Messages/chat.db)
  • A CLI tool for iMessage access — set the cliPath config field to the absolute path of the binary

Configuration

NameRequiredDescription
IMESSAGE_ENABLEDNoEnable or disable the connector
IMESSAGE_CLI_PATHNoPath to the iMessage CLI tool executable
IMESSAGE_DB_PATHNoPath to the iMessage database (default: ~/Library/Messages/chat.db)
IMESSAGE_DM_POLICYNoDM policy (e.g., allow, deny, allowlist)
IMESSAGE_ALLOW_FROMNoComma-separated allowed sender list
IMESSAGE_GROUP_POLICYNoGroup message policy
IMESSAGE_POLL_INTERVAL_MSNoPolling interval in milliseconds

The connector auto-enables when cliPath is truthy in the connector config and enabled is not explicitly false.

Configure in ~/.eliza/eliza.json:

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

To disable:

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

Setup

  1. Ensure macOS has iMessage configured and signed in.
  2. Grant Full Disk Access to the terminal or Eliza process (System Settings > Privacy & Security > Full Disk Access).
  3. Install an iMessage CLI tool and note its path.
  4. Add the CLI path to connectors.imessage.cliPath in your config.
  5. Start your agent -- the iMessage connector will auto-enable.

Features

Environment Variables

VariableDescription
IMESSAGE_CLI_PATHPath to the iMessage CLI tool executable
IMESSAGE_DB_PATHPath to the iMessage database
IMESSAGE_ENABLEDSet to true to enable
IMESSAGE_DM_POLICYDM access policy
IMESSAGE_ALLOW_FROMComma-separated list of allowed user IDs
IMESSAGE_GROUP_POLICYGroup join policy
IMESSAGE_POLL_INTERVAL_MSPolling interval in milliseconds

Environment Variables

VariableRequiredDescription
IMESSAGE_CLI_PATHNoPath to the iMessage CLI tool executable
IMESSAGE_DB_PATHNoPath to the iMessage database
IMESSAGE_ENABLEDNoEnable or disable the connector
IMESSAGE_DM_POLICYNoDM policy (e.g., allow, deny, allowlist)
IMESSAGE_ALLOW_FROMNoComma-separated allowed sender list
IMESSAGE_GROUP_POLICYNoGroup message policy
IMESSAGE_POLL_INTERVAL_MSNoPolling interval in milliseconds

Full Configuration Reference

All fields are defined under connectors.imessage in eliza.json.

Core Fields

FieldTypeDefaultDescription
cliPathstring—Path to the iMessage CLI tool executable
dbPathstring—Path to the iMessage database (default: ~/Library/Messages/chat.db)
remoteHoststring—Remote Mac hostname for SSH-based iMessage access
service"imessage" | "sms" | "auto"—Message service selection. "auto" detects the appropriate service
regionstring—Region configuration for phone number formatting
namestring—Account display name
enabledboolean—Explicitly enable/disable
capabilitiesstring[]—Capability flags
includeAttachmentsboolean—Include attachments in messages
configWritesboolean—Allow config writes from iMessage events
dmPolicy"pairing" | "allowlist" | "open" | "disabled""pairing"DM access policy. "open" requires allowFrom to include "*"
allowFrom(string|number)[]—User IDs allowed to DM
groupPolicy"open" | "disabled" | "allowlist""allowlist"Group join policy
groupAllowFrom(string|number)[]—User IDs allowed in groups
historyLimitinteger >= 0—Max messages in context
dmHistoryLimitinteger >= 0—History limit for DMs
dmsobject—Per-DM history overrides keyed by DM ID. Each value: {historyLimit?: int}
textChunkLimitinteger > 0—Max characters per message chunk
chunkMode"length" | "newline"—Long message splitting strategy
mediaMaxMbinteger > 0—Max media file size in MB
markdownobject—Table rendering: tables can be "off", "bullets", or "code"

Streaming Configuration

FieldTypeDefaultDescription
blockStreamingboolean—Disable streaming entirely
blockStreamingCoalesceobject—Coalescing settings: minChars, maxChars, idleMs

Group Configuration

Per-group settings are defined under groups.<group-id>:

FieldTypeDescription
requireMentionbooleanOnly respond when @mentioned
toolsToolPolicySchemaTool access policy
toolsBySenderobjectPer-sender tool policies (keyed by sender ID)

Heartbeat

json
{
  "connectors": {
    "imessage": {
      "heartbeat": {
        "showOk": true,
        "showAlerts": true,
        "useIndicator": true
      }
    }
  }
}

Multi-Account Support

The accounts field allows running multiple iMessage accounts from a single agent:

json
{
  "connectors": {
    "imessage": {
      "accounts": {
        "personal": {
          "cliPath": "/usr/local/bin/imessage",
          "service": "imessage",
          "groups": {}
        },
        "work": {
          "cliPath": "/usr/local/bin/imessage",
          "remoteHost": "work-mac.local",
          "service": "auto",
          "groups": {}
        }
      }
    }
  }
}

Each account entry supports the same fields as the top-level connectors.imessage configuration (excluding the accounts field itself).

Remote Host Access

To connect to iMessage on a remote Mac via SSH, set the remoteHost field:

json
{
  "connectors": {
    "imessage": {
      "cliPath": "/usr/local/bin/imessage",
      "remoteHost": "mac-mini.local"
    }
  }
}

Ensure SSH key-based authentication is configured between the local machine and the remote host.

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.

macOS Only

The iMessage connector requires macOS. It will not function on Linux or Windows.