> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# iMessage media and attachments

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

## Media, chunking, and delivery targets

> **Attachments and media**
>
> * 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)

> **Outbound text and chunking**
>
> * 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

> **Addressing formats**
>
> 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.
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> imsg chats --limit 20
> ```