# iMessage

Connect your iPhone and Mac to WhatSnap to send and receive iMessages and SMS directly through GoHighLevel. This personal device integration (P2P) gives you the power of iMessage's high engagement rates combined with GHL's automation capabilities.

{% hint style="success" %}
**Personal Device Power**: Using your own iPhone/Mac for iMessage allows you to leverage Apple's messaging ecosystem with its superior deliverability and engagement rates, all managed through GoHighLevel.
{% endhint %}

{% hint style="warning" %}
**Important Usage Guidelines**:

* iMessage accounts are designed for **personal, relationship-based messaging**, not bulk outreach
* Recommended limit: **50 unique contacts per day** to maintain good standing with Apple
* Your Mac must remain **powered on and connected to the internet** for messages to send/receive
* Best suited for: Sales follow-ups, customer service, VIP communications
  {% endhint %}

## Prerequisites

Before connecting your iMessage account to WhatSnap, ensure you have:

* ✅ **iPhone** with active iMessage and cellular service (iOS 12.0+)
* ✅ **Mac** (MacBook, iMac, or Mac mini) running macOS Monterey 12.4 or later
* ✅ **Same Apple ID** signed in on both iPhone and Mac
* ✅ **Active internet connection** on both devices
* ✅ **WhatSnap account** connected to your GoHighLevel sub-account

{% hint style="info" %}
**Hardware Requirements**: Not sure if your devices are compatible? Check our [**iMessage Device Specifications**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/imessage-specifications) guide for detailed hardware requirements, supported models, and Mac recommendations.
{% endhint %}

## Overview: How iMessage Integration Works

