# iMessage Monitor
A Python library for monitoring and extracting iMessage data with real-time capabilities and beautiful terminal display.
## Features
- **Real-time monitoring** of incoming iMessages
- **Pretty-printed chat bubbles** with proper left/right alignment
- **Sticker and reaction support** with emoji display
- **ASCII art generation** for image attachments (optional)
- **Attachment handling** including HEIC conversion
- **Outbound messaging** via AppleScript or Shortcuts
- **Safe database access** with read-only mode
## Requirements
- **macOS only** (requires access to Messages database)
- **Python 3.11+**
- **Full Disk Access** permission for terminal/IDE
## Installation
```bash
pip install imessage-monitor
or
uv add imessage-monitor
```
## Quick Start
### Real-time Monitoring
```python
from imessage_monitor import iMessageMonitor
from imessage_monitor.display import pretty_print_bubble
def handle_message(message):
"""Handle new messages with pretty printing."""
print(pretty_print_bubble(message, show_ascii_art=True))
# Start monitoring
monitor = iMessageMonitor()
monitor.start(message_callback=handle_message)
# Keep running (in practice, you'd run this in an async loop)
input("Press Enter to stop...")
monitor.stop()
```
### Message Retrieval
```python
from imessage_monitor import iMessageMonitor, to_json
# Get recent messages
monitor = iMessageMonitor()
messages = monitor.get_recent_messages(limit=50)
# Convert to JSON
json_data = to_json(messages)
print(json_data)
```
### Sending Messages
```python
from imessage_monitor import ImessageOutbound
# Send via AppleScript
outbound = ImessageOutbound()
success = outbound.send_message_applescript("+1234567890", "Hello!")
# Send attachment
success = outbound.send_attachment_applescript("+1234567890", "/path/to/file.jpg")
```
## Display Options
The library provides three pretty-print formats:
### Chat Bubbles
```python
from imessage_monitor.display import pretty_print_bubble
# Basic bubble (no ASCII art)
print(pretty_print_bubble(message))
# With ASCII art for images
print(pretty_print_bubble(message, show_ascii_art=True))
```
### Reactions
```python
from imessage_monitor.display import pretty_print_reaction
print(pretty_print_reaction(message)) # Shows ❤️, 👍, 👎, etc.
```
### Stickers
```python
from imessage_monitor.display import pretty_print_sticker
print(pretty_print_sticker(message, show_ascii_art=True))
```
## Data Conversion
```python
from imessage_monitor import to_json, to_toml
# Convert messages to different formats
json_str = to_json(messages)
toml_str = to_toml(messages)
# Save to files
to_json(messages, "messages.json")
to_toml(messages, "messages.toml")
```
## Configuration
The library uses sensible defaults but can be configured:
```python
from imessage_monitor.config import Config
# Create custom config
config = Config.default()
config.monitoring.poll_interval_seconds = 1 # Faster polling
monitor = iMessageMonitor(config_path="path/to/config.toml")
```
### Contact Filtering
Filter messages by specific contacts with whitelist/blacklist functionality:
```python
from imessage_monitor import iMessageMonitor
from imessage_monitor.config import ContactFilter
# Create contact filter
contact_filter = ContactFilter(
outbound_behavior="whitelist", # Only include outbound messages to these contacts
outbound_ids=["+1234567890", "friend@example.com"],
inbound_behavior="blacklist", # Exclude inbound messages from these contacts
inbound_ids=["spam@example.com", "+9876543210"]
)
# Apply filter to message retrieval
config = Config.default()
config.contacts = contact_filter
monitor = iMessageMonitor()
filtered_messages = monitor.get_recent_messages(limit=100)
```
Contact filtering supports:
- **Chat-level filtering**: Group chats can be whitelisted/blacklisted by chat ID
- **Individual-level filtering**: Individual contacts filtered by phone/email
- **Precedence**: Chat-level filtering takes precedence over individual-level
- **Directional filtering**: Separate rules for inbound vs outbound messages
### Date Range Filtering
Filter messages by date range (applies to manual queries only, not monitoring):
```python
from imessage_monitor.config import DateRange
from datetime import datetime
# Custom date range
date_range = DateRange(
start_date=datetime(2024, 1, 1),
end_date=datetime(2024, 12, 31)
)
# Quick helpers
date_range = DateRange.from_days_back(7) # Last 7 days
date_range = DateRange.from_hours_back(24) # Last 24 hours
config = Config.default()
config.date_range = date_range
monitor = iMessageMonitor()
recent_messages = monitor.get_recent_messages(limit=100)
```
### Example TOML Configuration
```toml
[apple]
chat_db_path = "~/Library/Messages/chat.db"
attachments_path = "~/Library/Messages/Attachments"
permissions_check = true
[monitoring]
poll_interval_seconds = 20 # Used as backup if enable_real_time=true
max_batch_size = 1000
enable_real_time = true
[contacts]
outbound_behavior = "whitelist" # "whitelist" | "blacklist" | "none"
outbound_ids = ["+1234567890", "friend@example.com"]
inbound_behavior = "blacklist" # "whitelist" | "blacklist" | "none"
inbound_ids = ["spam@example.com", "+9876543210"]
[date_range] # Ignored when monitoring
start_date = "2024-01-01T00:00:00"
end_date = "2024-12-31T23:59:59"
[outbound]
method = "applescript"
rate_limit_per_minute = 30
```
## Permissions
### Required: Full Disk Access
1. Open **System Preferences** � **Security & Privacy** � **Privacy**
2. Select **Full Disk Access**
3. Add your terminal application (Terminal.app, iTerm2, etc.)
4. Add your IDE if running from there (VS Code, PyCharm, etc.)
### Optional: Shortcuts (for outbound messaging)
For Shortcuts-based messaging, create these shortcuts in the Shortcuts app:
- "Send Message" - Not Yet Implemented
- "Send Attachment" - Not Yet Implemented
## Platform Support
- **macOS**: Supported
- **Windows/Linux**: Not supported L (requires macOS Messages database)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `pytest`
5. Submit a pull request
## Troubleshooting
### "Database not found" error
- Ensure you're running on macOS
- Check Full Disk Access permissions
- Verify Messages app has been used at least once
### "Permission denied" error
- Add Full Disk Access for your terminal/IDE
- Restart terminal after adding permissions
### ASCII art not showing
- Ensure `ascii-magic` is installed
- Enable with `show_ascii_art=True` parameter
- Check image file accessibility
## Examples
See `example_usage.py` for a complete real-time monitoring application.
## Security Note
This library accesses your Messages database in read-only mode for monitoring. It does not modify or delete any messages. Outbound messaging requires explicit function calls and uses standard macOS APIs.
Raw data
{
"_id": null,
"home_page": null,
"name": "imessage-monitor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Christian Hale <bhschristian@gmail.com>",
"keywords": "ascii-art, chat, imessage, macos, messages, monitoring, real-time, sms",
"author": null,
"author_email": "Christian Hale <bhschristian@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/78/9b/44a6c1d35da09fffb275f0e76d499b7c43afa101cd601710d172ace5c3a4/imessage_monitor-0.2.1.tar.gz",
"platform": null,
"description": "# iMessage Monitor\n\nA Python library for monitoring and extracting iMessage data with real-time capabilities and beautiful terminal display.\n\n## Features\n\n- **Real-time monitoring** of incoming iMessages\n- **Pretty-printed chat bubbles** with proper left/right alignment\n- **Sticker and reaction support** with emoji display\n- **ASCII art generation** for image attachments (optional)\n- **Attachment handling** including HEIC conversion\n- **Outbound messaging** via AppleScript or Shortcuts\n- **Safe database access** with read-only mode\n\n## Requirements\n\n- **macOS only** (requires access to Messages database)\n- **Python 3.11+**\n- **Full Disk Access** permission for terminal/IDE\n\n## Installation\n\n```bash\npip install imessage-monitor\n\nor\n\nuv add imessage-monitor\n```\n\n\n## Quick Start\n\n### Real-time Monitoring\n\n```python\nfrom imessage_monitor import iMessageMonitor\nfrom imessage_monitor.display import pretty_print_bubble\n\ndef handle_message(message):\n \"\"\"Handle new messages with pretty printing.\"\"\"\n print(pretty_print_bubble(message, show_ascii_art=True))\n\n# Start monitoring\nmonitor = iMessageMonitor()\nmonitor.start(message_callback=handle_message)\n\n# Keep running (in practice, you'd run this in an async loop)\ninput(\"Press Enter to stop...\")\nmonitor.stop()\n```\n\n### Message Retrieval\n\n```python\nfrom imessage_monitor import iMessageMonitor, to_json\n\n# Get recent messages\nmonitor = iMessageMonitor()\nmessages = monitor.get_recent_messages(limit=50)\n\n# Convert to JSON\njson_data = to_json(messages)\nprint(json_data)\n```\n\n### Sending Messages\n\n```python\nfrom imessage_monitor import ImessageOutbound\n\n# Send via AppleScript\noutbound = ImessageOutbound()\nsuccess = outbound.send_message_applescript(\"+1234567890\", \"Hello!\")\n\n# Send attachment\nsuccess = outbound.send_attachment_applescript(\"+1234567890\", \"/path/to/file.jpg\")\n```\n\n## Display Options\n\nThe library provides three pretty-print formats:\n\n### Chat Bubbles\n```python\nfrom imessage_monitor.display import pretty_print_bubble\n\n# Basic bubble (no ASCII art)\nprint(pretty_print_bubble(message))\n\n# With ASCII art for images\nprint(pretty_print_bubble(message, show_ascii_art=True))\n```\n\n### Reactions\n```python\nfrom imessage_monitor.display import pretty_print_reaction\n\nprint(pretty_print_reaction(message)) # Shows \u2764\ufe0f, \ud83d\udc4d, \ud83d\udc4e, etc.\n```\n\n### Stickers\n```python\nfrom imessage_monitor.display import pretty_print_sticker\n\nprint(pretty_print_sticker(message, show_ascii_art=True))\n```\n\n## Data Conversion\n\n```python\nfrom imessage_monitor import to_json, to_toml\n\n# Convert messages to different formats\njson_str = to_json(messages)\ntoml_str = to_toml(messages)\n\n# Save to files\nto_json(messages, \"messages.json\")\nto_toml(messages, \"messages.toml\")\n```\n\n## Configuration\n\nThe library uses sensible defaults but can be configured:\n\n```python\nfrom imessage_monitor.config import Config\n\n# Create custom config\nconfig = Config.default()\nconfig.monitoring.poll_interval_seconds = 1 # Faster polling\n\nmonitor = iMessageMonitor(config_path=\"path/to/config.toml\")\n```\n\n### Contact Filtering\n\nFilter messages by specific contacts with whitelist/blacklist functionality:\n\n```python\nfrom imessage_monitor import iMessageMonitor\nfrom imessage_monitor.config import ContactFilter\n\n# Create contact filter\ncontact_filter = ContactFilter(\n outbound_behavior=\"whitelist\", # Only include outbound messages to these contacts\n outbound_ids=[\"+1234567890\", \"friend@example.com\"],\n inbound_behavior=\"blacklist\", # Exclude inbound messages from these contacts\n inbound_ids=[\"spam@example.com\", \"+9876543210\"]\n)\n\n# Apply filter to message retrieval\nconfig = Config.default()\nconfig.contacts = contact_filter\nmonitor = iMessageMonitor()\nfiltered_messages = monitor.get_recent_messages(limit=100)\n```\n\nContact filtering supports:\n- **Chat-level filtering**: Group chats can be whitelisted/blacklisted by chat ID\n- **Individual-level filtering**: Individual contacts filtered by phone/email\n- **Precedence**: Chat-level filtering takes precedence over individual-level\n- **Directional filtering**: Separate rules for inbound vs outbound messages\n\n### Date Range Filtering\n\nFilter messages by date range (applies to manual queries only, not monitoring):\n\n```python\nfrom imessage_monitor.config import DateRange\nfrom datetime import datetime\n\n# Custom date range\ndate_range = DateRange(\n start_date=datetime(2024, 1, 1),\n end_date=datetime(2024, 12, 31)\n)\n\n# Quick helpers\ndate_range = DateRange.from_days_back(7) # Last 7 days\ndate_range = DateRange.from_hours_back(24) # Last 24 hours\n\nconfig = Config.default()\nconfig.date_range = date_range\nmonitor = iMessageMonitor()\nrecent_messages = monitor.get_recent_messages(limit=100)\n```\n\n### Example TOML Configuration\n\n```toml\n[apple]\nchat_db_path = \"~/Library/Messages/chat.db\"\nattachments_path = \"~/Library/Messages/Attachments\"\npermissions_check = true\n\n[monitoring]\npoll_interval_seconds = 20 # Used as backup if enable_real_time=true\nmax_batch_size = 1000\nenable_real_time = true\n\n[contacts]\noutbound_behavior = \"whitelist\" # \"whitelist\" | \"blacklist\" | \"none\"\noutbound_ids = [\"+1234567890\", \"friend@example.com\"]\ninbound_behavior = \"blacklist\" # \"whitelist\" | \"blacklist\" | \"none\" \ninbound_ids = [\"spam@example.com\", \"+9876543210\"]\n\n[date_range] # Ignored when monitoring\nstart_date = \"2024-01-01T00:00:00\"\nend_date = \"2024-12-31T23:59:59\"\n\n[outbound]\nmethod = \"applescript\"\nrate_limit_per_minute = 30\n```\n\n## Permissions\n\n### Required: Full Disk Access\n\n1. Open **System Preferences** \ufffd **Security & Privacy** \ufffd **Privacy**\n2. Select **Full Disk Access** \n3. Add your terminal application (Terminal.app, iTerm2, etc.)\n4. Add your IDE if running from there (VS Code, PyCharm, etc.)\n\n### Optional: Shortcuts (for outbound messaging)\n\nFor Shortcuts-based messaging, create these shortcuts in the Shortcuts app:\n- \"Send Message\" - Not Yet Implemented\n- \"Send Attachment\" - Not Yet Implemented\n\n## Platform Support\n\n- **macOS**: Supported\n- **Windows/Linux**: Not supported L (requires macOS Messages database)\n\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests: `pytest`\n5. Submit a pull request\n\n\n## Troubleshooting\n\n### \"Database not found\" error\n- Ensure you're running on macOS\n- Check Full Disk Access permissions\n- Verify Messages app has been used at least once\n\n### \"Permission denied\" error \n- Add Full Disk Access for your terminal/IDE\n- Restart terminal after adding permissions\n\n### ASCII art not showing\n- Ensure `ascii-magic` is installed\n- Enable with `show_ascii_art=True` parameter\n- Check image file accessibility\n\n## Examples\n\nSee `example_usage.py` for a complete real-time monitoring application.\n\n## Security Note\n\nThis library accesses your Messages database in read-only mode for monitoring. It does not modify or delete any messages. Outbound messaging requires explicit function calls and uses standard macOS APIs.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for monitoring and extracting iMessage data with real-time capabilities",
"version": "0.2.1",
"project_urls": {
"documentation": "https://github.com/Brynhild-CHale/imessage_monitor/blob/main/README.md",
"source": "https://github.com/Brynhild-CHale/imessage_monitor"
},
"split_keywords": [
"ascii-art",
" chat",
" imessage",
" macos",
" messages",
" monitoring",
" real-time",
" sms"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d8f8c3892bc9cb55fc63b04e8563c6472cf4678c1e9d0de73dcc6f9e9f2e8cfc",
"md5": "c2e9f2c84652a08a8c92210daddf3ece",
"sha256": "2d4e2206c9aeadf9a2414354bb6512090430e7d29f57940b1372e883a942c62a"
},
"downloads": -1,
"filename": "imessage_monitor-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2e9f2c84652a08a8c92210daddf3ece",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 32337,
"upload_time": "2025-07-22T11:50:33",
"upload_time_iso_8601": "2025-07-22T11:50:33.838324Z",
"url": "https://files.pythonhosted.org/packages/d8/f8/c3892bc9cb55fc63b04e8563c6472cf4678c1e9d0de73dcc6f9e9f2e8cfc/imessage_monitor-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "789b44a6c1d35da09fffb275f0e76d499b7c43afa101cd601710d172ace5c3a4",
"md5": "e82f180aebe37c730122382c8c30cdbd",
"sha256": "90c37b6b284e51d45d6720f38e1ccc4b3615cdffadb3716705c0e420eee6f6c3"
},
"downloads": -1,
"filename": "imessage_monitor-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "e82f180aebe37c730122382c8c30cdbd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 75467,
"upload_time": "2025-07-22T11:50:34",
"upload_time_iso_8601": "2025-07-22T11:50:34.978647Z",
"url": "https://files.pythonhosted.org/packages/78/9b/44a6c1d35da09fffb275f0e76d499b7c43afa101cd601710d172ace5c3a4/imessage_monitor-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 11:50:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Brynhild-CHale",
"github_project": "imessage_monitor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "imessage-monitor"
}
JSON
