# SMS Installation & Setup

This comprehensive guide walks you through the complete process of connecting your Android device to WhatSnap for SMS messaging through GoHighLevel.

{% hint style="info" %}
**Time Required**: 15-20 minutes for complete setup
{% endhint %}

## Prerequisites Checklist

Before beginning installation, ensure you have:

* ✅ **Android device** with Android 9.0+ and minimum 2 GB RAM ([See specifications](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/sms-specifications))
* ✅ **Active SIM card** installed and tested (can send/receive SMS)
* ✅ **WhatSnap account** installed in your GoHighLevel sub-account
* ✅ **Internet connection** (WiFi or mobile data)
* ✅ **Device charger** (keep device plugged in during setup)
* ✅ **GoHighLevel login** credentials ready

## Installation Overview

The installation process consists of three main parts:

{% @mermaid/diagram content="graph LR;
A\["Part 1<br/>Integrate WhatSnap<br/>with GoHighLevel"] --> B\["Part 2<br/>Setup Android<br/>Device"];
B --> C\["Part 3<br/>Configure WhatSnap<br/>Settings"];
C --> D\["Part 4<br/>Send Test<br/>Message"];

```
classDef part1 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000000;
classDef part2 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000000;
classDef part3 fill:#e8f5e8,stroke:#00695c,stroke-width:2px,color:#000000;
classDef part4 fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000000;

class A part1;
class B part2;
class C part3;
class D part4;" %}
```

***

## Part 1: Integrating WhatSnap with GoHighLevel

Connect your WhatSnap account with your GoHighLevel sub-account to enable SMS messaging.

{% stepper %}
{% step %}

#### Log In to WhatSnap Dashboard

1. Log in to your **GoHighLevel account**
2. Navigate to the **sub-account** where WhatSnap is installed
3. Click on the **WhatSnap** tab in the left sidebar
4. You'll land on the WhatSnap dashboard

{% hint style="info" %}
**First Time Setup**: If you haven't installed WhatSnap yet, follow the [Quick Start Guide](https://whatsnap.gitbook.io/whatsnap-docs/quick-start) to install the plugin first.
{% endhint %}
{% endstep %}

{% step %}

#### Access Connected Accounts

1. In the WhatSnap dashboard, navigate to **Connected Accounts** or **Devices**
2. Click **"Add Account"** or **"Add Device"**
3. You'll see account type options:
   * WhatsApp
   * **SMS/iMessage (P2P)** ← Select this
   * Twilio SMS
     {% endstep %}

{% step %}

#### Select Android SMS

1. Click on **"SMS/iMessage (P2P)"**
2. Choose **"Android"** as your device type
3. The system will prepare your connection settings

{% hint style="warning" %}
**Important**: Make sure you're logged into **app.gohighlevel.com** (not just your white-label domain) for proper integration.
{% endhint %}
{% endstep %}

{% step %}

#### Choose Integration Method

Select how WhatSnap integrates with GoHighLevel:

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

* WhatSnap replaces your existing SMS channel
* All SMS workflows automatically use your Android device
* Seamless integration with existing automations

**Option 2: Custom WhatSnap Channel**

* WhatSnap appears as a separate messaging channel
* Keeps existing SMS functionality intact
* Requires specific channel selection when messaging

{% hint style="success" %}
**Recommendation**: Choose **SMS Channel Override** for the smoothest experience and full workflow compatibility.
{% endhint %}
{% endstep %}

{% step %}

#### Note Your Authentication Details

1. The WhatSnap dashboard will display a **QR code** and/or **authentication token**
2. Keep this screen open - you'll need it in Part 2
3. Do not share this QR code or token with anyone
   {% endstep %}
   {% endstepper %}

***

## Part 2: Setting Up Your Android Device

Now configure your Android device and install the WhatSnap Gateway app.

{% stepper %}
{% step %}

#### Prepare Your Device - Disable Play Protect

Google Play Protect may block installation of apps from outside the Play Store.

1. Open the **Google Play Store** app on your Android device
2. Tap your **profile icon** (top right)
3. Tap **Play Protect**
4. Tap the **Settings** icon (gear icon, top right)
5. Toggle **OFF**: "Scan apps with Play Protect"

{% hint style="info" %}
**Why This Step**: WhatSnap Gateway is distributed as an APK file (not via Google Play Store). Disabling Play Protect allows you to install the app. This is safe - WhatSnap is a legitimate application.
{% endhint %}
{% endstep %}

{% step %}

#### Turn Off RCS (Rich Communication Services)

RCS can interfere with SMS delivery in some configurations.

1. Open the **Messages** app (Google Messages)
2. Tap your **profile icon** (top right)
3. Go to **Messages settings**
4. Tap **RCS chats** (or "Chat features")
5. Toggle **OFF**: "Enable chat features"

{% hint style="warning" %}
**Exception**: If using an **eSIM from another country** to send SMS over WiFi, you'll need RCS **enabled**. See [RCS Settings Guide](https://whatsnap.gitbook.io/whatsnap-docs/faq/sms/rcs-settings) for details.
{% endhint %}

**For more details**: [RCS Settings Guide](https://whatsnap.gitbook.io/whatsnap-docs/faq/sms/rcs-settings)
{% endstep %}

{% step %}

#### Download the WhatSnap Gateway App

1. On your Android device, open **Chrome** browser
2. Return to your **WhatSnap dashboard** on your computer
3. You'll see a **download link** for the Android APK
4. Use your phone to visit the download URL, or:
   * Scan a QR code if provided
   * Send yourself the link via email

**Alternative**: Some setups provide a direct download link you can access on your phone

5. **Download** the APK file
6. If prompted about downloading from unknown sources, tap **"OK"** or **"Download anyway"**
   {% endstep %}

{% step %}

#### Install the WhatSnap Gateway App

1. Once downloaded, tap the **APK file** in your downloads or notification
2. You may see: **"For your security, your phone is not allowed to install unknown apps from this source"**
3. Tap **"Settings"**
4. Toggle **ON**: "Allow from this source" (for Chrome or your browser)
5. Tap the **back button**
6. Tap **"Install"**

**If Play Protect warning appears:**

* You'll see: "App blocked by Play Protect"
* Tap **"More details"**
* Tap **"Install anyway"**

7. Wait for installation to complete
8. Tap **"Open"** to launch the app
   {% endstep %}

{% step %}

#### Grant App Permissions

The WhatSnap Gateway app requires several permissions to function.

**Initial Launch:**

1. Open the WhatSnap Gateway app (if not already open)
2. You may be prompted to allow SMS access
   * If denied accidentally, close and reopen the app
   * Or: Long press app icon → **App Info** → **Permissions**

**Required Permissions:**

Grant the following permissions (tap "Allow" for each):

* **📧 SMS** - Required to send and receive SMS messages
* **📞 Phone** - Required to access SIM card and phone number
* **📷 Camera** - Required for QR code authentication
* **🔔 Notifications** - Required for connection status alerts

**Additional Settings:**

1. When prompted: **"Remove permissions if app is unused"**
   * Toggle this **OFF** (we want the app always ready)
2. When prompted: **"Allow app to always run in background"**
   * Tap **"Allow"** or **"Always allow"**

{% hint style="warning" %}
**Critical**: If you skip any permissions, the app will not function properly. You can adjust permissions later in Android Settings → Apps → WhatSnap Gateway → Permissions.
{% endhint %}
{% endstep %}

{% step %}

#### Configure as Default SMS App (Optional)

When prompted: **"Make WhatSnap your default SMS app?"**

**Choose based on your needs:**

**Tap "No"** if:

* You only need SMS (text) messaging
* You want to keep your regular messaging app for personal use
* **Recommended for most users**

**Tap "Yes"** if:

* You need **MMS support** (picture messages, group messages)
* You want all messages to route through WhatSnap

{% hint style="info" %}
**Recommendation**: Most users should tap **"No"**. You can still send and receive SMS perfectly without making it the default app. Only set as default if you specifically need MMS support.
{% endhint %}
{% endstep %}

{% step %}

#### Authenticate with QR Code

1. In the WhatSnap Gateway app, select **"Sign in using QR code"**
   * ⚠️ **Do NOT** type your login credentials manually
   * Always use QR code authentication
2. The app will open your camera
3. Point your camera at the **QR code** displayed in your WhatSnap dashboard (on your computer)
4. The app will automatically scan and authenticate

**If QR code doesn't scan:**

* Ensure good lighting
* Hold camera steady
* Move phone closer or farther from screen
* Refresh the QR code in your WhatSnap dashboard if it expired
  {% endstep %}

{% step %}

#### Start the Gateway Service

1. After successful authentication, you'll see the main gateway screen
2. Tap the **red play button** (▶️) to start the gateway
3. A confirmation prompt appears: **"Start gateway service?"**
4. Tap **"Yes"** to confirm

**Status Indicators:**

* 🟢 **Green/Connected**: Gateway is running and connected
* 🔴 **Red/Stopped**: Gateway is not running
* 🟡 **Yellow/Connecting**: Gateway is attempting to connect

{% hint style="success" %}
**Gateway Started!** Your Android device is now connected to WhatSnap and ready to send/receive SMS through GoHighLevel.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Part 3: Configure WhatSnap Settings

Finalize your device settings in the WhatSnap dashboard.

{% stepper %}
{% step %}

#### Refresh WhatSnap Dashboard

1. Return to your **WhatSnap dashboard** in GoHighLevel (on your computer)
2. **Refresh** the page or devices list
3. Navigate to **Devices** → **Android Devices** (or similar)
4. You should see your newly connected device listed

**Device Information Shown:**

* Device model
* Phone number (from SIM card)
* Connection status
* Last active time
  {% endstep %}

{% step %}

#### Name Your Device

Give your device a descriptive name for easy identification:

1. Click on the device or its **settings menu** (⋮)
2. Find the **"Device Name"** or **"Nickname"** field
3. Enter a descriptive name, such as:
   * `Android-Main-SMS`
   * `Sales-Team-Device`
   * `DBR-Campaign-Device-1`
   * `Support-Line-Android`

**Why Name Your Device:**

* Easy identification in multi-device setups
* Clear organization in reports and logs
* Team members know which device handles which contacts
  {% endstep %}

{% step %}

#### Configure Dual-SIM Settings (If Applicable)

If your Android device has 2 SIM cards installed:

1. In device settings, you'll see both SIM cards listed
2. **Uncheck** any SIM card you do NOT want to use for WhatSnap
3. Keep checked only the SIM(s) you want for CRM messaging

{% hint style="info" %}
**Dual-SIM Strategy**: You can use both SIMs for WhatSnap to double your capacity, or reserve one for personal use. Learn more in [Multiple SMS Accounts](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/multiple-sms-accounts).
{% endhint %}
{% endstep %}

{% step %}

#### Save Device Configuration

1. After configuring device name and SIM selection
2. Click **"Save"** or **"Update"**
3. Confirm your changes are saved
   {% endstep %}

{% step %}

#### Assign Device to Sub-Account

If you manage multiple GoHighLevel sub-accounts:

1. In WhatSnap dashboard, go to **SIMs** or **Accounts** section
2. Find **"Assign to Sub-Account"** or **"Connected Locations"**
3. **Toggle ON** the sub-account(s) where you want to use this device
4. Click **"Confirm"** or **"Save"**

{% hint style="warning" %}
**Note**: Toggling a sub-account ON does not change or override anything in your GoHighLevel account. It simply makes the device available for that location.
{% endhint %}
{% endstep %}

{% step %}

#### Set Custom Provider in GoHighLevel (If Using Override)

If you chose **SMS Channel Override** in Part 1:

1. Log into the **connected sub-account** in GoHighLevel
2. Go to **Settings** → **Phone Numbers** (or **Business Profile** → **Phone Numbers**)
3. Scroll to **Additional Settings**
4. Under **"Custom Provider"**, change from:
   * "LeadConnector" or "Twilio"
   * **TO**: "WhatSnap SMS Gateway" or similar (exact name may vary)
5. Click **"Save"**

{% hint style="success" %}
**Integration Complete!** Your SMS workflows will now automatically use your Android device for messaging.
{% endhint %}
{% endstep %}

{% step %}

#### Note Your Account Tag

WhatSnap automatically creates a unique tag for your device:

1. In WhatSnap dashboard, find your device's **tag**
2. It will look like: `whatsnap-account-android-1` or `whatsnap-account-[your-device-name]`
3. **Write this down** - you'll use it to route messages to this device

**Tag Purpose:**

* Contacts with this tag will route messages to this specific Android device
* Use in workflows to target specific messaging channels
* Filter contacts by device/account
  {% endstep %}
  {% endstepper %}

***

## Part 4: Send Your First Test SMS

Verify your setup is working correctly by sending a test message.

{% stepper %}
{% step %}

#### Prepare a Test Contact

1. In **GoHighLevel**, open or create a **test contact**
2. Use your personal phone number or a colleague's number for testing
3. Ensure the contact has a valid mobile phone number
   {% endstep %}

{% step %}

#### Add the Device Tag

1. Open the contact's profile
2. Navigate to the **Tags** section
3. Add your device's tag (e.g., `whatsnap-account-android-1`)
4. Save the contact

{% hint style="info" %}
**Why Tag Contacts**: WhatSnap uses tags to determine which device/account should handle each contact's messages. Without the tag, messages won't route correctly.
{% endhint %}
{% endstep %}

{% step %}

#### Send a Test Message

1. Open the contact's **Conversations** tab in GoHighLevel
2. Click on **SMS** (if using override) or **WhatSnap** (if using custom channel)
3. Type a test message, such as:
   * "Hi! This is a test message from my WhatSnap SMS gateway. Please reply to confirm you received this."
4. Click **Send**
   {% endstep %}

{% step %}

#### Verify Delivery

**On Your Android Device:**

1. Open the **WhatSnap Gateway app**
2. Check the **message log** or **activity feed**
3. You should see the outgoing message listed

**On Recipient's Device:**

1. The recipient should receive your SMS
2. The message will come from **your Android device's phone number**
3. It will appear as a regular SMS (not from a short code or unknown number)

**In GoHighLevel:**

1. Message status should show as **"Delivered"** or **"Sent"**
2. Check message timestamp

{% hint style="success" %}
**Success!** If the recipient received your message, your setup is complete and working.
{% endhint %}
{% endstep %}

{% step %}

#### Test Receiving Messages

1. Have the recipient **reply** to your test message
2. The reply should appear in:
   * Your **Android device's WhatSnap Gateway app**
   * **GoHighLevel conversations** tab for that contact
   * Your Android phone's regular **Messages app** (if visible there)
3. All messages should stay in sync

**Bidirectional Sync Confirmed!**

* ✅ Outbound messages: GoHighLevel → WhatSnap → Android device → Recipient
* ✅ Inbound messages: Recipient → Android device → WhatSnap → GoHighLevel
  {% endstep %}
  {% endstepper %}

***

## Device Configuration Best Practices

### Power Management Settings

To ensure 24/7 operation, configure your Android device to prevent the gateway app from being killed:

{% tabs %}
{% tab title="Battery Optimization" %}
**Disable Battery Optimization for WhatSnap Gateway**

1. Open **Settings**
2. Go to **Apps** → **WhatSnap Gateway**
3. Tap **Battery** or **Battery usage**
4. Select **"Unrestricted"** or **"No restrictions"**

**Alternative path:**

1. Settings → **Battery** → **Battery optimization**
2. Tap dropdown: **"All apps"**
3. Find **WhatSnap Gateway**
4. Select **"Don't optimize"**

{% hint style="warning" %}
**Critical Setting**: If battery optimization is enabled, Android may kill the WhatSnap Gateway app after periods of inactivity, causing messages to fail.
{% endhint %}
{% endtab %}

{% tab title="Background Restrictions" %}
**Allow Background Activity**

1. Settings → **Apps** → **WhatSnap Gateway**
2. Tap **Mobile data & Wi-Fi** (or **Data usage**)
3. Toggle **ON**: "Background data"
4. Toggle **ON**: "Unrestricted data usage" (if available)

**App Background Restrictions:**

1. Settings → **Apps** → **WhatSnap Gateway**
2. Look for **"Background restrictions"** or **"Remove permissions if unused"**
3. Ensure these are **disabled/OFF**
   {% endtab %}

{% tab title="Auto-Start & Permissions" %}
**Enable Auto-Start (Varies by Manufacturer)**

**Samsung:**

1. Settings → **Apps** → **WhatSnap Gateway**
2. Tap **Battery** → **Optimize battery usage**
3. Set to **"Don't optimize"**

**Xiaomi/MIUI:**

1. Settings → **Apps** → **Manage apps** → **WhatSnap Gateway**
2. Enable **"Autostart"**
3. Set **Battery saver** to **"No restrictions"**

**Huawei/EMUI:**

1. Settings → **Apps** → **Apps** → **WhatSnap Gateway**
2. **Battery** → **App launch** → **Manage manually**
3. Enable: **Auto-launch**, **Secondary launch**, **Run in background**

**OnePlus/Oppo:**

1. Settings → **Battery** → **Battery optimization**
2. Find WhatSnap Gateway → **Don't optimize**

{% hint style="info" %}
**Manufacturer-Specific**: Different Android manufacturers have different settings. Search for "\[Your Phone Brand] keep app running in background" for specific instructions.
{% endhint %}
{% endtab %}

{% tab title="Keep Device Awake" %}
**Power & Sleep Settings**

1. Keep device **plugged into charger** 24/7
2. Settings → **Display** → **Screen timeout** → Set to shortest time (to save power)
3. Settings → **Battery** → Disable any **"Adaptive battery"** or **"Battery saver"** modes

**Developer Options (Optional - Advanced Users):**

1. Enable Developer Options: Settings → **About phone** → Tap **"Build number"** 7 times
2. Settings → **System** → **Developer options**
3. Find **"Stay awake"** → Toggle **ON** (keeps screen on while charging)

{% hint style="warning" %}
**Screen Burn-In**: If using "Stay awake", be aware of potential screen burn-in on OLED displays. Consider setting screen brightness very low or using a screen saver app.
{% endhint %}
{% endtab %}
{% endtabs %}

### Network Connection

**WiFi (Recommended):**

* More stable than mobile data
* No data usage charges
* Consistent connection quality
* Set your device to **never disconnect from WiFi** when sleeping

**Mobile Data (Backup):**

* Enable as fallback if WiFi drops
* Ensure adequate data allowance (app uses minimal data: \~50-100 MB/month)
* Check that SIM plan includes data

### App Update Settings

**Disable Automatic Updates:**

1. Open **Google Play Store**
2. Search for any WhatSnap-related apps (if applicable)
3. Tap the app → Tap **⋮** (three dots, top right)
4. Uncheck **"Enable auto-update"**

**Why**: Automatic updates can restart the app unexpectedly, causing message delays during business hours. Update manually during off-peak times.

***

## Multi-SIM Setup (Optional)

If you're setting up multiple Android devices or SIM cards:

**Quick Setup:**

1. Repeat Parts 1-4 for each additional device
2. Give each device a unique name
3. Each device gets its own unique tag
4. Use GHL workflows to distribute contacts across devices

**Full Instructions**: [Multiple SMS Accounts Guide](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/multiple-sms-accounts)

***

## Troubleshooting Installation Issues

### App Won't Install

<details>

<summary><strong>Play Protect Blocking Installation</strong></summary>

**Problem**: "App blocked by Play Protect" message appears.

**Solution**:

1. When you see the warning, tap **"More details"**
2. Tap **"Install anyway"**
3. If this doesn't work:
   * Open **Play Store** → **Profile** → **Play Protect** → **Settings**
   * Disable **"Scan apps with Play Protect"**
   * Retry installation

</details>

<details>

<summary><strong>Unknown Sources Not Allowed</strong></summary>

**Problem**: "Installation blocked - For your security, your phone is not allowed to install unknown apps from this source."

**Solution**:

1. Tap **"Settings"** in the error message
2. Toggle **ON**: "Allow from this source" (for your browser)
3. Return to the installer and try again

**Alternative**:

1. Settings → **Security** (or **Privacy**)
2. Find **"Install unknown apps"**
3. Select your **browser** (Chrome, Firefox, etc.)
4. Toggle **ON**: "Allow from this source"

</details>

<details>

<summary><strong>APK File Won't Download</strong></summary>

**Problem**: Browser blocks APK download or download fails.

**Solution**:

1. Use **Chrome browser** (most reliable for APK downloads)
2. Ensure stable internet connection
3. Clear browser cache: Chrome → Settings → Privacy → Clear browsing data
4. Retry download
5. If link expired, refresh your WhatSnap dashboard to get a new download link

</details>

### App Won't Connect

<details>

<summary><strong>QR Code Won't Scan</strong></summary>

**Problem**: Camera opens but QR code doesn't scan.

**Solution**:

1. Ensure good lighting (not too bright, not too dark)
2. Hold phone steady 6-12 inches from screen
3. Clean camera lens
4. Refresh QR code in WhatSnap dashboard (may have expired)
5. Try different screen (laptop vs. monitor)
6. Take screenshot of QR code, display it larger on screen

</details>

<details>

<summary><strong>Gateway Shows "Disconnected"</strong></summary>

**Problem**: Gateway app shows disconnected status after authentication.

**Solution**:

1. Check internet connection (WiFi or mobile data)
2. Restart the gateway service (stop and start again)
3. Check firewall settings (if using corporate WiFi)
4. Re-authenticate with fresh QR code
5. Restart the app completely
6. Restart your Android device

</details>

<details>

<summary><strong>Device Not Appearing in Dashboard</strong></summary>

**Problem**: Authenticated successfully but device doesn't show in WhatSnap dashboard.

**Solution**:

1. **Refresh** the WhatSnap dashboard page
2. Wait 30-60 seconds (may take time to sync)
3. Check you're viewing the correct sub-account
4. Check gateway app status (should show "Connected")
5. Log out and log back into WhatSnap dashboard
6. Contact support if device still doesn't appear after 5 minutes

</details>

### Permissions Issues

<details>

<summary><strong>SMS Permission Denied</strong></summary>

**Problem**: App can't access SMS.

**Solution**:

1. Open Settings → **Apps** → **WhatSnap Gateway**
2. Tap **Permissions**
3. Find **SMS** → Set to **"Allow"**
4. Restart the app

</details>

<details>

<summary><strong>App Keeps Requesting Permissions</strong></summary>

**Problem**: App repeatedly asks for the same permissions.

**Solution**:

1. Grant all permissions at once in Settings (not within app)
2. Settings → **Apps** → **WhatSnap Gateway** → **Permissions**
3. Set ALL to **"Allow"**: SMS, Phone, Camera, Notifications
4. Toggle **OFF**: "Remove permissions if app unused"
5. Restart device
6. Reopen app

</details>

### For additional troubleshooting, see: [**SMS Troubleshooting Guide**](https://github.com/WhatSnap/documentation/blob/main/Account-management/sms/troubleshooting-sms.md)

***

## Next Steps

After successful installation:

1. [**Warm up your SIM card**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/broken-reference) - Essential before sending volume
2. [**Configure RCS settings**](https://whatsnap.gitbook.io/whatsnap-docs/faq/sms/rcs-settings) - Optimize message delivery
3. [**Set up workflows**](https://whatsnap.gitbook.io/whatsnap-docs/conversations/workflow-automation) - Automate SMS messaging
4. [**Learn multi-SIM strategies**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/multiple-sms-accounts) - Scale your operations
5. [**Review best practices**](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/..#best-practices) - Maximize deliverability and avoid blocks

{% hint style="success" %}
**Installation Complete!** Your Android device is now connected and ready to send/receive SMS through GoHighLevel via WhatSnap.
{% endhint %}

***

**Need Help?** Contact WhatSnap support at <support@whatsnap.ai> or join our community for assistance.
