01What is the message character limit?
Message character limits (often searched as the WhatsApp character limit) are the maximum lengths the WhatsApp Cloud API accepts for each text field of a non-template message — the kind a business sends inside an open 24-hour customer service window. The best known is the 4,096-character text.body of a Text Message, but every interactive field has its own cap: the body, header and footer of an Interactive Message, each reply-button title and ID, and the button label, section titles, row titles and row descriptions of a List Message.
The limits are enforced when you call the messages endpoint. A request with a field that is too long is rejected with an invalid-parameter error — typically code 100 or 131009, with error_data.details pointing at the offending value — and nothing reaches the customer. WhatsApp does not shorten the text to fit. That makes length a validation job for your code or your agents' composer, not something to discover in production when a product name merged into a button title runs past 20 characters.
These caps cover session (free-form) messages. Message templates are checked against their own component limits — header text 60, body 1,024, footer 60 and button text 25 characters — which live on Template Character Limits. Length is also separate from WhatsApp Text Formatting, but the two interact: the asterisks, underscores and tildes that make text bold, italic or struck through are characters in the string, so they count toward the limit too.
Key takeaways
- Message character limits are the longest values WhatsApp accepts for each field of a non-template message, from text bodies to button titles.
- A text message body holds up to 4,096 characters; an interactive message body up to 1,024, with 60 each for header and footer.
- Reply-button titles stop at 20 characters, list row titles at 24 and list row descriptions at 72.
- An over-long field fails the whole message with a parameter error — WhatsApp never trims it — so validate before you send.
- Template components have their own caps, such as 25 characters of button text, checked separately from session fields.
02The message character limit: key facts and limits
- Text message body
- 4,096 characters
- Interactive body
- 1,024 characters
- Interactive header / footer
- 60 characters each
- Reply-button title / ID
- 20 / 256 characters (max 3 buttons)
- List button label
- 20 characters
- List section / row title
- 24 characters each (10 rows in total)
- List row description
- 72 characters
- Over the limit
- Request rejected; nothing is delivered
03 · How it works, step by step
How does the message character limit work?
- Step 1
Find the field's cap
Text body 4,096; interactive body 1,024; header and footer 60; reply-button title 20 and ID 256; list button label 20; section title 24; row title 24; row description 72. A list holds 10 rows in total.
- Step 2
Count characters, not glyphs
Hindi, Tamil and other Indic scripts combine several code points into one visible letter, and many emoji are several code points long. Count code points in code, and keep headroom when a field is close to its cap.
- Step 3
Validate before you call the API
Check every field in your own code — especially values merged from a catalogue, CRM or translation file — and shorten, map or reroute them before the request is built.
- Step 4
Move to a roomier format
If choices will not fit in 20-character button titles, use a list message (24-character row titles plus 72-character descriptions), or put the detail in the body and keep the buttons to two or three words. Reply Buttons vs List Message compares the two formats.
- Step 5
Log the error if one slips through
Store the rejected payload with the error code and details, so the data source or template that produced the long value can be fixed rather than retried.
04The message character limit in code
// Field caps for non-template (session) messages on the Cloud API.const LIMITS = {"text.body": 4096,"interactive.header": 60,"interactive.body": 1024,"interactive.footer": 60,"button.title": 20,"button.id": 256,"list.button": 20,"section.title": 24,"row.title": 24,"row.description": 72,};const chars = (s) => [...(s ?? "")].length; // code points, not UTF-16 unitsexport function lengthProblems(msg) {const problems = [];const check = (field, value) => {if (value !== undefined && chars(value) > LIMITS[field]) {problems.push(field + ": " + chars(value) + " > " + LIMITS[field]);}};if (msg.type === "text") check("text.body", msg.text.body);if (msg.type === "interactive") {const i = msg.interactive;check("interactive.header", i.header?.text);check("interactive.body", i.body?.text);check("interactive.footer", i.footer?.text);for (const b of i.action.buttons ?? []) {check("button.title", b.reply.title);check("button.id", b.reply.id);}check("list.button", i.action.button);for (const s of i.action.sections ?? []) {check("section.title", s.title);for (const r of s.rows) {check("row.title", r.title);check("row.description", r.description);}}}return problems; // send only when this is empty}
Run it on every outbound payload; an empty array means every field fits.
05 · Common mistakes, and the fix
Common mistakes with the message character limit
Building titles from data
Product, city and customer names merged into button or row titles are the usual cause of over-length sends. Map them to short labels, or truncate deliberately, before the request is built.
Judging length by eye
A Devanagari word that looks five letters long can be eight or more characters to the API, and flag or skin-tone emoji are several. Count code points in code and leave headroom near a cap.
Expecting WhatsApp to truncate
It does not cut text to fit. One over-long field fails the entire message, so the customer sees nothing rather than a shortened version.
Reusing template copy in session buttons
Template button text allows 25 characters; an interactive reply-button title only 20. 'Reschedule appointment' (22) passes template review but fails as a reply-button title.
06Example: A pharmacy bot that went silent
A Chennai pharmacy chain's reorder bot offers three reply buttons built from medicine names. 'Paracetamol 650 mg strip' is 24 characters, so every send that included it was rejected and customers asking for that product got no reply at all. The team now caps button titles at 20 characters in code, maps long names to short labels ('Paracetamol 650') with the full name in the body, and moves any choice with more than three options into a list message, whose rows allow 24-character titles and 72-character descriptions — room for 'Paracetamol 650 mg strip' and a stock note.
07 · Tips from the bench
Best practices for the message character limit
- Keep one constants file of field limits and validate every outbound payload against it.
- Write button titles as two or three words and put the explanation in the body.
- Test copy in every language you send; translations change length.
- For answers longer than 4,096 characters, send a document or a link instead of several walls of text.
08Why does the message character limit matter?
Character caps bite in the least visible places: a bot that labels buttons with product names, a CRM field merged into a list row, a reply translated into Tamil or Malayalam that comes out longer than the English. Each of those fails the whole message, not just the long field, and the customer simply receives nothing. Knowing the caps lets developers validate before sending, lets content teams write copy that fits on the first try, and lets support leads trust that a canned response will actually go out.