# SMS Troubleshooting

This guide covers fundamental troubleshooting steps for resolving SMS sending and receiving issues with WhatSnap on Android devices.

{% hint style="info" %}
**Start Here First**: Before exploring specific troubleshooting topics, run through these basic checks to resolve most common issues quickly.
{% endhint %}

## Quick Diagnostic Steps

If you're experiencing issues with SMS not sending or receiving, follow these steps in order:

### Step 1: Test SIM Card Directly

**Verify your SIM can send SMS outside of WhatSnap:**

1. Open the native **Messages** app on your Android device
2. Send a test SMS to your personal number or a colleague
3. Ask them to reply to verify two-way communication works

**If this fails:**

* ❌ **Problem is with your SIM card or carrier**, not WhatSnap
* Contact your carrier/service provider first
* Verify account has credit/balance (for prepaid plans)
* Check if SIM plan includes SMS capability
* Ensure SIM is not blocked or restricted

**If this works:**

* ✅ SIM card is functional, continue to Step 2

***

### Step 2: Verify Installation is Correct

Confirm that WhatSnap SMS is properly installed and configured:

#### ✅ Check WhatSnap Integration in GoHighLevel

1. Log in to your **GoHighLevel sub-account**
2. Go to **Settings** → **Integrations** or **Phone Numbers**
3. Verify **WhatSnap** appears in your integrations list
4. Check custom provider is set to **"WhatSnap SMS Gateway"** or similar

**If missing:**

