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:

1

Step 1: Review Installation and Setup

Go back and verify your initial setup was completed correctly:

Check These Setup Steps:

  1. iPhone Setup:

    • Settings → Apple ID → iCloud → Messages is ON

    • Settings → Messages → iMessage is enabled

    • Using the same Apple ID as your Mac

  2. 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)

  3. 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.

2

Step 2: Verify Apple ID and iMessage Login

Ensure both devices are properly authenticated with iMessage:

On iPhone:

  1. Open Settings

  2. Tap your name at the top → Apple ID

  3. Verify you're signed in

  4. Go to iCloud → scroll to Messages

  5. Ensure "Sync this iPhone" is ON

  6. Go back to main Settings → Messages

  7. Verify iMessage is ON (toggle should be green)

  8. Check that your phone number appears under "Send & Receive"

On Mac:

  1. Open Messages app

  2. Go to Messages → Settings (or Preferences)

  3. Click iMessage tab

  4. Verify you're signed in with same Apple ID as iPhone

  5. Check "Enable Messages in iCloud" is selected

  6. Confirm your phone number is listed under "You can be reached for messages at"

  7. 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

3

Step 3: Send Test Messages

Verify basic iMessage functionality works before testing WhatSnap integration:

Test 1: Mac to Mac/iPhone iMessage

  1. Open Messages app on your Mac

  2. Send a test iMessage to a friend's iPhone or another iMessage user

  3. Verify the message sends (should show as blue bubble)

  4. Confirm message appears on your iPhone as well (sync test)

  5. Have the recipient reply

  6. Verify reply appears on both your Mac and iPhone

Test 2: WhatSnap Integration Test

  1. In GoHighLevel, open a contact record

  2. Add your iMessage account tag (e.g., whatsnap-account-imessage)

  3. Go to Conversations tab

  4. Send a test message to this contact

  5. 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.

4

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:

  1. Open System Settings (or System Preferences)

  2. Click Privacy & Security

  3. Scroll down to "Full Disk Access" in the left sidebar

  4. Click the lock icon at bottom left and authenticate

  5. Click the "+" button

  6. Navigate to Applications folder

  7. Select WhatSnap Gateway app

  8. Click "Open" to add it to the list

  9. Ensure the checkbox next to WhatSnap Gateway is checked

  10. 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

5

Step 5: Check Channel Integration Settings

Verify your WhatSnap channel integration is configured correctly in GoHighLevel:

Using SMS Channel Override (Recommended):

  1. In GoHighLevel, go to Settings → Phone Numbers

  2. Under "SMS Configuration", verify WhatSnap has replaced SMS

  3. Your iMessage messages should route through the SMS tab

  4. Test by sending a message - should use iMessage for tagged contacts

Using Separate WhatSnap Channel:

  1. In GoHighLevel conversations, look for WhatSnap or iMessage tab

  2. Ensure you're clicking the correct channel when messaging

  3. Verify the contact has the proper account tag

Account Tag Verification:

  1. Open the contact in GoHighLevel

  2. Check Tags section for your iMessage account tag (e.g., whatsnap-account-imessage)

  3. If missing, add the tag manually

  4. 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.

6

Step 6: Reconnect WhatSnap Gateway App

If issues persist after previous steps, try reconnecting the Gateway app:

Disconnect and Reconnect:

  1. Open WhatSnap Gateway app on your Mac

  2. Click "Log Out" or "Disconnect" in the app menu

  3. Quit the WhatSnap Gateway app completely (Cmd+Q)

  4. Go to your WhatSnap Dashboard in GoHighLevel

  5. Navigate to Devices or Connected Accounts

  6. Find your Mac device

  7. Click "Regenerate Token" or "Get New Token"

  8. Copy the new authentication token

  9. Reopen WhatSnap Gateway app

  10. Paste the new token and click "Connect"

  11. 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

7

Step 7: Check Power and Sleep Settings

A very common issue: Mac going to sleep stops the gateway from working.

Verify Energy Settings:

  1. Open System Settings → Energy (or Battery)

  2. 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"

  3. Disable "Power Nap" (can interfere)

  4. 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:

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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:

  1. 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

  2. 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

  3. 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

  4. 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:

  1. 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

  2. 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

  3. 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

  4. 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:

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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:

  1. Network Connectivity Issues

    • Check Mac has internet connection

    • Try loading a website in browser

    • Restart WiFi/Ethernet if needed

    • Check router is working properly

  2. Firewall Blocking Connection

    • System Settings → Network → Firewall

    • If enabled, click "Firewall Options"

    • Ensure WhatSnap Gateway is allowed

    • Consider temporarily disabling firewall to test

  3. 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

  4. WhatSnap Server Issues

    • Rarely, WhatSnap servers may have temporary issues

    • Check WhatSnap status page or Twitter for updates

    • Contact support if widespread issue suspected

  5. 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:

  1. 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

  2. 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

  3. 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

  4. 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:

  1. 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

  2. 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

  3. Hard Disk Sleep

    • Disable "Put hard disks to sleep when possible"

    • Can prevent gateway app from running properly

    • Found in Energy settings

  4. Power Nap Interference

    • Disable "Enable Power Nap"

    • Can cause unpredictable sleep behavior

    • Found in Energy settings

  5. 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

  6. 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:

  1. 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

  2. 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

  3. 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

  4. 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:

  1. Full Disk Access (Most Important)

    • System Settings → Privacy & Security → Full Disk Access

    • Add WhatSnap Gateway and check the box

    • Restart app after granting

  2. Accessibility Permissions

    • System Settings → Privacy & Security → Accessibility

    • Add WhatSnap Gateway if requested

    • May be needed for some features

  3. Security & Privacy Settings

    • System Settings → Privacy & Security

    • Under "Security" section

    • Click "Allow" for WhatSnap Gateway if blocked

    • May need to reinstall if repeatedly blocked

  4. 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"

  5. 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?

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:

  1. Email Support: support@whatsnap.ai

    • Include all information listed above

    • Attach screenshots

    • Link to Loom video if possible

  2. Submit Support Ticket:

    • Log into WhatSnap Dashboard

    • Navigate to Support or Help section

    • Submit detailed ticket with information above

  3. 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

Last Updated: For the latest setup instructions, see the Adding iMessage Accounts guide.

PreviousMultiple iMessage Accounts per Sub-AccountNextSettings

Last updated