Summarise this article with:
On this page6 sections
To use named parameters in a WhatsApp template, write placeholders such as {{customer_name}} instead of {{1}}, set parameter_format to named when you create the template, and send every value with a matching parameter_name. Templates created without that field stay positional, and an approved positional template cannot be switched over in place.
This guide covers the adoption work: choosing the format, naming variables so they last, writing sample values, changing your send code and moving live templates across without a gap in sends. For a one-paragraph definition, see the glossary entry on named parameters.
Named or positional: what changes in practice
Meta's template fundamentals documentation says that when a template string contains parameters, you can specify their format, named or positional, at creation, and you must include an example value for each parameter. If you specify nothing, the template is positional.
The difference shows up in three places: the template text, the example block you submit for review, and the send request.
| Positional | Named | |
|---|---|---|
| Placeholder | {{1}}, {{2}}, numbered from 1 |
{{customer_name}}, {{due_date}} |
| Set at creation | Default; no field needed | "parameter_format": "named" |
| Example values | body_text, in placeholder order |
body_text_named_params, any order |
| Send-time values | text only, in placeholder order |
parameter_name plus text, any order |
| What breaks it | Values sent in the wrong order | A name that does not match the template |
The last row is why teams switch. A positional send with two values swapped still delivers, with the delivery date where the customer's name should be. A named send says which value is which, so the payload can be read without opening the template.
Positional templates are still fine for short messages. A one-variable OTP fallback or a two-variable delivery alert is easy to keep in order. Named parameters earn their keep on templates with four or more variables, templates that marketing and engineering both touch, and templates that several systems (a CRM, a store, a support tool) fill from their own data.
Naming rules, and a convention that lasts
Meta's rule is short: named parameters must be unique, single strings made of lowercase characters and underscores, wrapped in double curly brackets. That rules out {{FirstName}}, {{order-id}} and {{customer name}}. Because the rule mentions only lowercase characters and underscores, leave digits out as well: write {{address_line_one}}, not {{address_line1}}.
Within those rules, the names you pick become part of the contract between the template and your code. A few habits keep that contract stable:
- Name after your data model. If your order table calls the field
delivery_date, so should the template. The mapping code then becomes a straight copy of fields. - Be specific.
{{date}}works until the template needs a second date.{{dispatch_date}}and{{delivery_date}}never collide. - Reuse names across templates. If
{{customer_name}}means the same thing in all 40 templates, one helper fills all of them. - Keep a register. A shared sheet listing each name, its source field and an example value saves arguments when the ops team edits copy and engineering ships code.
Names do not relax the review rules. Meta's template review page rejects templates that start or end with a parameter, contain special characters such as #, $ or % in parameters, or carry too many parameters relative to the message length. That page writes its examples in {{1}} style, and nothing in Meta's documentation exempts named templates, so apply the same rules. InfiQ's guide to template rejection reasons covers the other common failures.
Creating a named template with sample values
A named template is created on the same message_templates endpoint as any other. The differences are the parameter_format field and the shape of the examples. Per Meta's template components reference, the body takes multiple parameters within its 1,024-character limit and examples go in body_text_named_params; a text header takes one parameter within 60 characters, with its example in header_text_named_params.
Here is an illustrative request for a fee reminder from a hypothetical coaching institute in Kota. It follows the shape in Meta's docs, using Graph API v26.0, the newest version on the Graph API changelog (introduced 29 July 2026):
curl -X POST "https://graph.facebook.com/v26.0/{WABA_ID}/message_templates" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "fee_due_reminder_v2",
"language": "en",
"category": "UTILITY",
"parameter_format": "named",
"components": [{
"type": "BODY",
"text": "Hello {{student_name}}, the {{term_name}} fee of {{amount_due}} for {{course_name}} is due on {{due_date}}. Please pay before the due date to avoid a late charge.",
"example": { "body_text_named_params": [
{ "param_name": "student_name", "example": "Aarav" },
{ "param_name": "term_name", "example": "Term 2" },
{ "param_name": "amount_due", "example": "₹18,500" },
{ "param_name": "course_name", "example": "JEE Foundation" },
{ "param_name": "due_date", "example": "10 November 2026" }
] }
}]
}'
Three details matter for review:
- Every name needs an example. Meta requires an example value for each parameter at creation.
- Examples should look like real data. Meta notes that a sample makes it easier for reviewers to see how the template will appear to customers. "Aarav" and "₹18,500" read as a message; "test" and "123" do not.
- The fixed text still has to carry the meaning. Five placeholders inside two plain sentences gives the reviewer enough context; five placeholders joined by commas does not.
Review can take up to 24 hours, per Meta's review documentation, so create named templates ahead of the day you need them.
Sending a named template
The send request goes to the same /messages endpoint. Each named value gains a parameter_name, which Meta's coupon code templates reference marks as required when a template uses named parameters. An illustrative body component:
{
"type": "body",
"parameters": [
{ "type": "text", "parameter_name": "due_date", "text": "10 November 2026" },
{ "type": "text", "parameter_name": "student_name", "text": "Ishita" },
{ "type": "text", "parameter_name": "term_name", "text": "Term 2" },
{ "type": "text", "parameter_name": "amount_due", "text": "₹18,500" },
{ "type": "text", "parameter_name": "course_name", "text": "NEET Repeater" }
]
}
The values are out of order on purpose: Meta's docs say real values for named parameters can appear in any order. Buttons are a separate case. A URL button supports one variable appended to the end of the URL, and Meta's examples show it as {{1}}, so keep your existing button handling and test it against the new template.
The failures to watch for after the switch are listed in Meta's error codes reference: 132000 when the number of values does not match the template, 132012 when values do not use the format the template specifies, and, since v23.0, 132018 for template parameter issues at send time.
The most reliable defence is to stop assuming one style. Meta's template management API returns parameter_format as NAMED or POSITIONAL for each template, so store it alongside the template name and let your send code build the payload from it.
Moving existing positional templates over
You cannot flip an approved template's format. Meta's editing rules say you can only edit a template's category, components or time-to-live, and parameter_format is not among them. Migration therefore means a new template, and a little planning keeps sends running throughout.
| Step | What to do | Why it matters |
|---|---|---|
| 1. Inventory | List templates with their parameter_format, variable count and monthly sends |
Shows which templates are worth moving |
| 2. Choose | Start with templates that have four or more variables or change often | One- and two-variable templates rarely justify the work |
| 3. Create the twin | Same wording and category, named placeholders, a new name such as _v2 |
The old template keeps sending while the new one is reviewed |
| 4. Switch code | Deploy send code that builds the payload from the stored format | Both versions can run during the changeover |
| 5. Watch | Track 132000, 132012 and 132018 for the first days of sends | Catches a mismatched name before a large campaign |
| 6. Retire | Delete the old template only when nothing references it | A deleted approved template's name is blocked for 30 days |
Two account limits from Meta's template fundamentals page affect a large migration. Each WhatsApp Business Account holds 250 templates if its business portfolio is unverified, or up to 6,000 if the portfolio is verified and has a number with an approved display name, and twins occupy slots until the originals are deleted. You can also create at most 100 templates per hour in an account, so a bulk script should pace itself.
If a template exists in several languages, as many Indian templates do, recreate every language under the new name before you switch traffic. Deleting a template by name removes all its language versions at once. InfiQ's guide to templates in Indian languages covers how those versions are organised.
Setting this up on InfiQ
InfiQ's template manager lets you draft templates with variable placeholders, add a sample value for each variable and run a validator on structure and category before the template reaches Meta. It tracks review status and keeps a version history of each template, which helps when a positional template and its named copy run side by side.
