Skip to main content
How attachments move in and out, how outbound text is chunked, and which delivery targets iMessage accepts.

​
Media, chunking, and delivery targets

  • inbound attachment ingestion is off by default — set channels.imessage.includeAttachments: true to forward photos, voice memos, video, and other attachments to the agent. With it disabled, attachment-only iMessages are dropped before reaching the agent and may produce no Inbound message log line at all.
  • remote inbound attachment paths can be fetched via SCP when remoteHost is set
  • outbound files are staged into an owner-only temporary path on the configured or auto-detected Messages Mac, passed to imsg by that remote path, and cleaned up best-effort after success, failure, or timeout; cleanup failure emits a warning and can leave owner-only residue
  • attachment paths must match allowed roots:
    • channels.imessage.attachmentRoots (local)
    • channels.imessage.remoteAttachmentRoots (remote SCP mode)
    • configured roots extend the default root pattern /Users/*/Library/Messages/Attachments (merged, not replaced)
  • SCP uses strict host-key checking (StrictHostKeyChecking=yes)
  • outbound media size uses channels.imessage.mediaMaxMb (default 16 MB)
  • text chunk limit: channels.imessage.textChunkLimit (default 4000)
  • chunk mode: channels.imessage.streaming.chunkMode
    • length (default)
    • newline (paragraph-first splitting)
  • outbound markdown bold/italic/underline/strikethrough is converted to native styled text (macOS 15+ recipients render the styling; older recipients see plain text without the markers); markdown tables are converted per the channel markdown table mode
  • channels.imessage.sendTransport (auto default, bridge, applescript) selects how imsg delivers sends
Preferred explicit targets:
  • chat_id:123 (recommended for stable routing)
  • chat_guid:...
  • chat_identifier:...
Direct handles are also supported:
  • +1555...
  • tel:+1555...
  • imessage:+1555...
  • sms:+1555...
  • user@example.com
Use a service-qualified target for a contact name or mixed alphanumeric alias:
  • auto:<contact> lets Messages choose iMessage or SMS
  • imessage:<contact> requires iMessage
  • sms:<contact> requires SMS
Bare contact names and mixed alphanumeric aliases are rejected instead of being converted to a phone number. If an existing automation uses one, add auto:, imessage:, or sms: to make the intended delivery service explicit.