WhatsApp Template Reference
Complete internal reference for template submission, rejection reasons, media specifications, and per-user marketing limits. Use this during live support sessions and when triaging template-related tickets.
How Template Review Works
Every template submitted to Meta goes through automated review (typically minutes to a few hours). Meta checks content against its Business Policy, Commerce Policy, and category rules.
| Status | Meaning |
|---|---|
| Approved / Active | Passed review — can be sent |
| Rejected | Failed review — cannot be sent until fixed and resubmitted |
| Active - Low Quality | Live but receiving negative feedback; at risk of being paused |
| Paused | Temporarily blocked due to low quality signals |
| Disabled | Permanently blocked due to repeated violations |
Pausing escalation:
- 1st pause → blocked for 3 hours
- 2nd pause → blocked for 6 hours
- 3rd occurrence → Permanently Disabled
Section 1 — Why Templates Get Rejected
A. Policy Violations
| # | Reason | Detail |
|---|---|---|
| 1 | Promotional content in Utility template | Utility templates must contain only transactional/service info. No discounts, offers, or sales language. Auto-reclassified to Marketing since April 2025. |
| 2 | Sensitive information requested | Templates asking for passwords, PINs, card numbers, or national IDs are rejected to prevent phishing. |
| 3 | Threatening or aggressive language | Phrases like "Act now or lose access" or anything coercive are rejected. |
| 4 | Misleading claims | "Guaranteed results," "100% safe," or unsubstantiated promises get rejected. |
| 5 | Mentioning competitors | Naming other brands or comparing to competitors is not allowed. |
| 6 | Illegal or restricted products | Alcohol, tobacco, weapons, drugs, gambling, adult content, and other restricted categories are rejected. |
| 7 | Abusive content | Templates that threaten legal action, shame users, or contain harassing language are blocked. |
| 8 | Commerce Policy violation | Transaction messages that violate WhatsApp's Commerce Policy (e.g., prohibited product types). |
| 9 | Shortened URLs | Bit.ly or any link shortener hides the destination — rejected. All URLs must resolve to a verified business domain. |
| 10 | External domain links | CTA button URL domains must belong to the registered business. |
| 11 | WhatsApp link in CTA | CTA button URLs cannot contain a direct link to WhatsApp (wa.me). |
B. Formatting Errors
| # | Reason | Detail |
|---|---|---|
| 12 | Variable format is wrong | Only {{1}}, {{2}}, {{3}} etc. are valid. Any other format fails. |
| 13 | Variables at start or end of message | A message cannot begin with {{1}} or end with {{1}}. There must be surrounding text. |
| 14 | Non-sequential variables | Variables must go {{1}}, {{2}}, {{3}} — skipping numbers (e.g., {{1}}, {{3}}) is rejected. |
| 15 | Adjacent variables with no text between | {{1}} {{2}} directly next to each other is rejected. |
| 16 | Special characters inside variables | #, $, % inside variable placeholders causes rejection. |
| 17 | Missing variable sample | Every {{variable}} must have a real example submitted with the template. |
| 18 | Too many variables | Messages where most content is variables (very little fixed text) are treated as abuse risks. |
| 19 | Excessive caps or punctuation | ALL CAPS body text or !!! / ??? patterns are flagged as spam. |
| 20 | Template body too long | Body text limit is 1,024 characters. |
| 21 | Excessive newlines in body | More than two consecutive \n characters in the body. |
| 22 | Formatted/special header | Text headers cannot contain emojis, asterisks, \n, or other formatting markup. |
| 23 | Missing media sample for header | If you submit a media header (image/video/document), a sample file must be included. |
C. Category & Intent Issues
| # | Reason | Detail |
|---|---|---|
| 24 | Wrong category | Content does not match the selected category. Since April 2025, Meta auto-reclassifies rather than rejects — but this may increase costs. |
| 25 | Vague/unclear purpose | "We have news for you" has no clear purpose. Templates must state exactly what they are for. |
| 26 | Authentication template misuse | OTP/auth template category is strictly for login codes and verification only. |
| 27 | Language mismatch | Language selected at submission (e.g., Spanish) does not match the actual content language (e.g., English). |
D. Button Errors
| # | Reason | Detail |
|---|---|---|
| 28 | Button text too long | Maximum 25 characters per button label. |
| 29 | Button URL domain mismatch | URL in button must match your registered business domain. |
| 30 | Too many buttons | Maximum: 3 quick reply buttons OR 2 call-to-action buttons. |
| 31 | Missing button type | Each button must specify its type: quick_reply, url, or phone_number. |
E. Content Quality Issues
| # | Reason | Detail |
|---|---|---|
| 32 | Spelling or grammar errors | Typos make templates appear as spam or phishing attempts. |
| 33 | Duplicate template | Template body and footer identical to an already-existing template. |
| 34 | Low-quality or irrelevant media | Images must be at least 500×500 px. Media must be relevant to the message content. |
| 35 | Generic/spammy language | Phrases like "Limited time offer!", "Act now!", "Click here!" are spam signals. |
Template Category Rules (April 2025 Update)
Marketing templates are for:
- Promotions, offers, discounts
- Product announcements
- Re-engagement campaigns
- Anything with a commercial intent
Utility templates are for:
- Order confirmations, cancellations, fulfilment
- Delivery updates, COD confirmations
- Account updates, OTP/verification
- Any transactional message triggered by a user action
If promotional content is placed inside a Utility template, Meta no longer rejects it outright — it automatically reclassifies it as Marketing, which changes billing and delivery rules. Businesses found abusing this repeatedly lose their 24-hour grace period on further violations.
What to Do When a Template Is Rejected
- Check the rejection reason in WhatsApp Manager or the Business Support portal
- Fix the issue based on the tables above
- Resubmit as a new template or edit and resubmit
- You have 60 days to appeal or resubmit before the rejected template is archived
- If you believe the rejection is wrong, click "Request a Review" in Business Support Home
One common reason for rejection is exceeding Meta's template cap. Meta has a limit on the total number of templates a brand can create in FBM. Once reached, new submissions get auto-rejected even if the content is correct.
Fix: Ask the client to delete unused or old templates directly from Facebook Business Manager — not just from our dashboard. Then retry creating the new template.
Section 2 — Media Specifications
Images
| Property | Spec |
|---|---|
| Supported formats | JPEG, PNG |
| Max file size | 5 MB |
| Standard chat dimensions | Up to 1600 × 1052 px (auto-compressed) |
| HD image dimensions | Up to 4096 × 2692 px (less compression) |
| Carousel image dimensions | 1125 × 600 px — strict 1.91:1 ratio required |
| Product/catalog images | Min 500 × 500 px, optimal 1080 × 1080 px, 1:1 ratio |
| Min size (template headers) | 500 × 500 px |
WhatsApp auto-compresses standard images. For best quality, keep images under 1 MB. Sending as a Document preserves original resolution up to 2 GB but removes compression.
Videos
| Property | Spec |
|---|---|
| Supported formats | MP4, 3GP |
| Recommended | MP4 with H.264 video codec + AAC audio |
| Max file size (as video message) | 16 MB |
| Max file size (as document) | 2 GB |
| Auto-downscale | ~720p |
| Status/Story video | Max 90 seconds, 1080 × 1920 px, 9:16 ratio |
If a video needs to be higher quality or larger than 16 MB, send it as a Document file.
Audio
| Property | Spec |
|---|---|
| Supported formats | AAC, MP3, AMR, OGG, OPUS, M4A, WAV |
| Max file size (as audio message) | 16 MB |
| Max file size (as document) | 2 GB |
| Voice notes | Auto-encoded as OGG/OPUS by the app |
Play icon only shows if the file is ≤ 512 KB; larger files show a download button.
Documents
| Property | Spec |
|---|---|
| Supported formats | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT |
| Max file size | 100 MB |
Stickers
| Property | Spec |
|---|---|
| Format | WebP only |
| Dimensions | Exactly 512 × 512 px |
| Max file size (static) | 100 KB |
| Max file size (animated) | 500 KB |
| Max animation duration | 10 seconds |
Quick Reference
| Type | Formats | Max Size |
|---|---|---|
| Image | JPEG, PNG | 5 MB |
| Video | MP4, 3GP | 16 MB |
| Audio | AAC, MP3, AMR, OGG, OPUS | 16 MB |
| Document | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT | 100 MB |
| Sticker | WebP | 100 KB (500 KB animated) |
Section 3 — Per-User Marketing Template Limits
Meta enforces a per-user limit on how many marketing template messages a single WhatsApp user can receive from any business within a given time window. This is entirely controlled by Meta — BusinessOnBot or any BSP cannot override it.
How the Limit Works
| Scenario | What's Allowed |
|---|---|
| Initiating contact with a new user | 1 marketing template to start the conversation |
| Within 24-hour session window (after first message) | 1 additional template message |
| User replies to the message | 1 more template + unlimited free-form messages |
| User has received too many marketing messages from multiple brands | Message blocked — no delivery |
The limit resets after a time period that Meta determines individually per user, based on:
- How many marketing messages they've received from all businesses
- Their engagement rate (read rate, replies, clicks)
- User feedback signals (blocks, reports)
Every user has a different limit. A highly engaged user may have a higher threshold. A user who ignores marketing messages will be limited faster.
Error Codes
Error 131049 — "Healthy Ecosystem Engagement"
"This message was not delivered to maintain healthy ecosystem engagement."
What it means: The recipient has hit their per-user marketing message limit. Meta blocked the message to prevent over-messaging.
Causes:
- User already received multiple marketing templates from different businesses recently
- User shows low engagement (low read rates, has ignored previous messages)
- Template contains promotional content that Meta classifies as marketing-heavy
- User has negative feedback history (blocked or reported businesses)
What to do:
- Wait minimum 24 hours before retrying (Meta's official guidance)
- Do not retry immediately — repeated retries against a capped user waste credits and worsen account quality
- Tag these failures separately in reports — do not group with other error types
- Consider switching to a Utility template for softer re-engagement
Error 131026 — "Message Undeliverable"
What it means: The message could not be delivered at all.
Causes:
- Phone number is not a WhatsApp account
- Recipient has not accepted WhatsApp's updated Terms of Service
- Recipient is using a very outdated WhatsApp version
- Recipient has blocked your business number
- Frequency capping (broad policy enforcement)
What to do:
- Verify the recipient number is a valid WhatsApp account
- Remove the number from active campaign lists if it consistently fails
- Check if the template itself is triggering policy enforcement
Error 130472 — "Integration Experiment"
What it means: Meta runs ongoing experiments where ~1% of users cannot receive any marketing template unless a conversation already exists with that business.
What to do:
- This cannot be bypassed
- If the business has an existing relationship, ask the customer to initiate a conversation on WhatsApp first, then retry
Error 130429 — "Rate Limit Hit"
What it means: Your business account's own sending throughput limit has been exceeded (separate from per-user limits).
What to do:
- Slow down the send rate
- Space out campaign dispatches
Template Quality Score & Pausing
| Quality State | What It Means | Action |
|---|---|---|
| Active - High Quality | Good engagement, no issues | Continue sending |
| Active - Low Quality | Negative feedback detected | Review content, reduce frequency |
| Paused (1st time) | Blocked for ~3 hours | Wait, then review and reduce sends |
| Paused (2nd time) | Blocked for 6 hours | Review content urgently |
| Disabled | Permanently blocked | Recreate template; appeal via Business Support |
Quality is influenced by: user block rate, report rate, read rate, and engagement rate after receiving the message.
Best Practices to Avoid Marketing Message Failures
Do:
- Send campaigns only to users who opted in recently
- Use Segmentation to target engaged users
- Space out campaigns — avoid daily blasts to the same audience
- Use Utility templates for order/transactional messages
- Monitor delivery rates per campaign and per template
- Suppress users who consistently return 131049 errors
Avoid:
- Sending the same marketing campaign to the entire list repeatedly
- Using Marketing templates for clearly transactional messages
- Sending multiple marketing messages to the same user within hours
- Retrying immediately after a 131049 failure
Agent Troubleshooting Checklist
When a client reports marketing templates not delivering:
- Check the delivery report → identify the error code
- 131049 → inform client: per-user limit enforced by Meta, not a platform bug; wait 24 hours; do not retry immediately
- 131026 → verify the recipient's number is a valid WhatsApp account; check if the business is blocked
- 130472 → inform client: Meta experiment affecting ~1% of users; no override available
- Template Paused → check WhatsApp Manager quality score; reduce send frequency; wait for pause to lift
- Template Rejected → check rejection reason (Section 1 above); fix and resubmit