01 · Definition
What is the template character limit?
Template character limits are the length caps Meta applies to each component of a WhatsApp message template when you create or edit it. The body, the only required component, can hold up to 1,024 characters. A text header and the footer are capped at 60 characters each, every button label at 25, and the template name itself at 512 characters of lowercase letters, digits and underscores.
Buttons carry limits beyond their label. A URL button's address can be up to 2,000 characters with one variable, which must sit at the end; a phone-number button's number up to 20 characters; and a copy-code button's example code up to 20. A template can carry up to 10 buttons in total. Breaking any of these caps stops the template at creation — the API refuses it with error 2388040, which names the field — so the problem surfaces before review rather than at send time.
These caps are separate from the ones for free-form session messages. A plain text message can run to 4,096 characters and a non-template reply-button title only 20, so copy written for a chatbot reply rarely fits a template unchanged, and the reverse is true for button labels. Authentication templates are the exception to all of this: Meta supplies their body text, so there is nothing to write beyond optional extras such as the expiry note.
Key takeaways
- Template character limits cap each WhatsApp template field separately: body 1,024, text header 60, footer 60 and each button label 25 characters.
- URL buttons allow 2,000 characters with one variable at the end; phone-number buttons 20, copy-code examples 20 and template names 512.
- An over-length field is refused at creation with error 2388040, which names the field, before the template ever reaches review.
- Template caps differ from session caps: a free-form text message allows 4,096 characters, a template body only 1,024.
- Short templates still fail when they hold too many variables for their length (2388293) or start or end with one (2388299).
02 · Specifications
The template character limit: key facts and limits
| Body | 1,024 characters, multiple variables |
|---|---|
| Text header | 60 characters, 1 variable |
| Footer | 60 characters, no variables |
| Button label | 25 characters; up to 10 buttons |
| URL button | 2,000 characters, 1 variable at the end |
| Phone button number | 20 characters |
| Copy-code example | 20 characters |
| Template name | 512 characters: a–z, 0–9 and _ |
03 · Operation
How does the template character limit work?
Draft each component against its own cap
Write the body (1,024), header (60), footer (60) and every button label (25) separately. The caps apply per component; they are not a shared budget for the whole template.
Leave room for variables
A variable such as
{{1}}is replaced at send time, so the customer sees the value, not the placeholder. Size copy around realistic values — a 40-character product name in a 60-character header leaves almost no margin — because header parameter values are length-limited too.Keep enough fixed text around variables
Meta refuses templates with too many variables for their length (error 2388293) and variables at the very start or end (error 2388299). A short body stuffed with placeholders fails even when it is far below 1,024 characters.
Validate before you submit
Check every field in your build pipeline or template tool, counting code points rather than UTF-16 units. If the API still refuses the template, the message attached to error 2388040 tells you which field is too long.
Move overflow to where it fits
When copy will not fit, move detail behind a URL button, into a document header, or into the conversation that follows once the customer replies — not into a longer body.
04 · Code samples
The template character limit in code
// Length check for a template create payload, run before calling the API.const LIMITS = { HEADER: 60, BODY: 1024, FOOTER: 60, BUTTON_TEXT: 25, URL: 2000, PHONE: 20, NAME: 512 };const count = (s = "") => [...s].length; // code points, not UTF-16 unitsexport function checkLengths(template) {const problems = [];if (count(template.name) > LIMITS.NAME) problems.push("name");for (const c of template.components ?? []) {if (c.type === "HEADER" && c.format === "TEXT" && count(c.text) > LIMITS.HEADER) problems.push("header");if (c.type === "BODY" && count(c.text) > LIMITS.BODY) problems.push("body");if (c.type === "FOOTER" && count(c.text) > LIMITS.FOOTER) problems.push("footer");if (c.type === "BUTTONS") {c.buttons.forEach((b, i) => {if (count(b.text) > LIMITS.BUTTON_TEXT) problems.push(`buttons[${i}].text`);if (b.type === "URL" && count(b.url) > LIMITS.URL) problems.push(`buttons[${i}].url`);if (b.type === "PHONE_NUMBER" && count(b.phone_number) > LIMITS.PHONE) problems.push(`buttons[${i}].phone_number`);});}}return problems; // [] means every field fits}
Catches the common length failures before submission. Meta still has the final word, so read error 2388040's message if a template is refused.
05Playground
A working model of Template Character Limits. Use its controls to replay it step by step.
Type into each field and watch its limit
Over by 2. Text past 60 characters is rejected or cut off.
Won’t fit: ed
One variable allowed. Leave room for the value that will replace it at send time.
Fits, with 699 characters to spare.
Required. Multiple variables, but not at the very start or end, and with enough fixed text around them.
Fits, with 13 characters to spare.
Plain, fixed text. Footers take no variables.
Close to the limit: only 1 left. Keep headroom if part of this text is filled in at send time.
Applies to every button type. A template can carry up to 10 buttons.
Fits, with 488 characters to spare.
Lowercase letters, digits and underscores only.
Counted in Unicode code points, so an emoji, ₹ or an accented letter counts as one character.
06 · Cautions
Common mistakes with the template character limit
Counting with string length
JavaScript's
lengthcounts UTF-16 code units, so a single emoji can count as two in your own validator. Count code points ([...text].length) and confirm borderline copy in WhatsApp Manager before relying on it.Reusing session-message copy
Chatbot replies can run to 4,096 characters while template bodies stop at 1,024; session reply-button titles allow 20 characters while template button labels allow 25. Copy moved between the two needs re-checking in both directions.
Filling the body to the last character
A body at 1,020 characters leaves no room for a later fix, and trimming fixed text to make space can trip the too-many-variables rule. Aim comfortably below the cap.
Expecting the footer to carry detail
The footer holds 60 characters of fixed text with no variables. Order specifics and legal detail belong in the body or behind a link button.
07 · Worked example: A dispatch template that failed on length, then passed
Example: A dispatch template that failed on length, then passed
A Surat saree retailer drafts an order-dispatch utility template. The first version puts the full product name in the header — “Your Banarasi silk saree, maroon with zari border, has shipped”, 62 characters — adds a 1,100-character body with care instructions, and labels the button “Track your parcel on our website”. The API refuses it before review. The second version uses a short header with one variable (“Order {{1}} has shipped”), trims the body to about 420 characters by moving care instructions behind a “Care guide” URL button, and shortens the tracking label to “Track parcel”. It clears every length check and goes on to review.
08 · Recommended practice
Best practices for the template character limit
- Keep a one-line cheat sheet next to your drafts: header 60, body 1,024, footer 60, button 25, URL 2,000, phone 20, name 512.
- Write button labels as two- or three-word verbs — “Track order”, “Pay now”, “Reschedule”.
- Test with the longest realistic variable value, not the friendly sample you submitted for review.
- Read the field named in error 2388040 instead of guessing which part of the template is too long.
09 · Rationale
Why does the template character limit matter?
Length is the first gate a template has to pass. A body 30 characters too long, a button labelled “Track your shipment status” (26 characters, one over), or a header crowded with a product name gets refused before anyone reviews it — and on launch day that means rewriting under pressure. Knowing the cap for each field lets marketers draft to fit and lets developers validate payloads before they ever reach the API.
10 · Questions and answers
Template Character Limits FAQs
- What is the maximum length of a WhatsApp template body?
- 1,024 characters. Meta notes that limits can vary by template format, so check the template editor when you build special formats such as carousels.
- Can a template header be longer than 60 characters?
- No. A text header is capped at 60 characters and can hold one variable. If you need more room, use a media header — image, video or document — and put the text in the body.
- Do emojis count against template character limits?
- Yes, they are characters like any other. Count code points rather than UTF-16 units so your own tooling does not count one emoji twice, and test borderline copy in WhatsApp Manager.
- Why was my short template rejected?
- Probably not for length. A template with too many variables for its amount of text fails with error 2388293, and one that starts or ends with a variable fails with 2388299. Add fixed wording around the placeholders.