{% @mermaid/diagram content="graph TD;
A\["📱 iPhone + Mac"] --> B\["☁️ iCloud Messages Sync"];
B --> C\["💻 WhatSnap Mac App"];
C --> D\["🔗 WhatSnap Cloud"];
D --> E\["🏢 GoHighLevel"];
E --> F\["💬 Send/Receive Messages"];
F --> G{Recipient Device?};
G -->|"📱 iPhone"| H\["💙 iMessage (Blue Bubble)"];
G -->|"📲 Android"| I\["💚 SMS Fallback (Green Bubble)"];
H --> J\["✅ Message Delivered"];
I --> J;

```
classDef apple fill:#e3f2fd,stroke:#1976d2,stroke-width:3px,color:#000000;
classDef whatsnap fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000000;
classDef ghl fill:#e8f5e8,stroke:#00695c,stroke-width:2px,color:#000000;
classDef message fill:#e1f5fe,stroke:#3f51b5,stroke-width:2px,color:#000000;

class A,B apple;
class C,D whatsnap;
class E ghl;
class F,G,H,I,J message;" %}
```

## Part 1: Sync Your iPhone and Mac

Before installing the WhatSnap gateway, you need to ensure your Apple devices are properly synced.

{% stepper %}
{% step %}

#### iPhone Setup - Enable Messages in iCloud

This allows your messages to sync across all your Apple devices:

1. Open **Settings** on your iPhone
2. Tap on your **Apple ID** name at the top
3. Sign in with your Apple ID if not already signed in
4. Select **iCloud**
5. Scroll down and tap **Messages**
6. Toggle **Sync this iPhone** (or "Messages in iCloud") to **ON**
7. Wait a few moments for sync to complete

{% hint style="info" %}
**What This Does**: Enables message syncing across all devices signed in with your Apple ID, ensuring replies and conversations stay in sync between your iPhone and Mac.
{% endhint %}
{% endstep %}

{% step %}

#### Mac Setup - Configure iMessage

Set up iMessage on your Mac to work with WhatSnap:

1. Open the **Messages** app on your Mac
2. Sign in with the **same Apple ID** used on your iPhone
3. Go to **Messages** → **Settings** (or **Preferences** on older macOS)
4. Click the **iMessage** tab
5. Check the box for **Enable Messages in iCloud**
6. Under **"You can be reached for messages at"**, ensure your phone number is checked
7. Under **"Start new conversations from"**, select your **phone number** (NOT your email)
   * ⚠️ This is crucial - uncheck your email address to avoid confusion

{% hint style="warning" %}
**Critical Setting**: Always start conversations from your **phone number**, not your email. This ensures proper routing and delivery tracking in WhatSnap.
{% endhint %}
{% endstep %}

{% step %}

#### Test the Sync

Verify that your devices are properly synced before proceeding:

1. On your **Mac**, send a test iMessage to a friend or secondary phone
2. Verify the message appears on both your Mac and iPhone
3. Have the recipient reply
4. Confirm the reply appears on both devices

{% hint style="success" %}
**Sync Confirmed!** If messages appear on both devices, you're ready to proceed to installing the WhatSnap gateway app.
{% endhint %}
{% endstep %}
{% endstepper %}

## Part 2: Download & Connect WhatSnap Gateway

Now that your devices are synced, install the WhatSnap Mac app to connect your iMessage to GoHighLevel.

{% stepper %}
{% step %}

#### Access WhatSnap Dashboard

1. Log in to your **WhatSnap Plugin** in GoHighLevel
2. Navigate to **Connected Accounts** or **Devices**
3. Click **"Add Account"** or **"Add Device"**
4. Select **"SMS/iMessage (P2P)"** from the account type options
   {% endstep %}

{% step %}

#### Download the WhatSnap Mac App

1. Click **"Connect Device"** for Mac
2. Download the **WhatSnap Gateway App** for Mac from the provided link
3. **Unzip** the downloaded file
4. **Move the app** to your **Applications** folder

**If macOS blocks the installation:**

1. Open **System Settings** (or **System Preferences**)
2. Go to **Privacy & Security**
3. Scroll down to **Security**
4. Click **"Allow"** next to the blocked WhatSnap app message
5. Alternatively, click **"Open Anyway"** if prompted

{% hint style="info" %}
**Security Note**: The WhatSnap app is safe to install. macOS blocks apps from unidentified developers by default. You may need to explicitly allow the app in your security settings.
{% endhint %}
{% endstep %}

{% step %}

#### Launch and Authenticate

1. Open the **WhatSnap Gateway** app from your Applications folder
2. Read and agree to the **Terms of Use**
3. **Copy** the authentication token from your WhatSnap dashboard
4. **Paste** the token into the Mac app
5. Click **"Connect"** or **"Log In"**

**Important Usage Agreement:**

* iMessage should **not** be used for bulk messaging
* Recommended maximum: **50 unique contacts per day**
* Violating Apple's terms may result in account restrictions

{% hint style="warning" %}
**Keep Running**: The WhatSnap Gateway app must remain open and running on your Mac for messages to send and receive. We recommend keeping your Mac on 24/7 or using power settings to prevent sleep.
{% endhint %}
{% endstep %}

{% step %}

#### Verify Connection

Once authenticated, verify your device appears in WhatSnap:

1. Return to your **WhatSnap Dashboard** in GoHighLevel
2. **Refresh** the page or devices list
3. You should see your Mac listed as a **connected iMessage device**
4. Status should show as **"Connected"** or **"Active"**

{% hint style="success" %}
**Device Connected!** Your Mac is now bridging your iMessage to GoHighLevel through WhatSnap.
{% endhint %}
{% endstep %}
{% endstepper %}

## Part 3: Configure WhatSnap Settings

After connecting your device, configure how WhatSnap integrates with GoHighLevel.

{% stepper %}
{% step %}

#### Assign Device to Sub-Account

If you have multiple GoHighLevel sub-accounts:

1. In your **WhatSnap Dashboard**, locate your newly connected Mac device
2. Click on the device **settings** or **menu** (⋮)
3. Select **"Assign to Sub-Account"**
4. Choose the **GoHighLevel sub-account** where you want to use this iMessage account
5. Click **"Assign"** or **"Save"**

{% hint style="info" %}
**Multi-Location Users**: If you manage multiple locations, you can assign the same device to different sub-accounts, or connect multiple Mac devices for different locations.
{% endhint %}
{% endstep %}

{% step %}

#### Configure Channel Integration

Choose how iMessage integrates with your GoHighLevel conversations:

**Option 1: SMS Channel Override (Recommended)**

* WhatSnap replaces your existing SMS channel
* iMessages appear in the SMS conversation tab
* Works seamlessly with existing SMS workflows
* All SMS workflow actions automatically use iMessage (when messaging iPhones)

**Option 2: Separate iMessage Channel**

* WhatSnap appears as a separate tab in conversations
* Maintains existing SMS functionality
* Requires specific channel selection when messaging

{% hint style="success" %}
**Recommendation**: Use **SMS Channel Override** for the smoothest experience. Your existing workflows will automatically work with iMessage, and you can still send regular SMS as fallback to Android devices.
{% endhint %}
{% endstep %}

{% step %}

#### Set Up Account Tag

WhatSnap automatically creates a unique tag for your iMessage account:

1. Note your account tag (e.g., `whatsnap-account-imessage`)
2. This tag will be **automatically applied** to contacts who message this iMessage account
3. Use this tag in workflows and filters to target iMessage contacts

**Tag Usage:**

* Messages to contacts with this tag will route through your Mac iMessage
* You can manually add/remove this tag to control which account contacts use
* Use the tag in GHL workflows for iMessage-specific automation
  {% endstep %}
  {% endstepper %}

## Part 4: Sending Your First iMessage

Test your setup by sending messages through GoHighLevel.

{% stepper %}
{% step %}

#### Manual Message Test

1. In **GoHighLevel**, open or create a contact
2. Navigate to the **Conversations** tab
3. Add the **iMessage account tag** to the contact (e.g., `whatsnap-account-imessage`)
4. Click on **SMS** (if using override) or **WhatSnap** (if using separate channel)
5. Type a test message
6. Click **Send**

**What to Expect:**

* To an **iPhone**: Message sends as **iMessage** (blue bubble on recipient's phone)
* To an **Android**: Message sends as **SMS** (green bubble) using your iPhone's cellular plan
* Message appears in your Mac's Messages app
* Replies sync to both your Mac and GoHighLevel
  {% endstep %}

{% step %}

#### Verify Delivery

Check that the message was delivered:

1. Open the **Messages app** on your Mac
2. Find the conversation you just sent
3. Verify the message appears
4. Check for **"Delivered"** status on iPhone recipients
5. For Android, message sends as regular SMS

{% hint style="info" %}
**Delivery Status**: iMessages show "Delivered" and "Read" receipts (if enabled by recipient). SMS messages show "Delivered" when successfully sent to the carrier.
{% endhint %}
{% endstep %}

{% step %}

#### Test Receiving Messages

1. Have someone reply to your test message
2. The reply should appear in:
   * Your **Mac Messages app**
   * Your **iPhone Messages app**
   * **GoHighLevel conversations** tab
3. All devices should stay in sync

{% hint style="success" %}
**Bidirectional Sync!** Replies work in both directions, and you can respond from either GoHighLevel or your Mac Messages app.
{% endhint %}
{% endstep %}
{% endstepper %}

## Understanding Message Routing

### How WhatSnap Routes Messages

{% @mermaid/diagram content="graph TD;
A\["👤 GHL User Sends Message"] --> B\["🏷️ Check Contact Tag"];
B --> C{Has iMessage Tag?};
C -->|"✅ Yes"| D\["📱 Check Recipient Device"];
C -->|"❌ No"| E\["❌ Error: No Account Tag"];
D --> F{Is iPhone?};
F -->|"✅ Yes"| G\["💙 Send via iMessage"];
F -->|"❌ No"| H\["💚 Send via SMS Fallback"];
G --> I{Mac Online?};
H --> J{iPhone Online?};
I -->|"✅ Yes"| K\["✅ Delivered"];
I -->|"❌ No"| L\["❌ Failed: Mac Offline"];
J -->|"✅ Yes"| K;
J -->|"❌ No"| M\["❌ Failed: iPhone Offline"];

```
classDef user fill:#e3f2fd,stroke:#1976d2,stroke-width:3px,color:#000000;
classDef process fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000000;
classDef decision fill:#e1f5fe,stroke:#3f51b5,stroke-width:2px,color:#000000;
classDef success fill:#e8f5e8,stroke:#00695c,stroke-width:2px,color:#000000;
classDef error fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#000000;

class A user;
class B,D,G,H process;
class C,F,I,J decision;
class K success;
class E,L,M error;" %}
```

### Message Behavior

| Recipient Type        | Delivery Method  | Requirements                   | Appearance                          |
| --------------------- | ---------------- | ------------------------------ | ----------------------------------- |
| **iPhone User**       | iMessage         | Mac online, iMessage enabled   | Blue bubble, "Delivered" status     |
| **Android User**      | SMS (via iPhone) | iPhone online, cellular active | Green bubble, SMS charges may apply |
| **Unknown/No Number** | Fails            | -                              | Error message in GHL                |

{% hint style="warning" %}
**SMS Fallback Limitations**: When sending to Android devices, your iPhone must be online and have cellular service. SMS messages use your carrier plan and may incur charges.
{% endhint %}

## Workflow Automation with iMessage

### Using iMessage in GHL Workflows

When using **SMS Channel Override**, your workflows work automatically:

**Example Workflow - iMessage Follow-up:**

```
Trigger: Tag added → "whatsnap-account-imessage"
Wait: 5 minutes
Action: Send SMS (automatically sends via iMessage)
Message: "Hi {{first_name}}, thanks for reaching out! How can I help you today?"
```

**Key Points:**

* Use standard **"Send SMS"** actions in workflows
* Messages automatically route through iMessage for tagged contacts
* To iPhone: Sends as iMessage
* To Android: Sends as SMS fallback via your iPhone

### Advanced: Using #switch Commands

Switch between messaging accounts using WhatSnap commands:

**Permanently switch to iMessage:**

```
#switch|whatsnap-account-imessage Hi {{first_name}}, I'm following up personally via iMessage...
```

**Send one message via iMessage, then return to original account:**

```
#switch_unique|whatsnap-account-imessage This is a personal check-in from our team...
```

{% hint style="info" %}
**Command Benefits**: Use commands to dynamically route messages between different accounts (WhatsApp, SMS, iMessage, Twilio) based on conversation context or contact preferences.
{% endhint %}

## Best Practices

### Daily Usage Guidelines

{% tabs %}
{% tab title="Volume Limits" %}
**Apple's Unspoken Rules**

While Apple doesn't publish official limits, staying within these guidelines keeps your account healthy:

* **50 unique contacts per day** (maximum recommended)
* **Space out messages** throughout the day
* **Avoid identical messages** to multiple recipients
* **Engage naturally** - don't just broadcast

**Why These Limits Matter:**

* Apple monitors for spam-like behavior
* Exceeding limits may trigger temporary restrictions
* Multiple violations could lead to permanent iMessage blocks
* Personal accounts are not designed for mass messaging
  {% endtab %}

{% tab title="Device Management" %}
**Keeping Your Mac Ready**

For reliable 24/7 operation:

**Power Settings:**

* **Prevent Sleep**: System Settings → Energy → Prevent automatic sleeping
* **Display**: Allow display to sleep, but keep Mac awake
* **Power Nap**: Disabled for consistency

**Alternative: Use Amphetamine App**

* Free Mac app to keep your Mac awake
* Available on Mac App Store
* Recommended for Mac mini or headless setups

**Gateway App:**

* Keep WhatSnap Gateway app **always running**
* Add to **Login Items** for auto-start on boot
* Monitor the app icon in menu bar for connection status

**Internet Connection:**

* Use **wired Ethernet** for most reliable connection
* If using WiFi, ensure strong signal strength
* Have backup internet (mobile hotspot) for critical operations
  {% endtab %}

{% tab title="Message Quality" %}
**Maintain Personal Touch**

iMessage works best for relationship-based messaging:

**Do:**

* ✅ Personal follow-ups and check-ins
* ✅ Customer service conversations
* ✅ Sales relationship building
* ✅ VIP customer communications
* ✅ Appointment reminders and confirmations

**Don't:**

* ❌ Mass promotional campaigns
* ❌ Cold outreach at scale
* ❌ Identical messages to many recipients
* ❌ Excessive daily volume
* ❌ Automated spam-like content

**Message Characteristics:**

* Use recipient's name and personal details
* Reference previous conversations
* Keep tone conversational and authentic
* Allow time for responses before following up
  {% endtab %}
  {% endtabs %}

### Ideal Use Cases

**Perfect For:**

* **Sales Follow-ups**: Personal touch after initial contact via WhatsApp or other channels
* **Customer Success**: High-touch support for VIP customers
* **Appointment Reminders**: Personal reminders with high open rates
* **Relationship Building**: One-on-one conversations at scale
* **Internal Team Communication**: Coordinate with team members who use iPhones

**Not Ideal For:**

* ❌ Cold outreach campaigns (use WhatsApp or Twilio instead)
* ❌ High-volume promotional blasts (use Twilio SMS)
* ❌ International messaging (use WhatsApp)
* ❌ Conversations requiring 99.9% uptime (use Twilio)

## Multi-Platform Strategy

### Combining iMessage with Other Channels

WhatSnap allows you to use multiple messaging platforms together:

**Example Strategy:**

{% @mermaid/diagram content="graph LR;
A\["📢 Initial Outreach"] --> B\["WhatsApp Campaign"];
B --> C{Engaged?};
C -->|"✅ Yes"| D\["🔄 Switch to iMessage"];
C -->|"❌ No"| E\["Continue WhatsApp"];
D --> F\["💬 Personal Follow-up"];
F --> G{Converted?};
G -->|"✅ Yes"| H\["📲 iMessage for Support"];
G -->|"❌ No"| I\["📧 Email Sequence"];

```
classDef outreach fill:#e3f2fd,stroke:#1976d2,stroke-width:2px;
classDef engage fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;
classDef convert fill:#e8f5e8,stroke:#00695c,stroke-width:2px;

class A,B outreach;
class D,F engage;
class H convert;" %}
```

**Platform Selection Guide:**

| Scenario                | Best Platform | Reason                             |
| ----------------------- | ------------- | ---------------------------------- |
| Initial cold outreach   | WhatsApp      | Higher volume, international reach |
| Qualified leads         | iMessage      | Personal touch, higher engagement  |
| Enterprise clients      | Twilio SMS    | Reliability, compliance, SLA       |
| International customers | WhatsApp      | Global adoption, no SMS charges    |
| VIP relationships       | iMessage      | Personal device, authentic feel    |
| Mass notifications      | Twilio SMS    | Scale, reliability, uptime         |

## Troubleshooting

{% hint style="info" %}
**Need Help?** For comprehensive troubleshooting, see our detailed [**iMessage Troubleshooting Guide**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/troubleshooting-imessage) with step-by-step solutions for all common issues.
{% endhint %}

### Quick Solutions for Common Issues

<details>

<summary>Messages Not Sending</summary>

**Possible Causes:**

* WhatSnap Gateway app not running on Mac
* Mac is asleep or offline
* iMessage not properly synced
* Contact doesn't have iMessage account tag

**Solutions:**

1. Check that WhatSnap Gateway app is **open and running** on your Mac
2. Verify your Mac is **powered on** and **connected to internet**
3. Check **Messages app** on Mac - ensure you're signed in
4. Verify contact has the **correct account tag** in GHL
5. Test by sending a message directly from Mac Messages app
6. Restart the WhatSnap Gateway app
7. Re-authenticate if necessary

**Still having issues?** See the complete [iMessage Troubleshooting Guide](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/troubleshooting-imessage).

</details>

<details>

<summary>Mac Keeps Going to Sleep</summary>

**Possible Causes:**

* Energy Saver settings configured for sleep
* Display sleep triggering system sleep
* Power settings override

**Solutions:**

1. Open **System Settings** → **Energy** (or **Battery**)
2. Set **"Prevent automatic sleeping"** when plugged in
3. Adjust **"Turn display off after"** (display can sleep, Mac stays awake)
4. Disable **Power Nap** (can interfere with gateway)
5. **Alternative**: Install **Amphetamine** app to force Mac awake
6. For Mac mini: Disconnect display, use screen sharing for access

</details>

<details>

<summary>SMS Fallback Not Working</summary>

**Possible Causes:**

* iPhone not online or not connected to cellular
* iPhone not properly linked to Mac
* SMS forwarding not configured

**Solutions:**

1. Ensure **iPhone is online** with active cellular connection
2. Check **Messages app** on Mac → Preferences → iMessage
3. Verify **phone number is visible** and checked
4. On iPhone: Settings → Messages → **Text Message Forwarding** → Enable for your Mac
5. Test by sending an SMS directly from your Mac to an Android number
6. Restart both iPhone and Mac if sync issues persist

</details>

<details>

<summary>Replies Not Syncing to GHL</summary>

**Possible Causes:**

* Gateway app disconnected
* Authentication token expired
* Network connectivity issues

**Solutions:**

1. Check WhatSnap Gateway app status icon (should be connected)
2. Re-authenticate the app with a **fresh token** from WhatSnap dashboard
3. Check **internet connection** on Mac
4. Verify **firewall settings** aren't blocking the app
5. Restart the Gateway app
6. Check WhatSnap dashboard to see if device shows as "Connected"

</details>

<details>

<summary>Apple ID Restrictions or Warnings</summary>

**Possible Causes:**

* Exceeded daily volume limits
* Sent too many identical messages
* Flagged as spam-like behavior

**Solutions:**

1. **Immediately reduce volume** - stop all automated messaging
2. **Wait 24-48 hours** before resuming
3. Stay under **50 unique contacts per day** going forward
4. **Vary your messages** - don't send identical content
5. **Space out messages** throughout the day
6. Focus on **quality conversations** over quantity
7. If severe: Contact Apple Support for account review

</details>

## Security and Privacy

### Data Protection

{% hint style="info" %}
**Your Data, Your Control**: The WhatSnap Gateway app on your Mac creates a secure bridge between your local iMessage and WhatSnap cloud. Messages are encrypted in transit and processed according to our privacy policy.
{% endhint %}

**Security Features:**

* **End-to-end encryption** for iMessages (Apple's native encryption)
* **Secure authentication** token system
* **Local processing** on your Mac before cloud sync
* **No message storage** on WhatSnap servers beyond delivery
* **Compliance** with Apple's terms of service

**Your Responsibilities:**

* Keep your **Mac secure** with password protection
* Don't share your **authentication token**
* **Log out** from WhatSnap Gateway app when not in use
* Use **strong passwords** for your Apple ID
* Enable **two-factor authentication** on your Apple ID

## Next Steps

After successfully connecting your iMessage account:

1. [**iMessage Device Specifications**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/imessage-specifications) - Review hardware requirements and multi-device setup
2. [**Multiple iMessage Accounts**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/multiple-imessage-accounts) - Connect multiple iMessage numbers for team collaboration and increased volume
3. [**iMessage Troubleshooting**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/troubleshooting-imessage) - Comprehensive guide for resolving issues
4. [**iMessage Account Blocked**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/imessage/imessage-account-blocked) - Recover from iMessage deactivation by Apple
5. [**Account Settings**](https://github.com/WhatSnap/documentation/blob/main/Account-management/imessage/account-settings.md) - Configure typing simulation and other iMessage-specific settings
6. [**Tag Management**](https://github.com/WhatSnap/documentation/blob/main/Account-management/imessage/tag-management.md) - Master using tags to route messages between different platforms
7. [**User Assignments**](https://github.com/WhatSnap/documentation/blob/main/Account-management/imessage/user-assignments.md) - Set up automatic assignment for iMessage conversations
8. [**Conversations**](https://github.com/WhatSnap/documentation/blob/main/Account-management/conversations/messaging-basics.md) - Start messaging contacts through iMessage
9. [**Workflow Integration**](https://github.com/WhatSnap/documentation/blob/main/Account-management/conversations/workflow-automation.md) - Automate iMessage communications

{% hint style="success" %}
**Ready to Message!** Your iMessage account is now connected to WhatSnap. Remember to keep your Mac running and stay within Apple's usage guidelines for best results.
{% endhint %}

***

**Questions or Issues?** Contact WhatSnap support at <support@whatsnap.ai> or check our troubleshooting guides for additional help.
