Back to Details

imessage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

iMessage Integration

iMessage 集成

Send and read iMessages/SMS using the 
imsg
CLI tool on macOS.
在macOS上使用
imsg
CLI工具发送和读取iMessage/SMS消息。

Setup

设置

1. Build the imsg CLI

1. 构建imsg CLI工具

Clone and build the tool:
bash
git clone https://github.com/letta-ai/imsg.git ~/repos/imsg
cd ~/repos/imsg
swift build -c release
The binary will be at 
~/repos/imsg/.build/release/imsg
(or use the pre-built binary if available at 
~/repos/imsg/bin/imsg
).
克隆并构建工具：
bash
git clone https://github.com/letta-ai/imsg.git ~/repos/imsg
cd ~/repos/imsg
swift build -c release
二进制文件将位于
~/repos/imsg/.build/release/imsg
（如果
~/repos/imsg/bin/imsg
有预构建二进制文件，也可直接使用）。

2. Grant Permissions

2. 授予权限

Required macOS permissions (System Settings → Privacy & Security):
PermissionLocationRequired For
Full Disk AccessPrivacy & Security → Full Disk AccessReading message history
AutomationPrivacy & Security → AutomationSending messages via Messages.app
需要的macOS权限（系统设置 → 隐私与安全性）：
权限位置用途
完全磁盘访问隐私与安全性 → 完全磁盘访问读取消息历史
自动化隐私与安全性 → 自动化通过Messages.app发送消息

3. Enable SMS Relay (Optional)

3. 启用SMS中继（可选）

To send SMS (green bubbles) to non-iMessage users:
  1. On iPhone: Settings → Messages → Text Message Forwarding
  2. Enable forwarding to your Mac
要向非iMessage用户发送SMS（绿色气泡消息）：
  1. 在iPhone上：设置 → 消息 → 短信转发
  2. 启用向你的Mac转发短信

Commands

命令

List Recent Chats

列出最近对话

bash
imsg chats --limit 10
imsg chats --limit 10 --json
Output format: 
[chat_id] (identifier) last=timestamp
bash
imsg chats --limit 10
imsg chats --limit 10 --json
输出格式：
[chat_id] (标识符) last=时间戳

View Chat History

查看对话历史

bash
undefined
bash
undefined

View last 20 messages in a chat

查看对话中最近20条消息

imsg history --chat-id <id> --limit 20
imsg history --chat-id <id> --limit 20

With attachments metadata

包含附件元数据

imsg history --chat-id <id> --limit 20 --attachments
imsg history --chat-id <id> --limit 20 --attachments

Filter by date

按日期筛选

imsg history --chat-id <id> --start 2026-01-01T00:00:00Z --json
undefined
imsg history --chat-id <id> --start 2026-01-01T00:00:00Z --json
undefined

Send a Message

发送消息

bash
undefined
bash
undefined

Send to phone number

发送到电话号码

imsg send --to "+15555555555" --text "Hello!"
imsg send --to "+15555555555" --text "Hello!"

Send with attachment

发送带附件的消息

imsg send --to "+15555555555" --text "Here's the file" --file /path/to/file.jpg
imsg send --to "+15555555555" --text "Here's the file" --file /path/to/file.jpg

Force iMessage or SMS

强制使用iMessage或SMS

imsg send --to "+15555555555" --text "Hi" --service imessage imsg send --to "+15555555555" --text "Hi" --service sms
imsg send --to "+15555555555" --text "Hi" --service imessage imsg send --to "+15555555555" --text "Hi" --service sms

Send to existing chat by ID

通过现有对话ID发送消息

imsg send --chat-id 86 --text "Hello!"
undefined
imsg send --chat-id 86 --text "Hello!"
undefined

Watch for New Messages

监听新消息

bash
imsg watch --chat-id <id> --debounce 250ms
bash
imsg watch --chat-id <id> --debounce 250ms

Best Practices

最佳实践

Phone Number Format

电话号码格式

  • Use E.164 format: 
    +1XXXXXXXXXX
    for US numbers
  • Include country code for international
  • 使用E.164格式：美国号码为
    +1XXXXXXXXXX
  • 国际号码需包含国家代码

SMS vs iMessage

SMS 与 iMessage

  • iMessage (blue bubble): Default for Apple device users, free
  • SMS (green bubble): Requires iPhone relay, may have carrier charges
  • Use 
    --service sms
    when recipient doesn't have iMessage
  • iMessage（蓝色气泡）：苹果设备用户默认选项，免费
  • SMS（绿色气泡）：需要iPhone中继，可能产生运营商费用
  • 当收件人没有iMessage时，使用
    --service sms
    参数

Message Etiquette for Agents

Agent消息礼仪

  • Be concise - Keep messages short and clear
  • Be human - Write naturally, not robotically
  • Identify context - If following up, reference previous conversation
  • Respect timing - Avoid early morning/late night messages
  • 简洁明了 - 保持消息简短清晰
  • 贴近人类语气 - 用自然的语气撰写，不要像机器人
  • 明确上下文 - 如果是跟进消息，提及之前的对话内容
  • 注意时间 - 避免在清晨或深夜发送消息

Common Use Cases

常见用例

Scheduling Services

服务预约

bash
imsg send --to "+14155551234" --text "Hi! Do you have availability this Saturday for a cleaning?"
bash
imsg send --to "+14155551234" --text "Hi! Do you have availability this Saturday for a cleaning?"

Following Up

跟进消息

bash
imsg send --to "+14155551234" --text "Just wanted to follow up on my earlier message. Let me know when you have a chance!"
bash
imsg send --to "+14155551234" --text "Just wanted to follow up on my earlier message. Let me know when you have a chance!"

Confirming Appointments

确认预约

bash
imsg send --to "+14155551234" --text "Confirming our appointment for Saturday at 10am. See you then!"
bash
imsg send --to "+14155551234" --text "Confirming our appointment for Saturday at 10am. See you then!"

Troubleshooting

故障排除

IssueSolution
"not authorized" errorGrant Automation permission to terminal
Can't read messagesGrant Full Disk Access to terminal
SMS not sendingEnable Text Message Forwarding on iPhone
Message stuck sendingCheck Messages.app is signed in and working
问题解决方案
"not authorized"错误给终端授予自动化权限
无法读取消息给终端授予完全磁盘访问权限
SMS无法发送在iPhone上启用短信转发
消息发送卡住检查Messages.app是否已登录且正常工作

Technical Notes

技术说明

  • Uses AppleScript for sending (no private APIs)
  • Read operations are read-only on the Messages SQLite database
  • Requires macOS 14+ with Messages.app configured
  • Binary location: 
    ~/repos/imsg/bin/imsg
    (adjust path as needed)
  • 使用AppleScript发送消息（无私有API）
  • 读取操作仅对Messages SQLite数据库进行只读访问
  • 需要macOS 14+且已配置Messages.app
  • 二进制文件位置：
    ~/repos/imsg/bin/imsg
    （可根据需要调整路径）