You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 4-6.RSVP
Socket
Book a DemoInstallSign in
Socket

imessage-ts

Package Overview
Dependencies
Maintainers
0
Versions
7
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

imessage-ts

TypeScript library for interacting with iMessage on macOS - send messages, monitor chats, and automate responses

0.2.5
latest
Source
npmnpm
Version published
Weekly downloads
487
Maintainers
0
Weekly downloads
 
Created
Source

iMessage-TS

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

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

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
});

CLI Usage

# Send a message
imessage-ts send -t "+1234567890" -m "Hello from CLI!"

# List conversations
imessage-ts list-conversations

# Watch for new messages
imessage-ts watch

# Run HTTP server with webhook support
imessage-ts run-server --webhook https://your-webhook.com

See CLI_USAGE.md for complete CLI documentation.

Advanced Features

// 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}`);
});

HTTP Server

Start an HTTP server for programmatic access:

# Start server
npx imessage-ts run-server --port 3000 --webhook https://your-webhook.com

# Send message via API
curl -X POST http://localhost:3000/send \
  -H "Content-Type: application/json" \
  -d '{"to": "+1234567890", "text": "Hello from API!"}'

Security & Privacy

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.

License

MIT

Keywords

imessage

FAQs

Package last updated on 30 Jul 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts