@photon-ai/imessage-kit

A type-safe, elegant iMessage SDK for macOS with cross-runtime support

A full-featured iMessage SDK for reading, sending, and automating iMessage conversations on macOS. Perfect for building AI agents, automation tools, and chat-first applications.

[!NOTE] ✨ Looking for advanced features like threaded replies, tapbacks, message editing, unsending, live typing indicators? Check out Advanced iMessage Kit and contact us at [email protected].

Features

| Feature | Method | Example | |---------|--------|---------| | Send Text | sdk.send() | 01-send-text.ts | | Send Image | sdk.send() | 02-send-image.ts | | Send File | sdk.send() | 03-send-file.ts | | Send to Group | sdk.send() | 04-send-group.ts | | Query Messages | sdk.getMessages() | 05-query-messages.ts | | List Chats | sdk.listChats() | 06-list-chats.ts | | Real-time Watching | sdk.startWatching() | 07-watch-messages.ts | | Auto Reply | onDirectMessage → sdk.send() | 08-auto-reply.ts | | Plugin System | sdk.use() | 10-plugin.ts | | Error Handling | IMessageError | 11-error-handling.ts |

Quick Start

Installation

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

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

Basic Usage

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

const sdk = new IMessageSDK()

// Send a text message
await sdk.send({ to: '+1234567890', text: 'Hello from iMessage Kit!' })

// Or use async-dispose to guarantee teardown:
await using disposable = new IMessageSDK()
await disposable.send({ to: '+1234567890', text: 'Hi!' })

// Manual teardown
await sdk.close()

Configuration

// Simplified; `readonly` modifiers omitted for readability — see src/types/config.ts
interface IMessageConfig {
    databasePath?: string        // Path to Messages SQLite database (default: ~/Library/Messages/chat.db)
    maxConcurrentSends?: number  // Concurrent send cap (default 10, range 1..50)
    sendTimeout?: number         // ms per AppleScript invocation (default 30_000, range 1_000..300_000)
    debug?: boolean              // Verbose SDK logs
    plugins?: Plugin[]           // Plugins registered at construction; sdk.use() is also available later
}

Out-of-range numeric values throw IMessageError(code: 'CONFIG') at construction — they are not silently clamped. The accepted ranges are exposed as the BOUNDS constant exported from the package root.

Granting Permission

IMessageKit requires Full Disk Access to read chat.db.

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click "+" and add your IDE or terminal (e.g., Cursor, VS Code, Terminal, Warp)

Send vs Observe Semantics

• sdk.send(request) returns Promise<void> that resolves when osascript exits successfully. It does not confirm the message landed in chat.db, nor does it return a Message object.
• To correlate your send with a chat.db row (and observe delivery transitions), subscribe to onFromMeMessage via the watcher — it fires for every from-me row observed, whether authored by this SDK, another Apple client, or Messages.app.

// Fire-and-forget send
await sdk.send({ to: '+1234567890', text: 'Hi' })

// Observe the landed row
await sdk.startWatching({
    onFromMeMessage: (msg) => console.log('Landed in chat.db:', msg.id, msg.isDelivered),
})

Messages

Examples: 01-send-text.ts | 02-send-image.ts | 03-send-file.ts | 05-query-messages.ts

Send Messages

sdk.send(request: SendRequest): Promise<void>

// Simplified; `readonly` modifiers omitted for readability — see src/types/send.ts
interface SendRequest {
    to: string                  // phone, email, or chatId
    text?: string
    attachments?: string[]      // local absolute paths; remote URLs are rejected
}

// Text
await sdk.send({ to: '+1234567890', text: 'Hello World!' })

// Email recipient
await sdk.send({ to: '[email protected]', text: 'Hello!' })

Send Attachments

// Local file paths only — download remote URLs yourself first.
await sdk.send({ to: '+1234567890', attachments: ['/abs/path/image.jpg'] })

// Text + multiple attachments — non-transactional: the first osascript call
// bundles text + attachments[0]; each later attachment is its own call with
// a ~500ms inter-step pacing. A mid-batch failure is labelled
// "attachment N/total".
await sdk.send({
    to: '+1234567890',
    text: 'Check this out',
    attachments: ['/abs/path/photo.jpg', '/abs/path/report.pdf']
})

Query Messages

const messages = await sdk.getMessages({
    chatId: 'any;+;chat534ce85d...',   // optional — scopes to one conversation
    participant: '+1234567890',
    service: 'iMessage',                // 'iMessage' | 'SMS' | 'RCS'
    isFromMe: false,                    // tri-state: omit → both
    isRead: false,                      // tri-state: omit → both
    hasAttachments: true,               // tri-state: omit → both
    excludeReactions: true,             // drop tapback/sticker rows
    since: new Date('2025-01-01'),
    before: new Date('2025-02-01'),
    search: 'meeting',                  // app-layer substring over decoded text
    limit: 20,
    offset: 0,
})

