# What Happens If Messages Fail?

Sometimes SMS messages get stuck in **Pending** or **Queued** status instead of being delivered. This guide explains what these statuses mean, why messages get stuck, and how to clear or resend them.

{% hint style="info" %}
**Quick Summary**: Pending messages are waiting on WhatSnap's server, while Queued messages are already on your Android device waiting to send. Both can be managed from the WhatSnap dashboard.
{% endhint %}

## Understanding Message States

### Message Flow

{% @mermaid/diagram content="graph LR;
A\["📝 Message Created<br/>in GoHighLevel"] --> B\["📤 Sent to<br/>WhatSnap Server"];
B --> C\["⏳ PENDING<br/>on Server"];
C --> D\["📲 Sent to<br/>Android Device"];
D --> E\["⏳ QUEUED<br/>on Device"];
E --> F\["📨 Sending via<br/>Carrier"];
F --> G{"Delivery<br/>Success?"};
G -->|"✅ Yes"| H\["✅ DELIVERED"];
G -->|"❌ No"| I\["❌ FAILED"];

```
classDef created fill:#e3f2fd,stroke:#1976d2,stroke-width:2px;
classDef pending fill:#fff3e0,stroke:#e65100,stroke-width:2px;
classDef queued fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;
classDef success fill:#e8f5e8,stroke:#00695c,stroke-width:2px;
classDef failed fill:#ffebee,stroke:#c62828,stroke-width:2px;

class A,B created;
class C pending;
class D,E queued;
class F sending;
class H success;
class I failed;" %}
```

***

## Message Status Definitions

### ⏳ PENDING

**What it means**: Message has been received by WhatSnap's server but hasn't been sent to your Android device yet.

**Where it is**: On WhatSnap's cloud server (not on your phone)

**Normal duration**: Seconds to a few minutes

**When to worry**: If stuck for more than 5-10 minutes

**Visible in:**

* ✅ WhatSnap dashboard → Pending Messages
* ⚠️ GoHighLevel (shows as "Pending" but might actually be Queued)

{% hint style="info" %}
**Note**: GoHighLevel doesn't have a "Queued" status display, so messages that are actually queued on your device may still show as "Pending" in GHL.
{% endhint %}

***

### ⏳ QUEUED

**What it means**: Message has been successfully delivered from WhatSnap server to your Android phone, but hasn't been sent out to the recipient yet.

**Where it is**: On your Android device, in the WhatSnap Gateway app queue

**Normal duration**: Seconds to minutes (depends on queue length)

**When to worry**: If stuck for more than 10-15 minutes with good connection

**Why messages queue:**

* Other messages are ahead in line (app sends sequentially, one at a time)
* Device is processing previous messages
* Waiting for carrier to accept next message

**Visible in:**

* ✅ WhatSnap dashboard → Queued Messages
* ✅ WhatSnap Gateway app on Android (if it shows queue)
* ⚠️ GoHighLevel (shows as "Pending" - can't distinguish from actual pending)

{% hint style="success" %}
**Queued is Normal**: If you're sending multiple messages, newer messages will queue while older messages send. The app works sequentially to avoid overwhelming carriers.
{% endhint %}

***

### ❌ FAILED

**What it means**: Message couldn't be delivered and has stopped trying.

**Where it is**: Failed messages log in WhatSnap dashboard

**Why it failed**: See [Error Codes Guide](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/error-codes) for specific reasons

**What to do**: Investigate error code, fix issue, resend or delete message

***

### 🚫 MAX REACHED - DELETE ONLY

**What it means**: WhatSnap system has tried to send your message multiple times and was unsuccessful. No more automatic retry attempts will be made.

**Where it is**: WhatSnap dashboard, Pending Messages section

**Why this happens:**

* Message failed repeatedly (e.g., 5+ attempts)
* Same error occurred each time
* System has exhausted retry logic

**What to do:**

* ❌ Cannot resend from this state
* ✅ Delete the failed message
* ✅ Fix the underlying issue (check [Error Codes](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/error-codes))
* ✅ Send new message if still needed

***

## Why Messages Get Stuck

### Common Causes for PENDING Messages

| Cause                        | Explanation                              | Solution                                       |
| ---------------------------- | ---------------------------------------- | ---------------------------------------------- |
| **Gateway App Offline**      | Android device not connected to internet | Check device connection, restart app           |
| **Device Offline**           | Phone powered off or no network          | Power on device, connect to WiFi/data          |
| **WhatSnap Server Issues**   | Temporary server delay (rare)            | Wait 5-10 minutes, contact support if persists |
| **Integration Disconnected** | GoHighLevel token expired                | Reconnect WhatSnap integration                 |
| **Device Not Assigned**      | SIM not assigned to sub-account          | Assign device in WhatSnap dashboard            |

***

### Common Causes for QUEUED Messages

| Cause                          | Explanation                                  | Solution                                                                                                                                        |
| ------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **High Sending Rate**          | Sending too quickly, messages piling up      | Slow down sending, use drip mode                                                                                                                |
| **Sequential Processing**      | App sends one message at a time              | Wait - this is normal, queue will clear                                                                                                         |
| **Device Manufacturer Limits** | Phone restricts SMS frequency (30/30min)     | See [SMS Limit Bypass](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/sms-limit-bypass)                       |
| **SIM Card Blocks**            | Carrier has restricted or blocked your SIM   | Reduce volume, contact carrier, see [Error Codes](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/error-codes) |
| **MMS Configuration**          | Sending MMS without being default app        | Set WhatSnap as default messaging app                                                                                                           |
| **Insufficient Balance**       | Prepaid plan out of credit                   | Add funds to carrier account                                                                                                                    |
| **Connection Failures**        | App can't report back to server              | Check internet, restart app                                                                                                                     |
| **Old Device Issues**          | Older phones require manual approval per SMS | Use newer device (see [Specifications](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/sms-specifications))                    |
| **Oppo/Realme Confirmation**   | These phones prompt for each message         | Disable confirmation or use different brand                                                                                                     |

***

## How to Clear Pending Messages

### Accessing Pending Messages

{% stepper %}
{% step %}

#### Open WhatSnap Dashboard

1. Log in to **GoHighLevel**
2. Navigate to WhatSnap plugin
3. Click on **"Pending Messages"** or **"Messages"** section
4. You'll see list of messages with "Pending" status
   {% endstep %}

{% step %}

#### Review Each Message

For each pending message, you can see:

* Recipient phone number
* Message content
* How long it's been pending
* Status/error information
  {% endstep %}

{% step %}

#### Choose Action

You have two options for each pending message:

**Option 1: Process (Resend)**

* Attempts to push the message through again
* Useful if issue was temporary (device was offline, server hiccup)
* Click **"Process"** or **"Retry"**

**Option 2: Delete**

* Permanently removes message from queue
* Use if message is no longer needed or irrelevant
* Use if error is unfixable (invalid number, blocked contact)
* Click **"Delete"** or trash icon
  {% endstep %}
  {% endstepper %}

### Bulk Actions

**If you have many pending messages:**

1. Check if there's a **"Select All"** option
2. Choose bulk action:
   * **Process All**: Attempts to resend all pending messages
   * **Delete All**: Clears all pending messages
3. Confirm action

{% hint style="warning" %}
**Caution with Bulk Delete**: Ensure you actually want to discard all pending messages before using bulk delete. This action may not be reversible.
{% endhint %}

***

## How to Clear Queued Messages

### Accessing Queued Messages

{% stepper %}
{% step %}

#### Open WhatSnap Dashboard

1. Log in to GoHighLevel → WhatSnap plugin
2. Navigate to **"Queued Messages"** section
3. See messages that are on your Android device waiting to send
   {% endstep %}

{% step %}

#### Understand Queue Status

**Messages are Queued because:**

* ✅ They're on your phone, ready to send
* ✅ App is actively working to send them
* ✅ Each message sends sequentially (one at a time)
* ✅ New messages wait for older ones to finish

**This is normal operation** - the queue will clear automatically as messages send.
{% endstep %}

{% step %}

#### Choose Your Approach

**Option 1: Wait (Recommended)**

* Let the app continue sending
* Queue will clear on its own
* Typical speed: 1 message per minute (or faster if drip mode not active)
* Monitor progress in dashboard

**Option 2: Delete Queued Messages**

* **Permanently removes** messages from sending pipeline
* Use only if you don't want these messages sent
* Click **"Delete"** for specific messages
* Or use bulk delete if available

{% hint style="danger" %}
**Warning**: Deleting queued messages means they will NOT be sent. Only delete if you're certain you want to cancel these messages.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Preventing Messages from Getting Stuck

### Best Practices

#### 1. Use Drip Mode

**Problem**: Sending too fast causes queuing and potential carrier blocks.

**Solution**:

* Configure workflows to send 1 message per minute maximum
* Add "Wait" actions between messages
* Use GHL workflow delays and time restrictions

See: [Database Reactivations - Drip Configuration](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/broken-reference)

#### 2. Monitor Queue Length

**Problem**: Queue grows too large, causing delays.

**Solution**:

* Check WhatSnap dashboard regularly
* If queue exceeds 50-100 messages, slow down sending
* Consider adding more devices to distribute load

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

#### 3. Ensure Device Reliability

**Problem**: Device goes offline, stops processing queue.

**Solution**:

* Keep device plugged in 24/7
* Maintain stable internet connection
* Disable battery optimization for WhatSnap Gateway
* Check device daily

See: [SMS Installation - Device Configuration](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms-installation-setup#device-configuration-best-practices)

#### 4. Warm Up New SIMs

**Problem**: New SIM gets blocked, all messages fail.

**Solution**:

* Follow proper 2-week warm-up schedule
* Start with 10-20 messages/day only
* Gradually increase volume
* Monitor for carrier warnings

See: [SIM Warm-Up Process](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/broken-reference)

#### 5. Monitor for Errors

**Problem**: Same error repeats, messages keep failing.

**Solution**:

* Check error codes immediately
* Fix underlying issue before sending more
* Don't ignore "GENERIC\_FAILURE" errors

See: [Error Codes Guide](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/error-codes)

***

## Handling Specific Scenarios

### Large Queue After Campaign Launch

**Situation**: Launched campaign, now have 500 messages queued.

**What's happening:**

* All messages reached your device at once
* App is sending them one by one
* This will take time (500 msgs @ 1/min = 8+ hours)

**Options:**

**Option 1: Wait it Out**

* Let messages send naturally
* Monitor for delivery issues
* Ensure device stays online

**Option 2: Delete Some Messages**

* Keep first 100-200 messages
* Delete the rest
* Re-send later at slower pace

**Option 3: Distribute to Multiple Devices**

* If you have multiple SIM cards
* Pause campaign
* Distribute contacts across devices
* Resume campaign

### Messages Stuck for Hours

**Situation**: Messages have been pending/queued for 4+ hours with no movement.

**Diagnosis Steps:**

1. **Check Device**
   * Is phone online?
   * Is WhatSnap Gateway app running?
   * Is app showing "Connected"?
2. **Check SIM**
   * Can you send SMS directly from phone?
   * Is SIM active and has signal?
   * Has carrier blocked your SIM?
3. **Check Integration**
   * Is WhatSnap connected in GHL?
   * Try reconnecting integration
   * Check device is assigned to sub-account
4. **Check for Errors**
   * Any error messages in dashboard?
   * Look up error codes
   * Address specific errors

**Resolution:**

* If device issue → Restart app/device
* If SIM issue → Contact carrier or replace SIM
* If integration issue → Reconnect WhatSnap
* If persistent → Delete stuck messages and resend

### MMS Not Sending

**Situation**: Picture messages stuck in queue.

**Common Cause**: WhatSnap Gateway not set as default messaging app.

**Solution:**

1. On Android device:
   * Settings → Apps → Default apps → SMS app
   * Select **WhatSnap Gateway** as default
2. Restart WhatSnap Gateway app
3. MMS should now send

**Additional checks:**

* Ensure image is under 800 KB
* Check device signal strength (MMS needs stronger signal than SMS)
* Try connecting to WiFi and enable WiFi calling

***

## Queue Management Tools

### WhatSnap Dashboard Features

**Available Actions:**

* ✅ View pending message count
* ✅ View queued message count
* ✅ Process individual messages
* ✅ Delete individual messages
* ✅ Bulk process (if available)
* ✅ Bulk delete (if available)
* ✅ View error details
* ✅ Filter by status
* ✅ Filter by device

### Monitoring Queue Health

**Healthy Queue:**

* ⬇️ Messages move from Pending → Queued → Delivered within minutes
* ✅ Queue length stays manageable (under 50 messages)
* ✅ No error messages
* ✅ Delivery rate above 95%

**Unhealthy Queue:**

* ⚠️ Messages stuck for 30+ minutes
* ⚠️ Queue length growing (more incoming than sending)
* ⚠️ Multiple error messages
* ⚠️ Delivery rate below 90%

**Action for Unhealthy Queue:**

1. Stop sending new messages immediately
2. Diagnose root cause
3. Fix underlying issue
4. Clear stuck messages
5. Resume sending slowly

***

## Advanced Queue Management

### For High-Volume Operations

**If running large campaigns (1,000+ messages/day):**

**Strategy 1: Stagger Sending**

```
Campaign 1: Send 100 msgs
Wait: 2 hours (let queue clear)
Campaign 2: Send 100 msgs
Wait: 2 hours
Repeat...
```

**Strategy 2: Multi-Device Load Balancing**

* Distribute contacts across 3-5 devices
* Each device processes independently
* Total throughput multiplied by device count

**Strategy 3: Queue Length Triggers**

* Monitor queue length via API (if available)
* Pause sending if queue exceeds threshold (e.g., 50)
* Resume when queue drops below threshold (e.g., 20)

See: [Multiple SMS Accounts - Load Balancing](https://whatsnap.gitbook.io/whatsnap-docs/account-management/multiple-sms-accounts#load-balancing-and-volume-management)

***

## Troubleshooting Persistent Queue Issues

### Issue: Queue Never Clears

**Checklist:**

* [ ] WhatSnap Gateway app is running (not stopped)
* [ ] Device has internet connection (WiFi or mobile data)
* [ ] Device hasn't entered deep sleep mode
* [ ] SIM card is active and has signal
* [ ] No carrier blocks on SIM
* [ ] App has all required permissions
* [ ] Battery optimization is disabled
* [ ] Device isn't in power saving mode

**If all checked and queue still stuck:**

1. Restart WhatSnap Gateway app
2. Restart Android device completely
3. Delete queued messages and resend in smaller batches
4. Contact support: <support@whatsnap.ai>

### Issue: New Messages Immediately Queue

**Cause**: Messages are queuing faster than they can be sent.

**Solutions:**

1. **Slow down sending**:
   * Increase workflow delays
   * Use drip mode (1 msg per minute)
   * Pause campaigns temporarily
2. **Add capacity**:
   * Connect additional devices/SIM cards
   * Distribute contacts across devices
   * Scale horizontally
3. **Switch carriers**:
   * If current carrier is rate-limiting
   * Try carrier with higher limits
   * Consider Twilio for ultra-high volume

***

## Related Resources

* [Error Codes Guide](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/error-codes) - Understand specific failure reasons
* [Main Troubleshooting](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting) - General SMS troubleshooting
* [Database Reactivations](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/broken-reference) - Volume management best practices
* [Multiple SMS Accounts](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/multiple-sms-accounts) - Scale with multiple devices

***

**Questions about pending or queued messages?** Contact WhatSnap support at <support@whatsnap.ai> with details about stuck messages and error codes.
