Media & Limits
WhatsApp media formats and size limits, what the API cannot do, and the Meta error codes you will meet, each with its fix.
These are the limits per attachment type on a WhatsApp send. Every attachment URL must be public with no authentication and return the file itself, not an HTML page (media uploads).
Media requirements
Images
| Property | Requirement |
|---|---|
| Formats | JPEG, PNG |
| Max file size | 5 MB |
Videos
| Property | Requirement |
|---|---|
| Formats | MP4, 3GPP |
| Max file size | 16 MB |
| Codec | H.264 video, AAC audio |
Documents
| Property | Requirement |
|---|---|
| Formats | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT |
| Max file size | 100 MB |
Audio
| Property | Requirement |
|---|---|
| Formats | MP3, OGG (Opus codec), AMR, AAC |
| Max file size | 16 MB |
A voice note is OGG with the Opus codec, mono, sent with voiceNote: true (WhatsApp inbox).
Analytics
WhatsApp exposes no post-level analytics through its API. Delivery status (sent, delivered, read) is tracked per message and per broadcast recipient, and arrives as the message.delivered and message.read events (inbox webhooks).
What you cannot do
WhatsApp's API does not allow:
- Free-form messages outside the 24-hour customer service window (send an approved template)
- Messages to numbers that are not on WhatsApp
- Personal WhatsApp accounts (a WhatsApp Business Account is required)
- More than 250 unique contacts per day on a new number (Meta's starting tier, raised with usage)
- Scheduling a single message (schedule a broadcast instead)
- Per-message analytics beyond delivery status
Common errors
| Error | Cause | Fix |
|---|---|---|
| "Template not found" (132001) | The template name or language code does not match | Use the exact name and language code the template was created with (en is not en_US) |
| "Invalid phone number" (131021) | The recipient number is malformed or not on WhatsApp | Use E.164 with the country code, for example +13105551234 |
| "Re-engagement required" (131026) | The 24-hour customer service window has closed | Send an approved template to reopen the conversation |
| "Rate limit hit" (131047) | Too many messages sent too quickly | Slow down and wait for the limit to reset |
| "Too many messages sent to this recipient" (131056) | More than about 10 messages a minute to one recipient | Pace sends per recipient; other recipients are unaffected |
| "Media download failed" (131052) | WhatsApp could not fetch the media URL | Serve the file from a public URL with no authentication |
| "Not in allowed list" (131030) | The number is not in Meta's test recipient list | Add it to your test recipients in Meta Business Suite |
| "Account locked" (131031) | Meta suspended the WhatsApp Business Account | Contact Meta support |
(#200) You do not have the necessary permission on every send | The number has a two-step PIN that the connect flow could not register (error 133005) | Register the number with its PIN |
A failed send returns the error on the call; a message that was accepted and then failed to deliver arrives as message.failed with the same Cloud API code in its error object. The envelope every error shares is in error handling.
Related
- WhatsApp inbox: what each attachment type looks like when sent.
- Media uploads: host files on Zernio instead of your own URL.
- Templates: the fix for 131026 and 132001.
- WhatsApp phone numbers: the liveness check and the PIN registration.
- Pricing & costs: who bills what.
Pricing & Costs
Which WhatsApp charges Zernio bills, which ones Meta bills to your WhatsApp Business Account, and how the sandbox, a dedicated number and your own number differ.
Telegram
Publish text, photos, videos, documents and albums to Telegram channels and groups with the Zernio API, edit published messages, and run DMs and bot commands from the inbox.