一个功能齐全的 iMessage SDK，用于在 macOS 上读取、发送和自动化 iMessage 对话。非常适合构建 AI 智能体、自动化工具以及以聊天为首要的应用程序。

[!NOTE] ✨ 正在寻找高级功能，如线程回复、tapback（点赞反馈）、消息编辑、撤回、实时输入指示器？请查看 Advanced iMessage Kit 并联系 daniel@photon.codes。

---

功能

功能	方法	示例
发送消息	sdk.send()	01-send-text.ts
发送图片	sdk.send()	02-send-image.ts
发送文件	sdk.sendFile()	03-send-file.ts
发送给群组	sdk.send()	04-send-group.ts
查询消息	sdk.getMessages()	05-query-messages.ts
列出聊天	sdk.listChats()	06-list-chats.ts
实时监听	sdk.startWatching()	07-watch-messages.ts
自动回复	sdk.message()	08-auto-reply.ts
批量发送	sdk.sendBatch()	09-batch-send.ts
获取已发送消息	sdk.send()	10-get-sent-message.ts
插件系统	sdk.use()	11-plugin.ts
错误处理	SendError	12-error-handling.ts
监听自己的消息	sdk.startWatching()	13-watch-own-messages.ts
定时消息	MessageScheduler	14-scheduled-messages.ts
智能提醒	Reminders	15-smart-reminders.ts

---

快速开始

安装

# For Bun (zero dependencies)
bun add @photon-ai/imessage-kit

# For Node.js (requires better-sqlite3)
npm install @photon-ai/imessage-kit better-sqlite3

基本用法

import { IMessageSDK } from '@photon-ai/imessage-kit'

const sdk = new IMessageSDK()

// Send a message
await sdk.send('+1234567890', 'Hello from iMessage Kit!')

// Clean up
await sdk.close()

配置

interface IMessageConfig {
    debug?: boolean              // Enable debug logging
    maxConcurrent?: number       // Max concurrent sends (default: 5)
    scriptTimeout?: number       // AppleScript timeout in ms
    databasePath?: string        // Custom database path
    plugins?: Plugin[]           // Plugins
    watcher?: {
        pollInterval?: number    // Polling interval (default: 2000)
        unreadOnly?: boolean     // Only watch unread (default: false)
        excludeOwnMessages?: boolean  // Exclude own messages (default: true)
    }
    webhook?: {
        url: string
        headers?: Record<string, string>
    }
}

授予权限

IMessageKit 需要完全磁盘访问权限才能读取您的聊天记录并执行自动化任务。

1. 打开 系统设置 → 隐私与安全性 → 完全磁盘访问
2. 点击 "+" 并添加您的 IDE 或终端（例如 Cursor, VS Code, Terminal, Warp）

---

消息

示例：01-send-text.ts | 02-send-image.ts | 03-send-file.ts | 05-query-messages.ts

发送消息

// Send text
await sdk.send('+1234567890', 'Hello World!')

// Send to email
await sdk.send('user@example.com', 'Hello!')

发送图片

// Send local images
await sdk.send('+1234567890', { 
    images: ['image1.jpg', 'image2.png'] 
})

// Send network images (auto-download)
await sdk.send('+1234567890', { 
    images: ['https://example.com/image.jpg'] 
})

// Text with images
await sdk.send('+1234567890', { 
    text: 'Check this out!',
    images: ['photo.jpg']
})

发送文件

// Send files (PDF, CSV, VCF, etc.)
await sdk.send('+1234567890', { 
    files: ['document.pdf', 'data.csv', 'contact.vcf'] 
})

// Convenience methods
await sdk.sendFile('+1234567890', '/path/to/document.pdf')
await sdk.sendFiles('+1234567890', ['file1.pdf', 'file2.csv'], 'Multiple files')

查询消息

// Get messages with filters
const result = await sdk.getMessages({
    sender: '+1234567890',
    unreadOnly: true,
    limit: 20,
    since: new Date('2025-01-01'),
    search: 'meeting'
})

// Get unread messages grouped by sender
const unread = await sdk.getUnreadMessages()
console.log(`${unread.total} unread from ${unread.senderCount} senders`)

---

聊天

示例：04-send-group.ts | 06-list-chats.ts

列出聊天

// Get all chats
const all = await sdk.listChats()

// Filter chats
const groups = await sdk.listChats({
    type: 'group',
    hasUnread: true,
    sortBy: 'recent',
    search: 'Project',
    limit: 20
})

// Each chat includes
for (const chat of groups) {
    console.log({
        chatId: chat.chatId,
        name: chat.displayName,
        isGroup: chat.isGroup,
        unread: chat.unreadCount
    })
}

发送给群组

// Get group chatId from listChats()
const groups = await sdk.listChats({ type: 'group' })
const chatId = groups[0].chatId  // e.g., 'chat45e2b868...'

// Send to group
await sdk.send(chatId, 'Hello group!')
await sdk.send(chatId, {
    text: 'Check these files',
    files: ['report.pdf']
})

---

实时事件

