Appearance
WhatsApp API guidelines and limits
Use this guide when you are building messages, templates, broadcasts, or bot responses that are sent through WhatsApp.
- WhatsApp applies limits to buttons, lists, templates, media, and outbound sending
- The platform falls back to text options when a button layout is not supported
- Check these limits before creating long messages, large option lists, media templates, or high-volume broadcasts
How to read this page
If you are sending your first broadcast, start with the quick reference, then read Templates, Media, and Outbound sending limits.
If you are building bot messages, start with Options and buttons so you understand when users will see reply buttons, list messages, or labeled text fallback.
If you are troubleshooting delivery, start with Customer service window, Outbound sending limits, and Understand message statuses.
TIP
For a first marketing broadcast, the practical rule is simple: use an approved template, keep the message short, make media URLs public, remove opted-out users, and test with internal recipients before sending to customers.
Quick reference
| Area | Main rule |
|---|---|
| Reply buttons | 1-3 options, each 20 characters or less |
| List messages | Up to 10 rows when reply buttons do not fit |
| CTA URL button | Replaces interactive reply options when a CTA URL is present |
| Standard template body | Up to 1024 characters |
| Carousel cards | 2-10 cards, consistent structure across cards |
| Media | Files must be public when sent by URL |
Common examples
| Scenario | What customers will see |
|---|---|
| 3 short options | Reply buttons |
| 8 valid options | List message |
| 2 options where one is longer than 24 characters | Labeled text fallback |
| A CTA URL plus 2 short options | CTA URL button only |
Options and buttons
The platform decides how options should be displayed based on the number of options, option length, message length, and whether a CTA URL is set.
INFO
TL;DR: Use 1-3 short options for reply buttons. Use up to 10 short options for a list. If the options are too long or there are too many, the platform falls back to labeled text.
Reply buttons
- Reply buttons display when there are 1-3 options and each option is 20 characters or less
- Body text can be up to 1024 characters
- Reply buttons can be sent with a media header, such as an image, video, or document
- If a CTA URL is set, the platform sends a CTA URL button instead
List messages
List messages display when reply buttons do not fit and each option is 24 characters or less.
- In cases when there are:
- 4-10 options
- OR 1-3 options
- AND any option is longer than 20 characters
- Up to 10 rows across all sections
- Body text can be up to 1024 characters
List row limits
- The button that opens the list can be a maximum of 20 characters
- Section titles can be a maximum of 24 characters
- Row titles can be a maximum of 24 characters
CTA URL button
When a message has a CTA URL set, the platform sends a single tappable button that opens that URL.
- The CTA URL button replaces reply buttons or a list, even if the options would otherwise fit
- The button label uses the first option
- If no options are set, the button label is
Click here - Body text can be up to 1024 characters
- CTA URL buttons are supported on text and image messages
Labeled text fallback
When no interactive option format applies, the platform appends options to the message body as labeled text.
Example
text
A. Sales
B. Support
C. BillingThe platform falls back to labeled text when:
- There are more than 10 options
- Any option is longer than 24 characters
- The body text is longer than 1024 characters
Templates
Templates are required when you send proactive outbound messages outside the active customer service window.
INFO
TL;DR: You need an approved template before sending broadcasts or proactive messages. Keep the body under 1024 characters, use variables carefully, and avoid suspicious links or unclear wording.
Template content
- Template body text is limited to 1024 characters in standard template creation
- Text headers are limited to 60 characters
- Footers are limited to 60 characters
- Headers and footers should stay single-line
- Template variables such as
1should not contain newlines, tabs, or more than four consecutive spaces - Avoid placing variables at the very start or very end of the template body
Template buttons
- Template buttons can include Quick Reply buttons and Call To Action buttons
- Quick Reply buttons let the customer send a predefined reply
- Call To Action buttons can open a website or call a phone number
- A website CTA can use a static URL or a dynamic URL suffix, depending on how the approved template was created
- Button order follows the approved template layout
- If the button order needs to change, create and submit a new template
URLs
- Use clear, complete URLs
- Avoid URL shorteners such as
bit.ly - Make sure template URLs are valid and publicly reachable
Carousel templates
Carousel templates let you send one marketing template message with multiple swipeable media cards.
INFO
TL;DR: Use carousel templates for visual marketing choices. They need 2-10 cards, consistent card structure, and public media when sent.
When to use carousels
- Use carousels for product collections, promotions, listings, packages, or other visual choices
- Carousel templates are only available for Marketing templates
- Carousel templates must be created and approved before they can be sent
- Some Meta or provider interfaces may not expose carousel creation, so carousel setup may need to be done through the API
Carousel structure
- A carousel template includes one main message body and a set of carousel cards
- The main message body can be a maximum of 1024 characters
- A carousel must include at least 2 cards
- A carousel can include up to 10 cards
- Each card must use the same component structure
- Each card must have a media header, using either image or video
- Do not mix image cards and video cards in the same carousel
- Each card can have body text of up to 160 characters
- Each card must have at least 1 button
- Each card can have a maximum of 2 buttons
Carousel buttons
- Supported button types include Quick Reply, Visit Website, and Call Phone Number
- Button type, count, and order should be the same across all cards
- Website buttons can use static URLs or dynamic URL suffixes, depending on the approved template
- If the button layout needs to change, create and submit a new template
Carousel media
- Carousel cards support image or video headers
- Image cards support
.jpeg,.jpg, and.png - Video cards support
.mp4and.3gp - Images can be up to 5 MB
- Videos can be up to 16 MB
- Media used for sending must be publicly reachable when sent by URL
Carousel variables
- Variables can be used in the main message body
- Variables can be used in card body text
- Variables can be used in dynamic website URL suffixes
- Each variable must have a valid example value when the template is submitted for approval
- Keep variable values short enough to fit the card body or URL where they will appear
Media
Supported media must be publicly reachable when sent by URL.
INFO
TL;DR: Media URLs must be public and stable. Images can be up to 5 MB, videos up to 16 MB, and documents up to 100 MB.
| Media type | Supported formats | Maximum size |
|---|---|---|
| Image | .jpeg, .jpg, .png | 5 MB |
| Video | .mp4, .3gp | 16 MB |
| Document | .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt | 100 MB |
| Audio | .aac, .amr, .mp3, .m4a, .ogg with Opus codec | 16 MB |
Media notes
- Images should be 8-bit RGB or RGBA
- Videos should use H.264 video and AAC audio, with a single audio stream or no audio stream
- For documents, the displayed filename comes from the filename value
Customer service window
WhatsApp controls when you can send free-form messages and when you must use approved templates.
INFO
TL;DR: After a user messages you, you have 24 hours to reply freely. After that, use an approved template to restart the conversation.
- When a customer messages your business, WhatsApp opens a 24-hour customer service window
- During the customer service window, you can send free-form replies, including text, supported media, and supported interactive messages
- Outside the customer service window, outbound messages must use an approved template
- If the customer replies again, the customer service window starts again from that message
Outbound sending limits
Messaging limits control how many unique customers your business can message outside the customer service window in a rolling 24-hour period.
INFO
TL;DR: Meta controls outbound volume. Large broadcasts can fail if your account has low limits, poor quality, missing verification, or recent negative feedback.
- These limits are managed by Meta
- Limits depend on account status, business verification, sending quality, and user feedback
- Large broadcasts can fail if the WhatsApp Business Account or portfolio does not have enough messaging limit available
- Phone number quality can drop when users block, report, or negatively respond to messages
- Low quality can restrict sending volume or cause templates to be paused
You can review current sending limits and quality status in Meta Business Manager or WhatsApp Manager.