iMessage Troubleshooting
Comprehensive troubleshooting guide for resolving iMessage integration issues with WhatSnap, including common problems and step-by-step solutions.
Having trouble with your iMessage integration in WhatSnap? This guide provides systematic troubleshooting steps to resolve common issues and get your iMessage account working properly with GoHighLevel.
SMS vs iMessage Issues: If you're having trouble specifically with SMS messages (to Android users), check the SMS Fallback Issues section. For general iMessage problems, continue with the steps below.
iMessage Won't Activate? If iMessage won't turn on or says "Waiting for activation" indefinitely, your account may be blocked by Apple. See our iMessage Account Blocked Guide for recovery steps.
Quick Diagnostic Checklist
Before diving into detailed troubleshooting, quickly verify these common issues:
Most Common Issue: 90% of iMessage problems are caused by the WhatSnap Gateway 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:
Check These Setup Steps:
iPhone Setup:
Settings → Apple ID → iCloud → Messages is ON
Settings → Messages → iMessage is enabled
Using the same Apple ID as your Mac
Mac Setup:
Messages app → Settings → iMessage → Enabled
Same Apple ID as iPhone
"Enable Messages in iCloud" is checked
Phone number appears under "You can be reached for messages at"
"Start new conversations from" is set to your phone number (not email)
WhatSnap Connection:
WhatSnap Gateway app is installed and running
Device shows as "Connected" in WhatSnap dashboard
Account tag is assigned to contacts in GoHighLevel
Need to review? See the complete Adding iMessage Accounts guide for detailed setup instructions.
Step 2: Verify Apple ID and iMessage Login
Ensure both devices are properly authenticated with iMessage:
On iPhone:
Open Settings
Tap your name at the top → Apple ID
Verify you're signed in
Go to iCloud → scroll to Messages
Ensure "Sync this iPhone" is ON
Go back to main Settings → Messages
Verify iMessage is ON (toggle should be green)
Check that your phone number appears under "Send & Receive"
On Mac:
Open Messages app
Go to Messages → Settings (or Preferences)
Click iMessage tab
Verify you're signed in with same Apple ID as iPhone
Check "Enable Messages in iCloud" is selected
Confirm your phone number is listed under "You can be reached for messages at"
Under "Start new conversations from", select your phone number (uncheck email)
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 3: Send Test Messages
Verify basic iMessage functionality works before testing WhatSnap 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: WhatSnap Integration Test
In GoHighLevel, open a contact record
Add your iMessage account tag (e.g.,
whatsnap-account-imessage)Go to Conversations tab
Send a test message to this contact
Check if message appears in:
GoHighLevel conversations
Mac Messages app
iPhone Messages app
If Test 1 fails: The issue is with Apple's iMessage sync, not WhatSnap. Resolve Apple sync first.
If Test 1 works but Test 2 fails: Continue to next troubleshooting steps.
Step 4: Enable Full Disk Access for WhatSnap Gateway
macOS security requires full disk access for the WhatSnap Gateway app to read and send iMessages:
Grant Full Disk Access:
Open System Settings (or System Preferences)
Click Privacy & Security
Scroll down to "Full Disk Access" in the left sidebar
Click the lock icon at bottom left and authenticate
Click the "+" button
Navigate to Applications folder
Select WhatSnap Gateway app
Click "Open" to add it to the list
Ensure the checkbox next to WhatSnap Gateway is checked
Restart the WhatSnap Gateway app
Critical Permission: Without Full Disk Access, the WhatSnap Gateway cannot access your Messages database and will fail to send/receive messages silently.
Verify Permission Was Granted:
WhatSnap Gateway should no longer show permission warnings
App status should show as "Connected" in the menu bar
Test sending a message through GoHighLevel
Step 5: Check Channel Integration Settings
Verify your WhatSnap channel integration is configured correctly in GoHighLevel:
Using SMS Channel Override (Recommended):
In GoHighLevel, go to Settings → Phone Numbers
Under "SMS Configuration", verify WhatSnap has replaced SMS
Your iMessage messages should route through the SMS tab
Test by sending a message - should use iMessage for tagged contacts
Using Separate WhatSnap Channel:
In GoHighLevel conversations, look for WhatSnap or iMessage tab
Ensure you're clicking the correct channel when messaging
Verify the contact has the proper account tag
Account Tag Verification:
Open the contact in GoHighLevel
Check Tags section for your iMessage account tag (e.g.,
whatsnap-account-imessage)If missing, add the tag manually
Try sending again
Tag Required: Every contact must have an iMessage account tag for WhatSnap to route messages through your Mac. No tag = no message delivery.
Step 6: Reconnect WhatSnap Gateway App
If issues persist after previous steps, try reconnecting the Gateway app:
Disconnect and Reconnect:
Open WhatSnap Gateway app on your Mac
Click "Log Out" or "Disconnect" in the app menu
Quit the WhatSnap Gateway app completely (Cmd+Q)
Go to your WhatSnap Dashboard in GoHighLevel
Navigate to Devices or Connected Accounts
Find your Mac device
Click "Regenerate Token" or "Get New Token"
Copy the new authentication token
Reopen WhatSnap Gateway app
Paste the new token and click "Connect"
Verify connection status shows "Connected"
After Reconnecting:
Wait 2-3 minutes for connection to stabilize
Check device status in WhatSnap dashboard (should be green/active)
Send a test message through GoHighLevel
Verify message appears in Mac Messages app
Step 7: Check Power and Sleep Settings
A very common issue: Mac going to sleep stops the gateway from working.
Verify Energy Settings:
Open System Settings → Energy (or Battery)
For "Power Adapter" settings:
"Prevent automatic sleeping" should be ON
Or "Turn display off after" set to longer duration
Disable "Put hard disks to sleep when possible"
Disable "Power Nap" (can interfere)
Check "Start up automatically after power failure" is ON
Additional Power Checks:
Verify Mac is plugged into power (not running on battery)
For Mac mini: Can run headless (no display needed)
Check Mac hasn't entered sleep mode (wiggle mouse/keyboard)
Install Amphetamine (Optional):
Free app from Mac App Store
Keeps Mac awake reliably
Backup to WhatSnap's built-in wake prevention
Especially useful for unattended Mac mini setups
See our iMessage Specifications - Power Settings section for detailed configuration.
Common Issues and Solutions
Messages Not Sending from GoHighLevel
No messages appear in Mac Messages app when sending from GHL
Symptoms:
Send message in GoHighLevel
Message shows as "sent" in GHL
Message never appears in Mac Messages app
Recipient never receives message
Causes & Solutions:
WhatSnap Gateway Not Running
Check Mac menu bar for WhatSnap Gateway icon
If not visible, app is not running
Launch WhatSnap Gateway from Applications folder
Verify it shows "Connected" status
Wrong Account Tag
Contact may have wrong tag or no tag
Check contact tags in GoHighLevel
Add correct iMessage account tag (e.g.,
whatsnap-account-imessage)Remove any conflicting tags from other accounts
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
Go to System Settings → Privacy & Security → Full Disk Access
Ensure WhatSnap Gateway is in list and checked
Restart 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
Messages send from Mac but not showing in GoHighLevel
Symptoms:
Messages appear in Mac Messages app
Messages send to recipients successfully
Replies don't appear in GoHighLevel
Causes & Solutions:
Gateway Connection Lost
Check WhatSnap Gateway app status
Should show "Connected" with green indicator
If disconnected, reconnect with fresh token
Restart the app if status is unclear
Authentication Token Expired
Go to WhatSnap Dashboard
Generate new authentication token
Log out of Gateway app and log back in
Use new token to reconnect
Network Firewall Blocking
Check Mac firewall settings
Ensure WhatSnap Gateway is allowed through firewall
System Settings → Network → Firewall Options
Add WhatSnap Gateway to allowed apps
Contact Not in GoHighLevel
WhatSnap can only sync messages for contacts that exist in GHL
Check if contact exists in your GHL account
Create contact manually if needed
Tag will be auto-assigned when they message you
SMS Fallback Not Working (to Android)
Can't send SMS to Android users (green bubbles)
Symptoms:
iMessages to iPhones work fine
SMS to Android phones fail
Green bubble messages don't send
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: 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
Important Note: SMS to Android uses your iPhone's cellular plan and may incur carrier SMS charges.
Device Sync and Connection Issues
iPhone and Mac not syncing messages
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
WhatSnap Gateway shows as disconnected
Symptoms:
Gateway app shows "Disconnected" status
Red indicator in menu bar
Messages fail to send through WhatSnap
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 WhatSnap Gateway is allowed
Consider temporarily disabling firewall to test
Authentication Token Invalid
Token may have expired or been regenerated
Go to WhatSnap Dashboard
Get fresh authentication token
Log out of Gateway app and log back in with new token
WhatSnap Server Issues
Rarely, WhatSnap servers may have temporary issues
Check WhatSnap status page or Twitter for updates
Contact support if widespread issue suspected
App Corruption
Quit WhatSnap Gateway app completely
Delete app preferences: ~/Library/Preferences/com.whatsnap.*
Restart Mac
Reinstall WhatSnap Gateway app
Reconnect with fresh token
Performance and Reliability Issues
Messages delayed or taking long time to send
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
Running too many iMessage accounts on limited RAM
Check RAM usage in Activity Monitor
Reduce number of active accounts
Upgrade to Mac with more RAM
See iMessage Specifications for RAM requirements
Mac keeps going to sleep despite settings
Symptoms:
Mac sleeps even with "prevent sleep" enabled
Messages stop sending when Mac is idle
Have to wake Mac for messages to work
Causes & Solutions:
Energy Settings Override
Check multiple energy settings locations:
System Settings → Energy (or Battery)
System Settings → Lock Screen
Ensure "Prevent automatic sleeping" is ON
For MacBooks, check both "Battery" and "Power Adapter" tabs
Display Sleep vs System Sleep
Display can sleep, but system must stay awake
Set "Turn display off after" to desired time
But "Prevent automatic sleeping" must be ON
These are independent settings
Hard Disk Sleep
Disable "Put hard disks to sleep when possible"
Can prevent gateway app from running properly
Found in Energy settings
Power Nap Interference
Disable "Enable Power Nap"
Can cause unpredictable sleep behavior
Found in Energy settings
Use Amphetamine App
Free from Mac App Store
Reliably keeps Mac awake
Overrides system sleep settings
Menu bar control for easy management
Highly recommended for Mac mini setups
For Mac Mini Specifically
Can run "headless" (no monitor needed)
Disconnect display after setup
Access via Screen Sharing when needed
Ensure power settings are correct before disconnecting display
Advanced Troubleshooting
Multiple iPhone Accounts Issues
Problems running multiple iMessage accounts on one Mac
Symptoms:
Some accounts work, others don't
Mac runs slow with multiple accounts
Accounts disconnect randomly
Solutions:
Memory Limitations
Check total RAM vs. number of accounts
Recommended: 16-32 GB RAM for 3-4 accounts
Close unnecessary apps to free memory
Consider upgrading RAM or using separate Macs
User Profile Issues
Ensure using "Fast User Switching" (not logout)
All profiles must remain logged in simultaneously
Check each profile has WhatSnap Gateway running
Verify each profile auto-starts Gateway app
Resource Distribution
Limit to maximum 4 iPhones per Mac
Monitor Activity Monitor for performance
Distribute accounts across multiple Macs if possible
Prioritize which accounts need best reliability
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
See iMessage Specifications - Multiple iPhone Setup for detailed configuration.
Permissions and Security Issues
Permission errors or security warnings
Symptoms:
macOS security warnings about WhatSnap Gateway
Permission dialogs keep appearing
Features not working due to permissions
Solutions:
Full Disk Access (Most Important)
System Settings → Privacy & Security → Full Disk Access
Add WhatSnap Gateway and check the box
Restart app after granting
Accessibility Permissions
System Settings → Privacy & Security → Accessibility
Add WhatSnap Gateway if requested
May be needed for some features
Security & Privacy Settings
System Settings → Privacy & Security
Under "Security" section
Click "Allow" for WhatSnap Gateway if blocked
May need to reinstall if repeatedly blocked
Gatekeeper Issues
If app won't open due to "unidentified developer":
Right-click app → "Open"
Click "Open" in dialog that appears
Or: System Settings → Privacy & Security → click "Open Anyway"
Reset All Permissions
Remove WhatSnap Gateway from all permission lists
Quit app completely
Restart Mac
Reopen app and grant permissions when prompted
Ensures clean permission state
Still Having Issues?
Tried everything and still stuck? Salvador has debugged hundreds of iMessage setups and can spot the issue fast → Get Salvador's help now
If you've worked through all troubleshooting steps and still experience problems:
Before Contacting Support
Gather this information to help support resolve your issue faster:
Device Information:
iPhone model and iOS version
Mac model and macOS version
WhatSnap Gateway app version
Internet connection type (WiFi/Ethernet)
Problem Details:
Exact error messages you're seeing
When the problem started
What you've already tried
Does it happen for all contacts or specific ones?
Can you send/receive directly in Mac Messages app?
Screenshots/Videos:
Screenshot of WhatSnap Gateway app showing status
Screenshot of the error in GoHighLevel
Screenshot of your iMessage settings on both devices
Loom video showing the problem (highly recommended)
Contact WhatSnap Support
Get Help: If you've followed all troubleshooting steps and still face issues, our support team is here to help.
How to Get Support:
Email Support: support@whatsnap.ai
Include all information listed above
Attach screenshots
Link to Loom video if possible
Submit Support Ticket:
Log into WhatSnap Dashboard
Navigate to Support or Help section
Submit detailed ticket with information above
Include in Your Support Request:
Subject: "iMessage Integration Issue - [Brief Description]"
Your GoHighLevel sub-account name
Device information (iPhone/Mac models and OS versions)
Detailed description of the problem
Steps to reproduce the issue
What troubleshooting you've already tried
Screenshots or Loom video link
Loom Video Tips:
Record your screen while demonstrating the problem
Show: WhatSnap Gateway status, sending message in GHL, checking Messages app
Narrate what you're doing and what should happen vs. what actually happens
Keep video under 5 minutes if possible
Share the Loom link in your support request
Typical Response Times
Email: 24-48 hours
Support Ticket: 12-24 hours
Critical Issues: Prioritized for faster response
Related Documentation
Adding iMessage Accounts - Complete setup guide
Multiple iMessage Accounts - Connect multiple iMessage numbers for teams
iMessage Account Blocked - Recover from Apple iMessage deactivation
iMessage Device Specifications - Hardware requirements and recommendations
Account Settings - Configure account preferences
Tag Management - Understanding account tags and routing
Conversations - Using iMessage for messaging
Last Updated: For the latest setup instructions, see the Adding iMessage Accounts guide.
Last updated