iMessage¶

概述¶

iMessage Channel通过steipete/imsg库与macOS Messages.app集成，支持发送和接收iMessage/SMS消息。

官方文档: https://github.com/steipete/imsg
平台要求: macOS 14+
接入方式: JSON-RPC via imsg CLI
支持消息类型: 文本、文件、Tapback反应

配置参数¶

Config 结构体¶

type Config struct {
    DefaultService         string  // 默认消息服务
    Region                 string  // 地区代码
    EnableTypingIndicators bool    // 启用输入指示器
    EnableReactions        bool    // 启用Tapback反应
    WatchAllChats          bool    // 监听所有聊天
    IncludeReactions       bool    // 包含反应事件
}

参数详细说明¶

参数名	类型	必填	默认值	说明
`default_service`	string	否	"iMessage"	默认消息服务："iMessage"或"SMS"
`region`	string	否	"US"	电话号码地区代码
`enable_typing_indicators`	bool	否	false	启用输入状态指示（需imsg v0.5.0+）
`enable_reactions`	bool	否	false	启用Tapback反应（需imsg v0.5.0+）
`watch_all_chats`	bool	否	false	监听所有聊天会话
`include_reactions`	bool	否	false	在消息流中包含反应事件

default_service¶

数据类型: string
可选值: "iMessage", "SMS"
默认值: "iMessage"
说明: 默认使用的消息服务类型

region¶

数据类型: string
格式: ISO 3166-1 alpha-2 国家代码
默认值: "US"
用途: 电话号码格式化和验证

enabletypingindicators¶

数据类型: bool
要求: 需要imsg CLI v0.5.0或更高版本
功能: 显示对方正在输入的状态

enable_reactions¶

数据类型: bool
要求: 需要imsg CLI v0.5.0或更高版本
功能: 支持发送和接收Tapback反应（👍❤️等）

完整配置示例¶

YAML配置¶

channels:
  - name: imessage-channel
    type: imessage
    config:
      default_service: "iMessage"
      region: "US"
      enable_typing_indicators: true
      enable_reactions: true
      watch_all_chats: false
      include_reactions: true

Go代码配置¶

import (
    "github.com/example/gort/pkg/channel/imessage"
)

config := imessage.Config{
    DefaultService:         "iMessage",
    Region:                 "US",
    EnableTypingIndicators: true,
    EnableReactions:        true,
    WatchAllChats:          false,
    IncludeReactions:       true,
}

ch, err := imessage.NewChannel("imessage-channel", config)
if err != nil {
    log.Fatal(err)
}

前置要求¶

1. 系统要求¶

操作系统: macOS 14 (Sonoma) 或更高版本
硬件: Apple Silicon 或 Intel Mac
存储: 需要访问 ~/Library/Messages/chat.db

2. 安装imsg CLI¶

# 安装imsg CLI工具
go install github.com/steipete/imsg/cmd/imsg@latest

# 验证安装
which imsg
imsg --version

3. 系统权限配置¶

需要授予以下权限：

Full Disk Access (完全磁盘访问权限)
系统设置 → 隐私与安全性 → 完全磁盘访问
添加终端应用（iTerm/Terminal）
Automation (自动化权限)
系统设置 → 隐私与安全性 → 自动化
允许终端控制 Messages.app
Messages.app 登录
确保 Messages.app 已登录 Apple ID
启用 iMessage 服务

功能支持¶

消息类型¶

消息类型	支持状态	说明
文本消息	✅	iMessage/SMS文本
文件附件	✅	图片、文档等
Tapback反应	✅	👍❤️😂😮😢👎
输入指示器	✅	显示输入状态

能力矩阵¶

GetCapabilities() 返回:
- TextMessages:     true
- MarkdownMessages: false
- ImageMessages:    true
- FileMessages:     true
- AudioMessages:    true
- VideoMessages:    false
- LocationMessages: false
- ReactionMessages: true
- ReadReceipts:     true
- TypingIndicators: true

常见配置问题¶

问题1: 非macOS系统¶

现象: 返回"iMessage channel requires macOS"

原因: iMessage Channel只能在macOS上运行

解决: 此Channel仅支持macOS，无法在其他平台使用

问题2: imsg CLI未安装¶

现象: 返回"imsg CLI not installed"

原因: 未安装imsg CLI工具

解决:

# 安装imsg CLI
go install github.com/steipete/imsg/cmd/imsg@latest

# 确保$GOPATH/bin在PATH中
export PATH=$PATH:$(go env GOPATH)/bin

问题3: 权限被拒绝¶

现象: 返回"permission denied"

原因: 缺少Full Disk Access或Automation权限

解决: 1. 打开系统设置 → 隐私与安全性 2. 授予终端应用"完全磁盘访问"权限 3. 授予终端应用控制"Messages"的权限 4. 重启终端应用

问题4: 无法发送消息¶

现象: 消息发送失败或超时

原因: - Messages.app未登录 - 收件人电话号码/邮箱格式错误

解决:

// 确保使用正确的电话号码格式
msg := &message.Message{
    To: message.UserInfo{
        ID: "+1234567890",  // 国际格式
    },
}

发送消息示例¶

发送文本消息¶

msg := &message.Message{
    ID:        "msg-1",
    ChannelID: "imessage-channel",
    Direction: message.DirectionOutbound,
    To:        message.UserInfo{ID: "+1234567890"},  // 电话号码或邮箱
    Content:   "Hello from iMessage!",
    Type:      message.MessageTypeText,
}

err := ch.SendMessage(ctx, msg)

发送文件¶

fileData := []byte("file content...")
err := ch.SendFile(ctx, "+1234567890", fileData, "document.pdf")

发送Tapback反应¶

// 对某条消息发送反应
err := ch.SendReaction(ctx, "+1234567890", "message-id", "❤️")

安全建议¶

权限管理: 仅授予必要的系统权限
数据保护: iMessage数据存储在本地SQLite数据库
隐私合规: 遵守iMessage服务条款
访问控制: 限制对chat.db文件的访问

限制与注意事项¶

平台限制: 仅支持macOS
单设备: 依赖本地Messages.app数据库
Apple ID: 需要登录有效的Apple ID
同步延迟: 可能存在消息同步延迟

错误代码参考¶

错误	说明
`ErrNotMacOS`	非macOS系统
`ErrIMsgNotInstalled`	imsg CLI未安装
`ErrPermissionDenied`	缺少系统权限
`ErrNoActiveChat`	无有效聊天会话
`ErrInvalidPhoneNumber`	电话号码格式错误