示例：07-watch-messages.ts | 08-auto-reply.ts | 13-watch-own-messages.ts

实时监听

await sdk.startWatching({
    // All messages
    onMessage: (msg) => {
        console.log(`New: ${msg.text}`)
    },
    
    // DMs only
    onDirectMessage: (msg) => {
        console.log(`DM from ${msg.sender}`)
    },
    
    // Groups only
    onGroupMessage: (msg) => {
        console.log(`Group: ${msg.chatId}`)
    },
    
    onError: (error) => {
        console.error(error)
    }
})

// Stop watching
sdk.stopWatching()

自动回复

await sdk.startWatching({
    onDirectMessage: async (msg) => {
        await sdk.message(msg)
            .ifFromOthers()
            .matchText(/hello/i)
            .replyText('Hi there!')
            .execute()
    }
})

消息链式 API

await sdk.message(msg)
    .ifUnread()
    .ifNotReaction()   // Skip tapback reactions
    .ifGroupChat()
    .when(m => m.sender.startsWith('+1'))
    .matchText(/photo/i)
    .replyImage(['photo.jpg'])
    .execute()

---

附件

示例：02-send-image.ts | 03-send-file.ts

附件辅助函数

import {
    attachmentExists,
    downloadAttachment,
    getAttachmentSize,
    isImageAttachment,
    isVideoAttachment,
    isAudioAttachment
} from '@photon-ai/imessage-kit'

const msg = await sdk.getMessages({ hasAttachments: true, limit: 1 })
const attachment = msg.messages[0].attachments[0]

if (await attachmentExists(attachment)) {
    const size = await getAttachmentSize(attachment)
    
    if (isImageAttachment(attachment)) {
        await downloadAttachment(attachment, '/path/to/save.jpg')
    }
}

支持的文件类型

• 文档：PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, RTF
• 图片：JPG, PNG, GIF, HEIC, WEBP, AVIF
• 联系人卡片：VCF (vCard)
• 数据文件：CSV, JSON, XML
• 压缩包：ZIP, RAR, 7Z
• 媒体：MP4, MOV, MP3, M4A

---

定时发送

示例：14-scheduled-messages.ts | 15-smart-reminders.ts

定时消息

import { IMessageSDK, MessageScheduler } from '@photon-ai/imessage-kit'

const sdk = new IMessageSDK()
const scheduler = new MessageScheduler(sdk, { debug: true }, {
    onSent: (msg, result) => console.log(`✅ Sent: ${msg.id}`),
    onError: (msg, error) => console.error(`❌ Failed: ${error.message}`),
    onComplete: (msg) => console.log(`🏁 Completed: ${msg.id}`)
})

// One-time message
const id = scheduler.schedule({
    to: '+1234567890',
    content: 'Reminder!',
    sendAt: new Date(Date.now() + 5 * 60 * 1000)  // 5 minutes
})

// Recurring daily
scheduler.scheduleRecurring({
    to: '+1234567890',
    content: 'Good morning! ☀️',
    startAt: new Date('2025-01-01T08:00:00'),
    interval: 'daily',  // 'hourly' | 'daily' | 'weekly' | 'monthly' | number
    endAt: new Date('2025-12-31')
})

// Manage
scheduler.reschedule(id, newDate)
scheduler.cancel(id)
scheduler.getPending()

// Persistence
const data = scheduler.export()
scheduler.import(data)

// Cleanup
scheduler.destroy()

智能提醒

一个支持自然语言的人类友好定时调度封装：

import { IMessageSDK, Reminders } from '@photon-ai/imessage-kit'

const sdk = new IMessageSDK()
const reminders = new Reminders(sdk)

// Relative time
reminders.in('5 minutes', '+1234567890', 'Take a break!')
reminders.in('2 hours', '+1234567890', 'Call the client')
reminders.in('1 day', '+1234567890', 'Follow up')

// Specific time
reminders.at('5pm', '+1234567890', 'End of day review')
reminders.at('tomorrow 9am', '+1234567890', 'Morning standup')
reminders.at('friday 2pm', '+1234567890', 'Weekly sync')

// Exact date
reminders.exact(new Date('2025-12-25T10:00:00'), '+1234567890', 'Merry Christmas!')

// Manage
reminders.list()    // List pending
reminders.count()   // Count pending
reminders.cancel(id)
reminders.destroy()

支持的格式：

• 时长："5 minutes", "2 hours", "1 day", "30 seconds", "1 week"
• 时间："5pm", "5:30pm", "17:30"
• 日期 + 时间："tomorrow 9am", "friday 2pm"

---

插件系统

示例：11-plugin.ts

import { loggerPlugin } from '@photon-ai/imessage-kit'

// Built-in logger
sdk.use(loggerPlugin({
    level: 'info',
    colored: true
}))

// Custom plugin
sdk.use({
    name: 'my-plugin',
    onInit: async () => console.log('Initialized'),
    onBeforeSend: async (to, content) => {
        console.log('Sending to:', to)
        return { to, content }
    },
    onAfterSend: async (result) => {
        console.log('Sent:', result)
    },
    onDestroy: async () => console.log('Destroyed')
})

