# iMessage Troubleshooting

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.

{% hint style="info" %}
**SMS vs iMessage Issues**: If you're having trouble specifically with SMS messages (to Android users), check the [SMS Fallback Issues](#sms-fallback-not-working-to-android) section. For general iMessage problems, continue with the steps below.
{% endhint %}

{% hint style="danger" %}
**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](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/imessage-account-blocked) for recovery steps.
{% endhint %}

## Quick Diagnostic Checklist

Before diving into detailed troubleshooting, quickly verify these common issues:

* [ ] WhatSnap Gateway 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 **account tag** in GoHighLevel
* [ ] Your WhatSnap account is **active** (not expired trial)

{% hint style="warning" %}
**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!
{% endhint %}

## Systematic Troubleshooting Steps

Follow these steps in order to diagnose and resolve iMessage integration issues:

{% stepper %}
{% step %}

#### 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](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage) guide for detailed setup instructions.
{% endstep %}

{% step %}

#### 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
  {% endstep %}

{% step %}

#### 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.
{% endstep %}

{% step %}

#### 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**

{% hint style="warning" %}
**Critical Permission**: Without Full Disk Access, the WhatSnap Gateway cannot access your Messages database and will fail to send/receive messages silently.
{% endhint %}

**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
  {% endstep %}

{% step %}

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

{% hint style="info" %}
**Tag Required**: Every contact must have an iMessage account tag for WhatSnap to route messages through your Mac. No tag = no message delivery.
{% endhint %}
{% endstep %}

{% step %}

#### 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
  {% endstep %}

{% step %}

#### 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](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage-specifications#power--reliability-configuration) section for detailed configuration.
{% endstep %}
{% endstepper %}

## Common Issues and Solutions

### Messages Not Sending from GoHighLevel

<details>

<summary>No messages appear in Mac Messages app when sending from GHL</summary>

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

</details>

<details>

<summary>Messages send from Mac but not showing in GoHighLevel</summary>

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

</details>

### SMS Fallback Not Working (to Android)

<details>

<summary>Can't send SMS to Android users (green bubbles)</summary>

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

</details>

### Device Sync and Connection Issues

<details>

<summary>iPhone and Mac not syncing messages</summary>

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

</details>

<details>

<summary>WhatSnap Gateway shows as disconnected</summary>

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

</details>

### Performance and Reliability Issues

<details>

<summary>Messages delayed or taking long time to send</summary>

**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](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/imessage-specifications) for RAM requirements

</details>

<details>

<summary>Mac keeps going to sleep despite settings</summary>

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

</details>

## Advanced Troubleshooting

### Multiple iPhone Accounts Issues

<details>

<summary>Problems running multiple iMessage accounts on one Mac</summary>

**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](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage-specifications#multiple-iphone-setup-advanced) for detailed configuration.

</details>

### Permissions and Security Issues

<details>

<summary>Permission errors or security warnings</summary>

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

</details>

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

{% hint style="info" %}
**Get Help**: If you've followed all troubleshooting steps and still face issues, our support team is here to help.
{% endhint %}

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

* [**Adding iMessage Accounts**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage) - Complete setup guide
* [**Multiple iMessage Accounts**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/multiple-imessage-accounts) - Connect multiple iMessage numbers for teams
* [**iMessage Account Blocked**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/imessage-account-blocked) - Recover from Apple iMessage deactivation
* [**iMessage Device Specifications**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/imessage-specifications) - Hardware requirements and recommendations
* [**Account Settings**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/settings/account-settings) - Configure account preferences
* [**Tag Management**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/settings/tag-management) - Understanding account tags and routing
* [**Conversations**](https://github.com/WhatSnap/documentation/blob/main/conversations/messaging-basics.md) - Using iMessage for messaging

***

**Last Updated**: For the latest setup instructions, see the [Adding iMessage Accounts](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage) guide.
