Mac Worker Setup Guide

Use one Mac worker script for two-way Apple Messages sync (outbound + inbound)

Quick Start (2 Minutes)

1

Register Your Mac in CRM

  1. Go to Settings (gear icon) → Messaging
  2. Click "Register Device"
  3. Select "Mac" (green box)
  4. Enter device name (e.g., "My MacBook Pro")
  5. Enter your phone number (e.g., "+1 480 793 9922")
  6. Click "Register"
  7. Copy both credentials shown (Device ID and Secret)
2

Run Installer

Open Terminal on your Mac and paste these commands:

curl -fsSL https://www.usenextora.com/imessage/install | bash
nextora-imessage install

The installer will:

  • Install the local shell worker runtime
  • Install one unified worker script (worker.sh)
  • Ask for your Device ID and Secret (from Step 1)
  • Enable inbound sync settings
  • Set auto-start so it runs after every reboot

When prompted, choose Option 1 (Auto-Start / Background).

Already installed an older worker? Update it first:

nextora-imessage install

💡 Tip: Have your credentials ready to paste when the installer asks for them.

✓

Done! Test It

The worker now runs automatically in background. Now test it:

  1. Go to any client in your CRM
  2. Click Activities tab
  3. Send a test Apple Messages text to yourself (outbound test)
  4. Reply from another phone to your Mac number (inbound test)
  5. Within 10-20 seconds, both directions should appear in CRM

Privacy-safe default: inbound sync only tracks replies from contacts you messaged via CRM.

Why Use Mac Instead of iPhone?

Fully Automatic

Zero user interaction - no taps needed

24/7 Operation

Mac can stay on and run continuously

Free

No per-message carrier costs like traditional SMS

Reliable

Direct AppleScript integration

⚠️ Important: iOS cannot send iMessages fully automatically due to Apple security restrictions. Mac is the only platform that supports zero-interaction sending.

Troubleshooting

"Permission denied" when running install.sh

Solution: Make the script executable first:

chmod +x install.sh && ./install.sh

"nextora-imessage: command not found"

Solution: Install the CLI again, then rerun the installer:

curl -fsSL https://www.usenextora.com/imessage/install | bash

"Connection failed" or "Invalid credentials"

Solution: Make sure you:

  • Registered the device in CRM first (before running installer)
  • Copied credentials correctly (no extra spaces or line breaks)
  • Used the credentials from your own account

Messages not sending

Solution: Check these:

  • Messages app is open and signed into your Apple account
  • For Android texting, your paired iPhone has Messages in iCloud or Text Message Forwarding enabled
  • Mac is awake (not sleeping)
  • Auto-start service is loaded: launchctl list | grep imessage-worker
  • Check worker logs for error messages
  • Try sending a test message manually in Messages app first

Messages send but inbound replies don't appear

Solution: Check these:

  • Update worker to latest: nextora-imessage install
  • Grant Full Disk Access to Terminal in macOS Privacy settings
  • Restart worker and look for Inbound enabled: yes in logs

Worker stopped running

Solution: Restart the auto-start service:

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.nextora.imessage-worker.plist 2>/dev/null || truelaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.nextora.imessage-worker.plist

Mac is off/sleeping - will messages still send?

Answer:No, but they'll queue and send when Mac wakes up.

To prevent Mac from sleeping:

caffeinate -s /bin/bash ~/.nextora-imessage/worker.sh

Running 24/7 in Background

Auto-start is the default and recommended mode:

Option 1: launchd Auto-Start (Recommended)

Check or restart your background service:

launchctl list | grep imessage-workerlaunchctl kickstart -k gui/$(id -u)/com.nextora.imessage-worker

View logs:

tail -f ~/Library/Logs/imessage-worker.log

Option 2: Keep Mac Awake

Use caffeinate to prevent Mac from sleeping:

caffeinate -s

How It Works

1

You send a message from CRM

Open any client → Activities → Send via Apple Messages

2

Gateway queues the message

Message is stored and assigned to your Mac device

3

Mac worker polls gateway

Checks every 10 seconds for new messages

✓

Message sent automatically!

AppleScript sends via Messages app - no user interaction needed

Manual Downloads

If the one-command installer doesn't work, download these files manually:

nextora-imessage

CLI wrapper with install/status/test/logs/uninstall

imessage/install

One-command bootstrap installer

worker.sh

Unified outbound + inbound shell worker

After downloading:

  1. Save files to a folder (e.g., ~/imessage-worker/)
  2. Open Terminal and navigate to that folder
  3. Run: chmod +x nextora-imessage
  4. Run: ./nextora-imessage install
  5. Enter your credentials when prompted
  6. Run: ./nextora-imessage status

Frequently Asked Questions

Do I need to keep my Mac on 24/7?

For real-time automatic sending, yes. If your Mac is off or sleeping, messages will queue and send automatically when the Mac wakes up. For 24/7 operation, use a Mac Mini or keep your MacBook plugged in and awake.

Can I use my iPhone instead?

iOS has security restrictions that prevent fully automatic sending. Even with shortcuts, you'll need to tap "Send" for each message. Mac is the only platform that supports zero-interaction automatic sending.

Is my data secure?

Yes! Your Device ID and Secret are stored only on your Mac. The worker only has access to messages sent from your CRM account. Each user's data is completely isolated.

How do I stop the worker?

Unload the launchd service:

nextora-imessage uninstall

Can I run this on multiple Macs?

Yes! Register each Mac separately in the CRM. Each device gets its own credentials. Messages will be distributed across available devices.