---

错误处理

示例：12-error-handling.ts

import { SendError, DatabaseError, PlatformError } from '@photon-ai/imessage-kit'

try {
    await sdk.send('+1234567890', 'Hello')
} catch (error) {
    if (error instanceof SendError) {
        console.error('Send failed:', error.message)
    } else if (error instanceof DatabaseError) {
        console.error('Database error:', error.message)
    } else if (error instanceof PlatformError) {
        console.error('Platform error:', error.message)
    }
}

---

示例

使用 Bun 运行任意示例：

bun run examples/<filename>.ts

入门

• 01-send-text.ts - 基础文本消息
• 02-send-image.ts - 发送图片
• 03-send-file.ts - 发送文件

消息操作

• 05-query-messages.ts - 查询消息
• 09-batch-send.ts - 批量发送
• 10-get-sent-message.ts - 获取已发送消息

聊天与群组

• 04-send-group.ts - 发送到群组
• 06-list-chats.ts - 列出聊天

实时与自动化

• 07-watch-messages.ts - 监听消息
• 08-auto-reply.ts - 自动回复机器人
• 13-watch-own-messages.ts - 监听自己的消息

定时任务

• 14-scheduled-messages.ts - 定时消息
• 15-smart-reminders.ts - 智能提醒

高级功能

• 11-plugin.ts - 自定义插件
• 12-error-handling.ts - 错误处理

---

API 参考

核心方法

方法	描述
getMessages(filter?)	使用过滤器查询消息
getUnreadMessages()	按发送者分组获取未读消息
listChats(options?)	列出聊天（支持过滤/排序）
send(to, content)	发送文本、图片及/或文件
sendFile(to, path, text?)	发送单个文件
sendFiles(to, paths, text?)	发送多个文件
sendBatch(messages)	并发发送多条消息
message(msg)	创建消息处理链
startWatching(events?)	开始监控新消息
stopWatching()	停止监控
use(plugin)	注册插件
close()	关闭 SDK（软件开发工具包）并释放资源

类型

interface Message {
    id: string
    guid: string
    text: string | null
    sender: string
    senderName: string | null
    chatId: string
    isGroupChat: boolean
    isFromMe: boolean
    isRead: boolean
    service: 'iMessage' | 'SMS' | 'RCS'
    attachments: Attachment[]
    date: Date
    // Reaction fields
    isReaction: boolean
    reactionType: 'love' | 'like' | 'dislike' | 'laugh' | 'emphasize' | 'question' | null
    isReactionRemoval: boolean
    associatedMessageGuid: string | null
}

interface SendResult {
    sentAt: Date
    message?: Message  // Available if watcher is running
}

---

要求

• 操作系统：仅限 macOS
• 运行环境：Node.js >= 18.0.0 或 Bun >= 1.0.0
• 权限：完全磁盘访问权限

---

大语言模型 (LLMs)

下载 llms.txt 以获取语言模型上下文：

• Download llms.txt

Context7 MCP

• Context7 Docs

将 Context7 MCP 添加到您的集成开发环境 (IDE)，然后使用：

use context7: photon-hq/imessage-kit

---

许可证

MIT License

---

注意：本 SDK（软件开发工具包）仅供教育和开发用途。请始终尊重用户隐私并遵守 Apple 的服务条款。

imessage-kit 快速上手指南

@photon-ai/imessage-kit 是一个专为 macOS 设计的类型安全、优雅的 iMessage SDK。支持读取、发送和自动化处理 iMessage 对话，适用于构建 AI Agent、自动化工具及聊天优先的应用程序。

注意：本工具仅支持 macOS 系统。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

1. 操作系统：macOS
2. 运行环境：Node.js 或 Bun
3. 关键权限：必须授予 IDE 或终端 完全磁盘访问权限 (Full Disk Access)，以便读取聊天记录和执行自动化任务。

配置完全磁盘访问权限

1. 打开 系统设置 → 隐私与安全性 → 完全磁盘访问权限。
2. 点击 "+" 按钮。
3. 添加您的开发工具（例如 Cursor, VS Code, Terminal, Warp 等）。

安装步骤

根据您的包管理器选择以下命令进行安装：

# 使用 Bun 安装（零依赖）
bun add @photon-ai/imessage-kit

# 使用 Node.js 安装（需要 better-sqlite3）
npm install @photon-ai/imessage-kit better-sqlite3

基本使用

初始化 SDK 后即可发送消息或查询历史记录。以下是发送文本消息的最简示例：

import { IMessageSDK } from '@photon-ai/imessage-kit'

const sdk = new IMessageSDK()

// 发送消息
await sdk.send('+1234567890', 'Hello from iMessage Kit!')

// 清理资源
await sdk.close()

进阶配置

如需启用调试日志或自定义数据库路径，可在初始化时传入配置对象：

const sdk = new IMessageSDK({
    debug: true,
    databasePath: '/custom/path/database.db'
})

更多功能（如发送图片、文件、实时监听、定时消息等）请参考官方文档中的详细示例。