search runs in application layer over decoded attributedBody — there is no SQL LIKE index. Narrow with chatId / participant / since / limit on large databases.

Chats

Examples: 04-send-group.ts | 06-list-chats.ts

List Chats

const chats = await sdk.listChats({
    chatId: 'any;+;chat...',   // optional — scope to one chat
    kind: 'group',              // 'group' | 'dm'
    service: 'iMessage',
    isArchived: false,
    hasUnread: true,
    sortBy: 'recent',           // 'recent' | 'name'
    search: 'Project',          // LIKE over display_name / chat_identifier (escaped)
    limit: 20,
    offset: 0,
})

for (const chat of chats) {
    console.log({
        chatId: chat.chatId,
        name: chat.name,
        kind: chat.kind,
        unread: chat.unreadCount,
        lastMessageAt: chat.lastMessageAt,
    })
}

Send to Groups

Never hand-write a group chatId. Always use one surfaced by the SDK.

// From listChats
const groups = await sdk.listChats({ kind: 'group' })
await sdk.send({ to: groups[0].chatId, text: 'Hello group!' })

// From the watcher
await sdk.startWatching({
    onGroupMessage: async (msg) => {
        if (msg.chatId) await sdk.send({ to: msg.chatId, text: 'ack' })
    }
})

ChatId Formats

| Format | Example | Used for | |--------|---------|----------| | DM bare address | +1234567890 / [email protected] | DM routing; SDK prefixes internally | | DM prefixed | iMessage;-;+1234567890 | Canonical DM chatId | | Group (macOS 26+) | any;+;chat534ce85d... | Group chat (current) | | Group (legacy) | iMessage;+;chat534ce85d... | Pre-macOS-26 group chat | | Group (bare GUID) | chat45e2b868... | Accepted as input; SDK prefixes internally |

Parse / validate directly via the exported value object when needed:

import { ChatId, resolveTarget } from '@photon-ai/imessage-kit'

const cid = ChatId.fromUserInput('iMessage;-;[email protected]')
cid.isGroup            // false
cid.coreIdentifier     // '[email protected]'

const target = resolveTarget('+1234567890')   // MessageTarget (dm | group)

Real-time Events

Examples: 07-watch-messages.ts | 08-auto-reply.ts | 09-get-sent-message.ts

Real-time Watching

sdk.startWatching(events) accepts five callbacks. Calling it while a watcher is already running throws IMessageError(code: 'CONFIG', message: 'Watcher is already running') — stop it first.

await sdk.startWatching({
    onIncomingMessage: (msg) => { /* every incoming (non-from-me) row */ },
    onDirectMessage:   (msg) => { /* incoming DMs only */ },
    onGroupMessage:    (msg) => { /* incoming group messages only */ },
    onFromMeMessage:   (msg) => { /* any from-me row — this SDK or another client */ },
    onError:           (err) => { /* dispatch errors */ },
})

await sdk.stopWatching()   // safe to call even if never started

Auto Reply

await sdk.startWatching({
    onDirectMessage: async (msg) => {
        if (!msg.text || !/hello/i.test(msg.text)) return
        if (!msg.chatId) return   // rare WAL race before chat_message_join flushes
        await sdk.send({ to: msg.chatId, text: 'Hi there!' })
    }
})

Attachments

Examples: 02-send-image.ts | 03-send-file.ts

Attachment Helpers

Only iMessage-specific helpers are exported. For copy / read / stat, use node:fs directly against attachment.localPath.

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

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

if (attachment && await attachmentExists(attachment)) {
    if (isImageAttachment(attachment)) {
        const ext = getAttachmentExtension(attachment)   // lowercase, no leading dot — e.g. 'jpg'
        // Use node:fs for anything further (copyFile, createReadStream, stat, …)
    }
}

Plugin System

Example: 10-plugin.ts · reference logger: logger-plugin.ts

sdk.use(plugin) can be called before or after sdk is initialized — late registrations are joined to the pipeline on the next hook. Plugins are torn down on sdk.close().

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

const audit = definePlugin({
    name: 'audit',
    version: '1.0.0',
    onBeforeSend: ({ request }) => {
        // Throw here to veto the send; cause is attached to IMessageError(SEND).
        if (request.text?.includes('forbidden')) throw new Error('blocked by policy')
    },
    onAfterSend: ({ request }) => {
        console.log('[audit] dispatched to', request.to)
    },
})

sdk.use(audit)

Hook contract

All 11 hooks, grouped by dispatch mode:

