iMessage Media, Attachments, and Delivery Targets
Explains iMessage attachment ingestion in both directions, outbound text chunking, and supported delivery targets. Useful for operators configuring media handling and attachment roots.
Read this when
- Enabling inbound attachments
- Tuning outbound text chunking
- Choosing an addressing format for a send
Attachment flow in both directions, how outbound text gets split, and the delivery targets iMessage supports.
Media, chunking, and delivery targets
Attachments and media
- incoming attachment handling is disabled unless enabled, turn on
channels.imessage.includeAttachments: trueto pass photos, voice memos, video, and similar files through to the agent. While it stays off, iMessages that contain only an attachment are discarded before the agent sees them and might leave noInbound messagelog entry whatsoever. - when
remoteHostis set, remote inbound attachment paths can be retrieved over SCP - outbound files are placed in an owner-only temporary location on the Messages Mac (configured or auto-detected), handed to
imsgas that remote path, then removed on a best-effort basis whether the send succeeds, fails, or times out; a failed cleanup logs a warning and may leave owner-only files behind - attachment paths have to fall under permitted roots:
channels.imessage.attachmentRoots(local)channels.imessage.remoteAttachmentRoots(remote SCP mode)- roots you configure are added to the default root pattern
/Users/*/Library/Messages/Attachmentsrather than substituting for it
- host-key checking in SCP is strict (
StrictHostKeyChecking=yes) - the size limit for outbound media comes from
channels.imessage.mediaMaxMb(16 MB by default)
Outbound text and chunking
- limit per text chunk:
channels.imessage.textChunkLimit(4000 by default) - chunk mode:
channels.imessage.streaming.chunkModelength(default)newline(splits on paragraphs first)
- bold, italic, underline, and strikethrough in outbound markdown become native styled text (recipients on macOS 15+ see the styling; on older versions the text arrives plain, with no markers); markdown tables are converted according to the channel markdown table mode
channels.imessage.sendTransport(autoby default,bridge,applescript) determines howimsgperforms sends
Addressing formats
Explicit targets are preferred:
chat_id:123(best choice when routing must stay stable)chat_guid:...chat_identifier:...
Direct handles work too:
+1555...tel:+1555...imessage:+1555...sms:+1555...user@example.com
For a contact name or a mixed alphanumeric alias, qualify the target with a service:
auto:<contact>leaves the iMessage-or-SMS choice to Messagesimessage:<contact>forces iMessagesms:<contact>forces SMS
Bare contact names and mixed alphanumeric aliases are refused rather than turned into a
phone number. If some existing automation relies on one, add auto:, imessage:, or sms: so
the delivery service you intend is stated explicitly.
imsg chats --limit 20