📏 Limits & Quotas
This page lists every hard limit (set by WhatsApp) and soft limit (set by the module) you'll run into. Knowing them up front prevents surprises in production.
7.1 Hard Limits (Set by WhatsApp)
These are enforced by WhatsApp itself — the module cannot raise them.
| Limit | Value |
|---|---|
| Text message length | 4 096 characters |
| QR validity window | ~60 seconds |
| Linked devices per number | 4 (WhatsApp limit) |
| Delete-for-everyone window | ~2 days from sending (WhatsApp limit) |
📲 LINKED DEVICE BUDGET
WhatsApp allows one phone number to have up to 4 linked devices at the same time.
The WhatsApp QR Login connection uses 1 linked device. The remaining devices can be used for WhatsApp Web, the WhatsApp desktop app, or other linked devices.
If all 4 linked-device slots are already in use, WhatsApp will not allow you to add another device. You must first log out one of the existing linked devices.
7.2 Default Limits in This Module
These are tuned for safety. Most can be adjusted via configuration if your use case demands it.
| Limit | Allowed Extensions | Max Size |
|---|---|---|
| Image upload | .jpeg, .png, .jpg | 5 MB |
| Video upload | .mp4, .3gp | 16 MB |
| Audio upload | .mp3, .m4a, .amr | 16 MB |
| Document upload | .pdf, .doc, .docx, .txt, .xls, .xlsx, .ppt, .pptx | 100 MB |
| Sticker upload | .webp | 0.1 MB |
| Behaviour | Default |
|---|---|
| Single send timeout | 20 seconds before retry |
| Send retries | 4 attempts (with increasing delays) |
| Minimum gap between messages | 4 seconds |
| Chat list page size | 20 chats per page (auto-loads more) |
| Message history page size | 20 messages per page (auto-loads older) |
📂 MEDIA SIZES MIRROR WHATSAPP'S OWN
File type and size limits are checked on the server before the file is sent to WhatsApp.
If a file is too large or uses an unsupported file type, it will be rejected immediately. An error message will appear in the message box, and the file will not be sent.
7.3 Send Throttle
Message Sending Limit
The inbox waits at least 4 seconds between messages sent from the same WhatsApp connection.
This delay helps prevent messages from being sent too quickly and reduces the risk of triggering WhatsApp's anti-spam and message-quality systems.
🚫 DO NOT REMOVE THE SEND DELAY
Do not try to disable or bypass the 4-second delay.
WhatsApp applies its own sending and quality limits to each WhatsApp number. Sending too many messages too quickly can increase the risk of restrictions on the number.
If you need to send messages at a higher rate, use the WhatsApp Cloud API instead of removing the sending limit from QR Login.
7.4 Retry Behaviour
Failed Messages and Retries
If a message cannot be sent, the system automatically tries again up to 4 times. The system waits a little longer between each retry.
If all retry attempts fail, the message is marked as Failed and remains in the chat with a red error icon.
Hover over the red error icon to see the error reason from WhatsApp.
Common reasons a message may fail:
- The phone number is not registered with WhatsApp.
- The customer has blocked your WhatsApp number.
- The WhatsApp connection was lost while sending the message and did not reconnect in time.
- WhatsApp has temporarily restricted or slowed down message sending for the connected number.
For diagnosing limit-related errors, see Troubleshooting.