iMessage (legacy: imsg)

For new iMessage deployments, use BlueBubbles.

The imsg integration is legacy and may be removed in a future release.

Status: legacy external CLI integration. Gateway spawns imsg rpc and communicates over JSON-RPC on stdio (no separate daemon/port).

💬

BlueBubbles (recommended)

Preferred iMessage path for new setups.

🔗

Pairing

iMessage DMs default to pairing mode.

⚙️

Configuration reference

Full iMessage field reference.

Quick setup

Install and verify imsg

bash
brew install steipete/tap/imsg
imsg rpc --help

Configure Mayros

json5
{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<you>/Library/Messages/chat.db",
    },
  },
}

Start gateway

bash
mayros gateway

Approve first DM pairing (default dmPolicy)

bash
mayros pairing list imessage
mayros pairing approve imessage <CODE>

Pairing requests expire after 1 hour.

Requirements and permissions (macOS)

Messages must be signed in on the Mac running imsg.
Full Disk Access is required for the process context running Mayros/imsg (Messages DB access).
Automation permission is required to send messages through Messages.app.

Permissions are granted per process context. If gateway runs headless (LaunchAgent/SSH), run a one-time interactive command in that same context to trigger prompts:

bash
imsg chats --limit 1
# or
imsg send <handle> "test"

Access control and routing

channels.imessage.dmPolicy controls direct messages:

pairing (default)
allowlist
open (requires allowFrom to include "*")
disabled

Allowlist field: channels.imessage.allowFrom.

Allowlist entries can be handles or chat targets (chat_id:*, chat_guid:*, chat_identifier:*).

Deployment patterns

Media, chunking, and delivery targets

Config writes

iMessage allows channel-initiated config writes by default (for /config set|unset when commands.config: true).

Disable:

json5
{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}