> For the complete documentation index, see [llms.txt](https://whatsnap.gitbook.io/whatsnap-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whatsnap.gitbook.io/whatsnap-docs/account-management/sms/troubleshooting/failed-messages.md).

# 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](/whatsnap-docs/account-management/sms/troubleshooting/error-codes.md) 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](/whatsnap-docs/account-management/sms/troubleshooting/error-codes.md))
* ✅ 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](/whatsnap-docs/account-management/sms/troubleshooting/sms-limit-bypass.md)                       |
| **SIM Card Blocks**            | Carrier has restricted or blocked your SIM   | Reduce volume, contact carrier, see [Error Codes](/whatsnap-docs/account-management/sms/troubleshooting/error-codes.md) |
| **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](/whatsnap-docs/account-management/sms/sms-specifications.md))                    |
| **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://github.com/WhatSnap/documentation/blob/main/Account-management/sms/database-reactivations.md)

#### 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](/whatsnap-docs/account-management/sms/multiple-sms-accounts.md)

#### 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](/whatsnap-docs/account-management/sms/sms-installation-setup.md#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://github.com/WhatSnap/documentation/blob/main/Account-management/sms/database-reactivations.md#sim-warm-up-process)

#### 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](/whatsnap-docs/account-management/sms/troubleshooting/error-codes.md)

***

## 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](/whatsnap-docs/account-management/sms/multiple-sms-accounts.md#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](/whatsnap-docs/account-management/sms/troubleshooting/error-codes.md) - Understand specific failure reasons
* [Main Troubleshooting](/whatsnap-docs/account-management/sms/troubleshooting.md) - General SMS troubleshooting
* [Database Reactivations](https://github.com/WhatSnap/documentation/blob/main/Account-management/sms/database-reactivations.md) - Volume management best practices
* [Multiple SMS Accounts](/whatsnap-docs/account-management/sms/multiple-sms-accounts.md) - Scale with multiple devices

***

**Messages stuck and can't figure out why?** Salvador can check your setup in real-time and get things flowing again → [Message Salvador now](https://wa.me/17543029801?text=Hey%20Salvador%2C%20my%20SMS%20messages%20are%20stuck%20in%20pending%2Fqueued)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/failed-messages.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.