imessage-ts
Version:
TypeScript library for interacting with iMessage on macOS - send messages, monitor chats, and automate responses
119 lines (86 loc) • 2.76 kB
Markdown
A TypeScript library for interacting with the local iMessage database on macOS. This library allows you to:
- Monitor incoming messages in real-time
- Access conversation history and details
- Send new messages through iMessage
- Retrieve message attachments (images, files, etc.)
- Support for both individual and group chats
- **CLI tool for command-line access**
- **HTTP server with webhook support**
## Installation
```bash
npm install imessage-ts
# For CLI usage
npm install -g imessage-ts
```
## Requirements
- macOS (as iMessage is exclusive to Apple platforms)
- Node.js 14 or later
- An active Apple ID signed into iMessage
## Quick Start
### Library Usage
```typescript
import { IMessageClient } from 'imessage-ts';
// Initialize the client
const client = new IMessageClient();
// Listen for new messages
client.on('message', (message) => {
console.log(`New message from ${message.sender}: ${message.text}`);
});
// Get conversations
const conversations = await client.getConversations();
console.log(`You have ${conversations.length} conversations`);
// Send a message
await client.sendMessage({
text: 'Hello from Node.js!',
to: '+1234567890', // Phone number or email
});
```
```bash
imessage-ts send -t "+1234567890" -m "Hello from CLI!"
imessage-ts list-conversations
imessage-ts watch
imessage-ts run-server --webhook https://your-webhook.com
```
See [CLI_USAGE.md](./CLI_USAGE.md) for complete CLI documentation.
```typescript
// Get messages from a specific conversation
const messages = await client.getMessages({
conversationId: 'chat123456789',
limit: 50
});
// Get attachments
const attachments = await client.getAttachments({
messageId: 'message123456789'
});
// Send a message with an attachment
await client.sendMessage({
text: 'Check out this photo!',
to: '+1234567890',
attachments: ['/path/to/image.jpg']
});
// Listen for message read receipts
client.on('messageRead', (event) => {
console.log(`Message ${event.messageId} was read at ${event.readAt}`);
});
```
Start an HTTP server for programmatic access:
```bash
npx imessage-ts run-server --port 3000 --webhook https://your-webhook.com
curl -X POST http://localhost:3000/send \
-H "Content-Type: application/json" \
-d '{"to": "+1234567890", "text": "Hello from API!"}'
```
This package only accesses the local iMessage database on your machine and does not transmit your messages to any external servers. Authentication is handled through the existing macOS iMessage session.
MIT