FAQ & Troubleshooting

Frequently asked questions and solutions to common SMS Gateway operational issues.

Why are my messages marked as FAILED?

When a message is marked as FAILED, it means our backend successfully delivered the command to your Android device, the device attempted to send it, but the Carrier/Telecom Network rejected the dispatch.

Insufficient Balance: The SIM card in your Android device does not have enough SMS credits or airtime.
Invalid Number: The destination number to is improperly formatted or no longer exists.
Network Down: The Android device lost signal connectivity to the carrier towers at the exact moment of dispatch.
Carrier Block (SPAM): You have sent too many messages too quickly, and the carrier flagged your SIM.

How do I retry FAILED messages?

We do not auto-retry failed messages. This is a strict architectural decision to prevent your SIM from getting permanently blocked by telecom providers due to infinite retry loops (e.g., trying to send to a dead number 10 times in a row).

You must handle retries on your own server. We recommend listening to our message.failed Webhook, analyzing the failure reason, and orchestrating a retry through a different projectId or after a cooldown period.

Why are my messages permanently QUEUED?

A message remains QUEUED when the REST API accepts your payload, but the backend cannot find a reliable pathway to route it to an Android device.

Common Causes && Fixes

1
No Active DevicesOpen the Android app on your phone to keep the socket alive. If the phone is powered off or lacking internet, the backend will queue all pending messages until the hardware connects.
2
Wrong Project IDIf you supply an invalid or empty projectId in your POST JSON body, the message might become orphaned. Ensure the ID exactly matches the project where your device is registered.
3
Aggressive Dozing (Battery Saver)Certain Android skins (Xiaomi, Samsung) kill background sockets aggressively. Go to your phone's battery settings and mark the SMS Gateway app as "Unrestricted" or "Do Not Optimize".

App crashes with: java.lang.NullPointerException no SmsManager

If you or your clients are using cheaper or heavily modified Android devices (specifically some Oppo, Xiaomi, or generic Chinese phones & tablets without SIM configs), the Android OS might natively lack the necessary modern Telephony bindings, returning null when the App requests the SMS Module.

Why does it happen and how to fix it?

Operating systems like heavily customized ColorOS or MIUI sometimes forcefully block or fail to initialize the getSystemService(SmsManager.class) layer properly, leading to a crash when divideMessage() is invoked.

Resolution Available

This issue has been fully identified and patched. The upcoming v1.3.1 (and later) Android APK introduces a robust hardware-fallback mechanism. Instead of crashing, the App will explicitly invoke raw legacy hardware bridging, and if completely unavailable, will elegantly send a FAILED payload ("SMS Manager indisponível") directly to your Server Webhook instead of crashing the Mobile App!

Please monitor the software releases to download the next APK once published.

Hardware & Connectivity

Does my Android phone need to be connected to Wi-Fi?

No. The Android device can communicate with the backend using any active internet connection. Both Wi-Fi and 3G/4G/5G mobile data work perfectly to maintain the secure WebSocket tunnel.

Can I link multiple phones to a single Project?

Absolutely. The system acts as a distributed orchestrator. If you register 5 phones to the same projectId, the backend will instinctively load-balance your bulk SMS dispatches across all active phones.

Is it possible to receive SMS (Two-way communication)?

Currently, Paulina SMS Gateway is heavily optimized for outbound messaging (A2P). Inbound SMS interception is partially restricted by newer Android OS policies to protect user privacy, though implementing inbound triggers is on our strategic roadmap.

How can my backend know exactly when an SMS was Delivered?

Go to your Project Webhook settings and subscribe to the message.delivered and message.failed events. When your Android phone physically contacts the telecom carrier and the end-user receives the SMS, a secure POST request is fired to your server instantly.

Rate Limits & Performance

What is the dispatch throughput?

The NodeJS Socket backbone can comfortably process over 10,000 commands per second. However, your physical Android Device's modem will bottleneck the actual sending. A standard phone usually sends about 1 SMS per second. For high throughput, aggregate multiple phones into the same Project.

Is the content secure?

As an Open Source tool, if you host the stack on your own servers, you have full end-to-end sovereignty. The Android App establishes a secure WebSocket wss:// connection to your backend. Messages are never routed via third-party telecom API clouds (like Twilio).

Open a Support Ticket

Can't find an answer here? Open an engineering ticket and our support team will reach out directly to your inbox.