| Hook | Mode | Behaviour on throw | |------|------|--------------------| | onInit | sequential | Routed to onError | | onDestroy | sequential | Routed to onError | | onError | sequential | Logged once; not re-routed (prevents recursion) | | onBeforeMessageQuery | interrupting | Aborts getMessages with IMessageError(DATABASE) | | onBeforeChatQuery | interrupting | Aborts listChats with IMessageError(DATABASE) | | onBeforeSend | interrupting | Aborts send with IMessageError(SEND) — use as auth/policy gate | | onAfterMessageQuery | parallel | Routed to onError | | onAfterChatQuery | parallel | Routed to onError | | onAfterSend | parallel | Fires only on successful AppleScript dispatch | | onIncomingMessage | parallel | Every incoming row observed by the watcher | | onFromMe | parallel | Every from-me row observed — authoritative DB-arrival signal |

Naming quirk. The same from-me event surfaces as DispatchEvents.onFromMeMessage (user callback passed to startWatching) and PluginHooks.onFromMe (plugin entry point). They are intentionally distinct to mark the "inline handler" vs "plugin observer" boundary.

Error Handling

Example: 11-error-handling.ts

All SDK failures surface as IMessageError with a typed code.

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

try {
    await sdk.send({ to: '+1234567890', text: 'Hello' })
} catch (error) {
    if (error instanceof IMessageError) {
        // error.code: 'PLATFORM' | 'DATABASE' | 'SEND' | 'CONFIG'
        // error.cause: original thrown Error (when applicable)
        console.error(`[${error.code}] ${error.message}`)
    }
}

IMessageError codes map to failure classes:

• PLATFORM — non-darwin runtime, or missing $HOME (only raised by requireMacOS() / getDefaultDatabasePath())
• DATABASE — SQLite open failure, query errors, decoder issues, or onBeforeMessageQuery / onBeforeChatQuery plugin veto
• SEND — AppleScript dispatch failure, osascript non-zero exit, Messages.app not running, attachment unreadable, send cancellation, or onBeforeSend plugin veto
• CONFIG — out-of-bounds config, malformed chatId, SDK already destroyed, watcher already running, duplicate plugin name

Examples

Run any example with Bun (requires macOS and Full Disk Access):

bun run examples/01-send-text.ts

Getting Started

• 01-send-text.ts — basic text message
• 02-send-image.ts — send an image attachment
• 03-send-file.ts — send an arbitrary file

Message Operations

• 05-query-messages.ts — filter history
• 09-get-sent-message.ts — correlate a send with its chat.db row

Chats & Groups

• 04-send-group.ts — send to a group
• 06-list-chats.ts — list conversations

Real-time & Automation

• 07-watch-messages.ts — watcher lifecycle
• 08-auto-reply.ts — auto-reply bot

Advanced

• 10-plugin.ts — custom plugin
• 11-error-handling.ts — IMessageError handling
• logger-plugin.ts — a reference logger plugin to adapt

API Reference

Core Methods

| Method | Description | |--------|-------------| | new IMessageSDK(config?) | Construct the SDK (sync). Opens the DB lazily. | | sdk.use(plugin) | Register a plugin; valid before or after init. | | sdk.getMessages(query?) | Query historical messages. Returns Message[]. | | sdk.listChats(query?) | Query chat summaries. Returns Chat[]. | | sdk.send(request) | Dispatch a send via AppleScript. Resolves on osascript exit. | | sdk.startWatching(events) | Begin WAL-based real-time watching. Throws IMessageError(CONFIG) if a watcher is already live. | | sdk.stopWatching() | Stop the watcher. Safe when never started. | | sdk.close() | Tear down watcher, plugins, and DB. Concurrent callers share the in-flight teardown; teardown failures surface as AggregateError. | | await using sdk = new IMessageSDK() | Symbol.asyncDispose integration — auto-close on scope exit. |

Types

interface Message {
    rowId: number
    id: string
    text: string | null
    participant: string | null
    chatId: string | null
    chatKind: 'dm' | 'group' | 'unknown'
    service: 'iMessage' | 'SMS' | 'RCS' | null
    kind: 'text' | 'memberAdded' | 'memberRemoved' | 'nameChanged' | 'groupAction' | 'unknown'
    isFromMe: boolean
    isRead: boolean
    isSent: boolean
    isDelivered: boolean
    createdAt: Date
    deliveredAt: Date | null
    readAt: Date | null
    editedAt: Date | null
    retractedAt: Date | null
    reaction: Reaction | null
    attachments: Attachment[]
    // ...plus ~30 additional fields; see src/domain/message.ts for the full interface
}

Full types — Message, Chat, Attachment, Reaction, SendRequest, MessageQuery, ChatQuery, Plugin, PluginHooks, DispatchEvents, MessageTarget — are exported from the package root. See llms.txt for the condensed reference.

Requirements

• OS: macOS only
• Runtime: Node.js >= 20.0.0 or Bun >= 1.0.0
• Permissions: Full Disk Access

LLMs

Download llms.txt for language model context:

• Download llms.txt

Context7 MCP

• Context7 Docs

Add Context7 MCP to your IDE, then use:

use context7: photon-hq/imessage-kit

License

MIT License

Note: This SDK is for educational and development purposes. Always respect user privacy and follow Apple's terms of service.