> ## Documentation Index
> Fetch the complete documentation index at: https://help.messagesync.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# iMessage Troubleshooting
> Having trouble with your iMessage integration? This guide provides systematic troubleshooting steps to resolve common issues and get your iMessage account working properly with CRM.
If iMessage won't turn on or says "Waiting for activation" indefinitely, your account may be blocked by Apple. See the [iMessage Account Blocked](#help-my-imessage-got-blocked) section below for recovery steps.
***
## Quick Diagnostic Checklist
Before diving into detailed troubleshooting, quickly verify these common issues:
* iMessage Sync app is running on your Mac
* Mac is powered on and connected to internet
* iPhone is online with cellular/WiFi connection
* Both devices logged in with same Apple ID
* "Messages in iCloud" is enabled on both devices
* Contact has the correct contact tag in CRM (e.g., `{IM#1}`)
* Your account is active (not expired trial)
90% of iMessage problems are caused by the iMessage Sync app not running on the Mac, or the Mac being asleep/offline. Always check this first!
***
## Systematic Troubleshooting Steps
Follow these steps in order to diagnose and resolve iMessage integration issues:
### Step 1: Review Installation and Setup
Go back and verify your initial setup was completed correctly. Walk through the [iMessage Full Setup guide](/imessage/getting-started) and confirm every step - iPhone iCloud sync, Mac iMessage settings, SMS forwarding, and the iMessage Sync app - was done properly.
**If Apple ID issues persist:**
Sign out of iMessage on both devices
Restart both devices
Sign back in to iMessage on iPhone first, then Mac
Wait 5–10 minutes for sync to complete
***
### Step 2: Send Test Messages
Verify basic iMessage functionality works before testing the integration:
**Test 1: Mac to Mac/iPhone iMessage**
Open Messages app on your Mac
Send a test iMessage to a friend's iPhone or another iMessage user
Verify the message sends (should show as blue bubble)
Confirm message appears on your iPhone as well (sync test)
Have the recipient reply
Verify reply appears on both your Mac and iPhone
**Test 2: Integration Test**
In CRM, open a contact record
Add your iMessage contact tag (e.g., `{IM#1}`)
Go to Conversations tab
Send a test message to this contact
Check if message appears in:
* CRM conversations
* Mac Messages app
* iPhone Messages app
**If Test 1 fails:** The issue is with Apple's iMessage sync, not the intergration. Resolve Apple sync first.
**If Test 1 works but Test 2 fails:** Continue to next troubleshooting steps.
***
### Step 3: Check Power and Sleep Settings
A very common issue: Mac going to sleep stops the gateway from working. See the [Mac sleep settings guide](/imessage/getting-started#my-mac-keeps-falling-asleep) for the full configuration steps.
***
## Common Issues and Solutions
### Messages Not Sending from CRM
**Symptoms:**
* Send message in CRM
* Message shows as "sent" in CRM
* Message never appears in Mac Messages app
* Recipient never receives message
**Causes & Solutions:**
#### iMessage Sync Not Running
* Check Mac menu bar for iMessage Sync icon
* If not visible, app is not running
* Launch iMessage Sync from Applications folder
* Verify it shows "Connected" status
#### Mac is Asleep or Offline
* Wake Mac and ensure it's online
* Check WiFi/Ethernet connection
* Verify internet connectivity
* Adjust power settings to prevent sleep
#### Full Disk Access Not Granted
See [Granting Full Disk Access](/imessage/getting-started#log-in-and-connect) in the Full Setup guide. Restart the app after granting permission.
#### Messages in iCloud Not Synced
* iPhone and Mac must have Messages in iCloud enabled
* Check both devices under iMessage settings
* Allow 10–15 minutes for initial sync
* Send a test message directly from Mac to verify sync works
***
### Replies Not Appearing in CRM
**Symptoms:**
* Messages appear in Mac Messages app
* Messages send to recipients successfully
* Replies don't appear in CRM
**Causes & Solutions:**
#### Gateway Connection Lost
* Check iMessage Sync app status
* Should show "Connected" with green indicator
* If disconnected, reconnect with fresh token
* Restart the app if status is unclear
#### Network Firewall Blocking
* Check Mac firewall settings
* Ensure iMessage Sync is allowed through firewall
* **System Settings → Network → Firewall Options**
* Add iMessage Sync to allowed apps
***
### SMS Fallback Not Working (to Android)
**Symptoms:**
* Messages to iPhones work fine
* Messages to Android phones fail to send
* Green bubble messages don't deliver
**Causes & Solutions:**
#### iPhone Not Online
* iPhone must be online for SMS fallback to work
* SMS messages route through your iPhone's cellular plan
* Verify iPhone has cellular signal and data
* Keep iPhone charged and connected
#### Text Message Forwarding Not Enabled
On iPhone: **Settings → Messages → Text Message Forwarding**
Find your Mac in the list
Toggle it **ON**
Enter code displayed on Mac if prompted
iPhone and Mac must be on same WiFi for initial setup
#### Cellular Plan Doesn't Support SMS
* Verify your iPhone carrier plan includes SMS
* Some data-only plans don't support SMS
* Contact your carrier if unsure
* May incur SMS charges for Android messages
#### Phone Number Not Registered on Mac
On Mac: **Messages → Settings → iMessage**
Verify your phone number appears under "You can be reached..."
If missing, sign out and sign back into iMessage
May take 24 hours for phone number to activate on Mac
SMS to Android uses your iPhone's cellular plan and may incur carrier SMS charges.
***
### Device Sync and Connection Issues
**Symptoms:**
* Messages sent from Mac don't appear on iPhone
* Messages sent from iPhone don't appear on Mac
* Conversations out of sync
**Causes & Solutions:**
#### Messages in iCloud Not Enabled
* iPhone: **Settings → Apple ID → iCloud → Messages → Toggle ON**
* Mac: **Messages → Settings → iMessage → Check "Enable Messages in iCloud"**
* Both devices must have this enabled
* Wait 10–15 minutes after enabling for initial sync
#### Different Apple IDs
* Verify both devices use the same Apple ID
* iPhone: **Settings → \[Your Name]**
* Mac: **Messages → Settings → iMessage**
* Sign out and sign back in if needed
#### iCloud Storage Full
* Messages in iCloud requires iCloud storage
* Check: **iPhone Settings → Apple ID → iCloud → Manage Storage**
* If full, upgrade iCloud plan or free up space
* Consider iCloud+ for more storage
#### Poor Internet Connection
* Both devices need stable internet for sync
* Try switching between WiFi and cellular
* Restart router if WiFi seems slow
* Test internet speed on both devices
#### Force Sync
Sign out of iMessage on both devices
Restart both devices
Sign back into iMessage (iPhone first, then Mac)
Wait 10–15 minutes for full sync
Send test message to verify sync
***
### iMessage Sync Disconnects
**Symptoms:**
* Gateway app shows "Disconnected" status
* Red indicator in menu bar
* Messages fail to send through the system
**Causes & Solutions:**
#### Network Connectivity Issues
* Check Mac has internet connection
* Try loading a website in browser
* Restart WiFi/Ethernet if needed
* Check router is working properly
#### Firewall Blocking Connection
**System Settings → Network → Firewall**
If enabled, click **"Firewall Options"**
Ensure iMessage Sync is allowed
Consider temporarily disabling firewall to test
#### App Corruption
Quit iMessage Sync app completely
Restart Mac
Reinstall iMessage Sync app
Reconnect with fresh code
***
### Performance and Reliability Issues
#### Message Delays
**Symptoms:**
* Messages eventually send but with delays
* Several minutes between sending and delivery
* Inconsistent delivery times
**Causes & Solutions:**
**Mac Resource Constraints:**
* Check Activity Monitor for high CPU/memory usage
* Close unnecessary applications
* Restart Mac to clear memory
* Consider upgrading RAM if running multiple iMessage accounts
**Network Latency:**
* Test internet speed (should be 10+ Mbps)
* Use wired Ethernet instead of WiFi for better stability
* Restart router/modem
* Contact ISP if speeds are consistently slow
**iCloud Sync Delays:**
* Messages in iCloud can sometimes lag
* Wait a few minutes and check again
* Try sending test message to verify current sync status
* Consider disabling and re-enabling Messages in iCloud
**Multiple Accounts on One Mac:**
* Check RAM usage in Activity Monitor - running too many accounts on limited RAM causes delays
* See [How Much Power Do I Need?](/imessage/device-specifications#-how-much-power-do-i-need) for RAM requirements per account count
***
#### Mac Keeps Sleeping
**Symptoms:**
* Mac sleeps even with "prevent sleep" enabled
* Messages stop sending when Mac is idle
* Have to wake Mac for messages to work
**Fix:** See the [Mac sleep settings guide](/imessage/getting-started#my-mac-keeps-falling-asleep) for the full set of energy and Power Nap configurations.
***
## Advanced Troubleshooting
### Multiple iPhone Accounts Issues
**Symptoms:**
* Some accounts work, others don't
* Mac runs slow with multiple accounts
* Accounts disconnect randomly
**First, verify your setup matches the requirements** in [Running Multiple iPhones on One Mac](/imessage/device-specifications#-running-multiple-iphones-on-one-mac-advanced) - RAM, Fast User Switching, and the 4-iPhone maximum.
#### Individual Account Troubleshooting
Switch to problem account's user profile
Troubleshoot as if it were the only account
Check Gateway connection status
Verify iMessage is logged in for that profile
***
### Permissions and Security Issues
**Symptoms:**
* macOS security warnings about iMessage Sync
* Permission dialogs keep appearing
* Features not working due to permissions
#### Full Disk Access & Gatekeeper Blocks
For Full Disk Access setup and "unidentified developer" Gatekeeper warnings, see [Step 4: Install the iMessage Sync App](/imessage/getting-started#step-4-install-the-imessage-sync-app) in the Full Setup guide.
#### Accessibility Permissions
* **System Settings → Privacy & Security → Accessibility**
* Add iMessage Sync if requested
* May be needed for some features
#### Reset All Permissions
Remove iMessage Sync from all permission lists
Quit app completely
Restart Mac
Reopen app and grant permissions when prompted
Ensures clean permission state
***
## Help! My iMessage Got Blocked
Did Apple suddenly turn off your iMessage? Don't panic. This section will show you exactly how to get your account unblocked and how to make sure it never happens again.
If your account gets blocked, the integration won't be able to send or receive messages for you until Apple turns it back on.
The integration does not block accounts. Apple controls iMessage, and they have automated spam filters that will turn off your account if they think you are acting like a robot or a spammer.
### How to Tell if You're Blocked
You are probably blocked by Apple if:
* **The iMessage Button is Gray:** You can't even flip the switch to turn iMessage on in your iPhone settings.
* **Stuck on Activation:** Your screen is stuck saying "Waiting for Activation..." forever.
* **Messages Send as Green Texts:** Every message you send to another iPhone goes through as a green SMS text instead of a blue iMessage.
* **Dashboard Says Disconnected:** Your dashboard shows your Mac is completely disconnected.
* **Login Fails:** Apple won't let you sign into your Apple ID at all.
Before you panic, check your wifi! Sometimes bad internet or a turned-off Mac causes similar issues. Check the [troubleshooting steps above](#quick-diagnostic-checklist) first to rule out a simple internet drop.
***
### Why Did Apple Block Me?
Apple's number one goal is to keep spam off of iMessage. If you got blocked, you probably tripped one of their alarms.
#### Sending Too Much, Too Fast
* You texted way more people today than you usually do.
* You went over the safe limit of **50 unique contacts per day**.
* You went from sending 5 messages yesterday to 200 messages today.
#### Acting Like a Spammer
* You copy-pasted the exact same message to 50 different people.
* You didn't use anyone's first name.
* You fired off 30 messages in under two minutes.
#### People Reported You
* The people you texted hit the "Report Junk" button.
* A bunch of people blocked your phone number.
* You sent cold texts to people who had no idea who you were.
#### Brand New Accounts
* You created a brand new Apple ID today and immediately started blasting texts. Apple hates this.
#### The Rulebook
If you are using the integration for your business, you have to play by the rules:
Always keep your sending to **under 50 unique people per day**. If you have a brand new account, start with just 10 a day and slowly work your way up. Only text people who actually opted in to hear from you.
***
### How to Get Your Account Unblocked
If Apple definitely blocked you, here is exactly what you need to do to get it back.
#### Step 1: Make Sure You Can Still Log In
Go to [appleid.apple.com](https://appleid.apple.com) on your computer.
Try to log in with your Apple ID and password.
Look for any big red warning signs or security alerts.
If Apple locked your entire account and you can't even sign in, go to [Apple's Account Recovery](https://iforgot.apple.com) right now to get your password back.
#### Step 2: Call Apple Support
**How to reach them:**
* Go to [support.apple.com](https://support.apple.com)
* Click on **iMessage**.
* Choose **iMessage Activation** or **Can't Send Messages**.
* Pick the option to have them call you or open a chat.
**What to say when they answer:**
> "Hi! I can't seem to get iMessage to turn on on my phone. Can you check if my iMessage got blocked? My Apple ID is \[your email]."
**Have this ready:**
* Your Apple ID email
* What kind of phone or Mac you use
* What error message you see
#### Step 3: Fill Out the Re-Enable Form
If Apple confirms they turned your iMessage off, they will ask you to fill out a form to turn it back on.
**Where to go:**
* Apple will either text you a link, or you can go here: [apple.co/IMFT-mac](https://apple.co/IMFT-mac)
**What to write:** Keep it professional. Don't mention "mass texting" or "bulk SMS".
> "Hi there. I use my iMessage to chat with my clients through my company's CRM (CRM). I just noticed my iMessage turned off. All my clients have opted in to text me, and I follow Apple's guidelines. Could you please help me turn my iMessage back on? Thank you."
Apple will email you their answer. Keep an eye on your spam folder just in case!
#### Step 4: Wait for Apple's Email
**If they say YES:**
* They will email you saying iMessage is back on. Move to Step 5!
**If they say NO:**
* They might decide to keep you blocked. If this happens, you will need to get a new phone number and create a new Apple ID.
#### Step 5: Turn iMessage Back On
**On your iPhone:**
Open your **Settings** app.
Scroll down and tap **Messages**.
Turn the iMessage switch **OFF**.
Wait 30 seconds.
Turn the iMessage switch back **ON**.
Wait for it to activate (it might take a few minutes).
**On your Mac:**
Open the **Messages** app.
Click **Messages** in the top menu, then **Settings**.
Go to the **iMessage** tab.
Click **Sign Out**.
Wait 30 seconds, then sign back in.
**Test it:** Send a text to a friend with an iPhone. If the bubble is blue, you are back in business!
#### Step 6: Reconnect to the system
Open the **iMessage Sync app** on your Mac.
You might need to log out and log back in.
Grab a fresh Activation Code from your dashboard and paste it in.
Send a test message from CRM to make sure everything is working perfectly again.
***
### Still Blocked? Try This
If Apple sent you an email saying you are unblocked, but your phone is STILL stuck on "Waiting for Activation," try this:
Don't use the chat this time. Ask for a phone call.
Ask to speak to someone higher up.
Tell them, "I got an email saying my account was unblocked, but my phone still won't activate. My case number is \[insert number]."
**Apple Support Numbers:**
* **US:** 1-800-275-2273
* **Other Countries:** [Find your number here](https://support.apple.com/en-us/111900)
***
### How to Never Get Blocked Again
#### Warm Up New Accounts Slowly
| Timeframe | Maximum Texts Per Day | Who to text |
| --------- | --------------------- | ------------------------------------- |
| Week 1 | 10 to 15 | Real friends and family |
| Week 2 | 20 to 25 | A mix of friends and warm clients |
| Week 3 | 30 to 35 | Starting to send more client messages |
| Week 4 | 40 to 50 | Full speed! (But never go over 50) |
#### Stop Sounding Like a Robot
* **Use custom fields:** Always say "Hi `{{contact.first_name}}`" instead of just "Hi".
* **Mix it up:** Don't send the exact same sentence 40 times in a row.
* **No lists:** Never buy a list of phone numbers and start cold-texting them.
#### Talk to People Who Actually Reply
* Only text people who know you and will text you back.
#### Don't Put All Your Eggs in One Basket
* If your agency needs to send 200 messages a day, set up 4 different iPhones and send 50 messages through each one.
***
### Plan B: Starting Fresh
If Apple completely permanently banned your account and refuses to unlock it:
Create a brand new Apple ID.
Get a new phone number.
Start the warm-up process from Week 1 (see above).
Do not make the same mistake twice!
***
### How Apple's Spam Filter Works
**Red Flags for Apple:**
* You text 100 people in an hour.
* You text people who don't have you saved in their contacts.
* You type faster than a human possibly could (which happens when you automate identical messages).
* Your Apple ID is only 3 days old and you are sending 50 texts a day.
* People hit the "Report Junk" button when they see your text.
***
## Support[](#support "Direct link to Support")
If you need help with the setup or onboarding:
* Email: [**support@messagesync.ai**](mailto:support@messagesync.ai)