* Reconnect WhatSnap integration (see [Step 7](#step-7-reconnect-whatsnap-integration))

#### ✅ Check WhatSnap Gateway App on Android

1. Open your **Android device**
2. Find the **WhatSnap Gateway** app
3. Verify app is **installed** and **visible**

**If app won't install:**

* Ensure **Google Play Protect is disabled**
  * Play Store → Profile → Play Protect → Settings → Disable scanning
* Allow installation from unknown sources
  * Settings → Security → Install unknown apps → Enable for Chrome/browser

See: [SMS Installation Guide](/whatsnap-docs/account-management/sms/sms-installation-setup.md)

#### ✅ Verify App is Running

1. Open **WhatSnap Gateway** app
2. Check status indicator shows **"Connected"** or **"Running"** (green)
3. Gateway service should be **started** (not stopped)

**If stopped:**

* Tap the **play button (▶️)** to start the gateway
* Wait 30 seconds for connection to establish

#### ✅ Check App Can Run in Background

1. Long press the **WhatSnap Gateway** app icon
2. Tap **"App info"** or **"Info"**
3. Go to **Battery** settings
4. Ensure it's set to **"Unrestricted"** (not "Optimized" or "Restricted")

**To fix:**

* Settings → Apps → WhatSnap Gateway → Battery → Select **"Unrestricted"**

See detailed instructions: [Device Configuration](/whatsnap-docs/account-management/sms/sms-installation-setup.md#device-configuration-best-practices)

***

### Step 3: Verify Device Registration

#### ✅ Device Added to WhatSnap Dashboard

1. Log in to **WhatSnap dashboard** in GoHighLevel
2. Navigate to **Connected Accounts** or **Devices**
3. Verify your Android device appears in the list
4. Check connection status shows **"Online"** or **"Connected"**

**If device is missing:**

* Re-authenticate device with new QR code
* Follow [installation steps](/whatsnap-docs/account-management/sms/sms-installation-setup.md#part-2-setting-up-your-android-device)

**If device shows "Offline":**

* Check internet connection on Android device
* Restart WhatSnap Gateway app
* Re-authenticate if needed

#### ✅ SIM Connected to Sub-Account

1. In WhatSnap dashboard, go to **SIMs** or **Account Assignment**
2. Verify your device is assigned to the correct **GoHighLevel sub-account**
3. Toggle should be **ON** for the sub-account you're using

**If not assigned:**

* Click **"Connect Location"** or **"Assign"**
* Select the appropriate sub-account
* Save changes

***

### Step 4: Verify Device Specifications

Confirm your device meets minimum requirements:

* [ ] **Android version**: 9.0 or higher
* [ ] **RAM**: 2 GB minimum (4 GB recommended)
* [ ] **SIM card**: Active and tested
* [ ] **Internet**: WiFi or mobile data working
* [ ] **Phone model**: Not on the "avoid" list

**Check your device:**

* Settings → **About phone** → Check Android version and RAM

**If device doesn't meet specs:**

* Consider upgrading to a [recommended device](/whatsnap-docs/account-management/sms/sms-specifications.md#recommended-devices)

See: [SMS Device Specifications](/whatsnap-docs/account-management/sms/sms-specifications.md)

***

### Step 5: Check Phone Software Updates

**Ensure device software is current:**

1. Go to Settings → **System** → **System update** (or **Software update**)
2. Check for available updates
3. Install any pending updates (during off-hours to avoid disruption)

**Note**: Keep device updated for security and compatibility, but disable auto-updates to prevent unexpected restarts.

***

### Step 6: Verify RCS is Disabled

RCS (Rich Communication Services) can interfere with SMS delivery in most setups.

1. Open **Messages** app
2. Go to Settings → **RCS chats** or **Chat features**
3. Verify RCS is **disabled** (turned OFF)

**Exception**: Enable RCS only if using eSIM from another country over WiFi

See: [RCS Settings Guide](/whatsnap-docs/faq/sms/rcs-settings.md)

***

### Step 7: Reconnect WhatSnap Integration

If messages still aren't sending/receiving, the GoHighLevel connection token may have expired.

#### Reconnect at Agency Level

{% stepper %}
{% step %}

#### Access Integrations

1. Log in to **GoHighLevel** (app.gohighlevel.com)
2. Navigate to **Settings** → **Integrations**
3. Find **WhatSnap** in your integrations list
   {% endstep %}

{% step %}

#### Reconnect Integration

1. Click the **WhatSnap integration** (or integration button)
2. Should show **"Already Connected with Agency"** or similar
3. Click **"Reconnect"** or **"Connect"**
4. Select your **Agency**
5. Enable both checkboxes:
   * ✅ Install for all locations
   * ✅ Auto-install for new locations
6. Click **"Install"** or **"Proceed"**

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

{% step %}

#### Reconnect Sub-Accounts

1. In WhatSnap dashboard, go to **Sub-Account SIMs** or **Connected Locations**
2. Click **"Connect Location"**
3. You can toggle one account **off and on** to reconnect all
   * Or reconnect each individually
     {% endstep %}

{% step %}

#### Verify Reconnection

1. Refresh your GoHighLevel page
2. WhatSnap integration should show as **active/connected**
3. Send a test message to verify
   {% endstep %}
   {% endstepper %}

***

### Step 8: Test Message Sending

After completing the above steps, test your setup:

1. Open a **contact** in GoHighLevel
2. Ensure contact has your **device tag** (e.g., `whatsnap-account-android-1`)
3. Navigate to **Conversations** → **SMS**
4. Send a simple test message
5. Check delivery on recipient's device
6. Ask recipient to **reply** and verify sync to GHL

**If messages still fail:**

* Proceed to specific troubleshooting guides below
* Check [Error Codes](/whatsnap-docs/account-management/sms/troubleshooting/error-codes.md) for specific error messages
* Contact support with error details

***

## Specific Troubleshooting Topics

Once you've completed the basic steps above, explore these specific troubleshooting guides:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>📋 Error Codes</strong></td><td>Decode error messages and understand failure reasons</td><td><a href="/pages/gkUXidSAL06CFDWuW4wI">/pages/gkUXidSAL06CFDWuW4wI</a></td></tr><tr><td><strong>🖥️ Remote Access</strong></td><td>Troubleshoot client devices remotely with Zoho Assist</td><td><a href="/pages/QeFSuTcHVyIoYfG4u7Tj">/pages/QeFSuTcHVyIoYfG4u7Tj</a></td></tr><tr><td><strong>📊 SMS Limit Bypass</strong></td><td>Remove Android's 30 messages/30 minutes restriction</td><td><a href="/pages/0QSzpIyGgalrcelGup94">/pages/0QSzpIyGgalrcelGup94</a></td></tr><tr><td><strong>⏳ Failed Messages</strong></td><td>Handle pending and queued messages</td><td><a href="/pages/ozVI72WfG5CRhPb8pFOG">/pages/ozVI72WfG5CRhPb8pFOG</a></td></tr><tr><td><strong>🗑️ Uninstall Integration</strong></td><td>Remove WhatSnap from GoHighLevel agency</td><td><a href="/pages/yqIFi67SNU7927TH2RBY">/pages/yqIFi67SNU7927TH2RBY</a></td></tr></tbody></table>

***

## Common Issues Quick Reference

### Messages Not Sending

**Most Common Causes:**

1. ⚠️ Gateway app not running → [Restart app](#step-2-verify-installation-is-correct)
2. ⚠️ Contact missing device tag → Add tag in GHL
3. ⚠️ Device offline → Check internet connection
4. ⚠️ SIM card issue → Test direct from phone
5. ⚠️ Battery optimization killing app → Set to unrestricted

**Solutions**: See [Main Troubleshooting Guide](https://github.com/WhatSnap/documentation/blob/main/Account-management/troubleshooting-sms.md#messages-not-sending)

### Messages Not Receiving

**Most Common Causes:**

1. ⚠️ Gateway app disconnected → Reconnect in dashboard
2. ⚠️ Network blocking → Try mobile data instead of WiFi
3. ⚠️ Firewall restrictions → Whitelist WhatSnap domains
4. ⚠️ App permissions revoked → Re-grant permissions

**Solutions**: See [Main Troubleshooting Guide](https://github.com/WhatSnap/documentation/blob/main/Account-management/troubleshooting-sms.md#messages-not-receiving)

### SIM Card Blocked

**Most Common Causes:**

1. ⚠️ Sent too many messages too quickly
2. ⚠️ Spam content detected by carrier
3. ⚠️ Didn't warm up new SIM card properly
4. ⚠️ Exceeded carrier fair use policy

**Solutions**:

* Stop messaging immediately for 24-48 hours
* Contact carrier to request unblock
* Review [SIM Warm-Up Process](broken://pages/1NpMBh9RXUeVt9ElFXvj#sim-warm-up-process)
* See [Avoiding Carrier Blocks](broken://pages/1NpMBh9RXUeVt9ElFXvj#avoiding-carrier-blocks)

### App Keeps Stopping

**Most Common Causes:**

1. ⚠️ Battery optimization enabled
2. ⚠️ Low device memory
3. ⚠️ Manufacturer restrictions (Xiaomi, Huawei, etc.)
4. ⚠️ App conflicts

**Solutions**: See [Main Troubleshooting Guide](https://github.com/WhatSnap/documentation/blob/main/Account-management/troubleshooting-sms.md#device-and-app-issues)

### MMS Not Sending

**Quick Checks:**

* [ ] Image is under 800 KB
* [ ] Can send MMS directly from phone (test natively)
* [ ] Signal strength is adequate (3-4 bars)
* [ ] WiFi calling enabled (if on WiFi)
* [ ] WhatSnap Gateway set as **default SMS app** (required for MMS)

**Note**: MMS requires the WhatSnap Gateway app to be set as the default messaging app on Android.

**If MMS still won't send:**

1. Check signal strength - MMS needs stronger signal than SMS
2. Try connecting to WiFi and enable WiFi calling
3. Reduce image size (compress to under 500 KB for best results)
4. Test sending MMS directly from phone first

***

## Device-Specific Issues

### Samsung Devices

**Common issues:**

* Aggressive battery optimization
* Samsung's "Sleeping apps" feature

**Solutions:**

1. Settings → Battery → **Background usage limits**
2. Remove WhatSnap Gateway from "Sleeping apps" list
3. Settings → Apps → WhatSnap → Battery → **Unrestricted**

### Xiaomi / MIUI Devices

**Common issues:**

* Very aggressive app killing
* Autostart restrictions

**Solutions:**

1. Settings → Apps → Manage apps → WhatSnap Gateway → **Enable Autostart**
2. Security → Permissions → Autostart → Enable for WhatSnap
3. Battery saver → **No restrictions**

### Huawei / EMUI Devices

**Common issues:**

* Protected apps system
* Aggressive battery management

**Solutions:**

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

### OnePlus / OxygenOS

**Common issues:**

* Battery optimization
* App "Deep Optimization"

**Solutions:**

1. Settings → Battery → Battery optimization → WhatSnap → **Don't optimize**
2. Disable "Deep Optimization" for WhatSnap in battery settings

***

## Still Having Issues?

If you've followed all the steps above and are still experiencing problems:

### 1. Check Error Codes

Review the specific error message you're receiving:

* [Error Codes Guide](/whatsnap-docs/account-management/sms/troubleshooting/error-codes.md) - Decode GENERIC\_FAILURE and other error codes

### 2. Review Main Troubleshooting Guide

For comprehensive troubleshooting covering all scenarios:

* [Complete SMS Troubleshooting](https://github.com/WhatSnap/documentation/blob/main/Account-management/troubleshooting-sms.md)

### 3. Contact Support

**Before contacting support, gather:**

* [ ] Device model and Android version
* [ ] Carrier/SIM plan provider
* [ ] Error codes or messages (screenshots)
* [ ] What troubleshooting steps you've already tried
* [ ] When the issue started

**Contact:**

* Email: <support@whatsnap.ai>
* Subject: "SMS Troubleshooting - \[Brief Description]"
* Include all information from checklist above

***

## Preventive Maintenance

Avoid issues before they occur:

### Daily Quick Check (30 seconds)

* [ ] Device is online and connected
* [ ] WhatSnap Gateway app shows "Connected"
* [ ] No error messages or warnings
* [ ] Test message sends successfully

### Weekly Maintenance (5 minutes)

* [ ] Review delivery rates (should be >95%)
* [ ] Clear old messages from native Messages app
* [ ] Verify battery optimization still disabled
* [ ] Check carrier usage (stay within fair use limits)
* [ ] Restart device (optional but recommended)

### Monthly Review (15 minutes)

* [ ] Full device restart
* [ ] Update WhatSnap Gateway app (if available)
* [ ] Review message performance metrics
* [ ] Test backup devices (if applicable)
* [ ] Verify all permissions still granted

{% hint style="success" %}
**Prevention is Better Than Cure**: Spending a few minutes weekly on maintenance prevents hours of troubleshooting later.
{% endhint %}

***

**Related Guides:**

* [SMS Installation & Setup](/whatsnap-docs/account-management/sms/sms-installation-setup.md)
* [SMS Device Specifications](/whatsnap-docs/account-management/sms/sms-specifications.md)
* [Database Reactivations - Avoiding Blocks](broken://pages/1NpMBh9RXUeVt9ElFXvj)
* [RCS Settings](/whatsnap-docs/faq/sms/rcs-settings.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.