iMessage Setup

macOS AppleScript bridge for urgent notifications

Overview

The iMessage channel provides a native macOS integration for sending urgent notifications directly to your iPhone, iPad, or Mac. It uses AppleScript to interact with the Messages app.

macOS Only Requirement

This channel only works on macOS. It requires the Messages app with an active iMessage account. Windows and Linux are not supported.

Urgent Notifications Only

iMessage is reserved for urgent-tier notifications only. It should only be used for critical alerts that require immediate attention.

Difficulty

Medium

Setup Time

15 minutes

Notification Tiers

Urgent Only

Prerequisites

macOS 10.15 (Catalina) or later
Active iMessage account configured in Messages app
Python 3.9+ with pyobjc framework
Administrative privileges to grant Accessibility permissions

Step-by-Step Setup

Enable iMessage on macOS

Open the Messages app on your Mac
Go to Messages → Settings → iMessage
Ensure your Apple ID is signed in
Verify "Enable Messages in iCloud" is checked
Test sending a message to confirm iMessage is working

Grant Accessibility Permissions

SingularCore needs Accessibility permissions to control the Messages app via AppleScript:

Open System Settings → Privacy & Security → Accessibility
Click the + button to add an app
Navigate to and select your Python executable or terminal application
Ensure the toggle is enabled (blue)
Restart your terminal/SingularCore for changes to take effect

Configure Allowed Contacts

Edit config/comms.json:

{
  "imessage": {
    "enabled": true,
    "allowed_contacts": [
      "+1234567890",
      "user@icloud.com"
    ],
    "auto_setup": true
  }
}

Use phone numbers with country code (e.g., +1234567890) or Apple ID email addresses.

Test the Integration

Send a test message to verify everything is working:

python -c "
from core.brain.comms.channels.imessage import iMessageChannel
channel = iMessageChannel()
await channel.send_message('+1234567890', 'Test from SingularCore')
"

Supported Commands

iMessage is outbound-only. It sends urgent notifications but does not support receiving commands. For two-way communication, use Telegram or Discord.

Feature	Description	Status
Send Messages	Send urgent alerts to configured contacts	Supported
Receive Commands	Process incoming iMessage commands	Not Supported
Media Attachments	Send images, files, or media	Text Only

Troubleshooting

Messages Not Sending

Verify iMessage is enabled in the Messages app
Check that Accessibility permissions are granted
Ensure the contact is in allowed_contacts list
Try sending manually from Messages app first

AppleScript Error

Make sure Messages app is running
Check Accessibility permissions in System Settings
Restart the Messages app
Verify Python has permission to control your computer

Contact Not Receiving

Use full phone number with country code (e.g., +1...)
Verify the contact uses iMessage (blue bubbles)
Check that the contact is not blocked
Ensure the contact has iMessage enabled on their device

Need More Details?

View the complete setup guide with advanced configuration options and security best practices.

View Full Documentation

Documentation Menu

Back to Channels