Skip to content

Named Parameters

Also called: Named variables · Named template parameters · Named parameter format · parameter_format named · {{first_name}} placeholders

Definition
Template variables written with descriptive names such as {{first_name}} instead of numbers, matched by name rather than by position when you send.

Exhibit A

Create by name, send by name

3 / 3
{
"name": "report_ready",
"language": "en",
"category": "UTILITY",
"parameter_format": "named",
"components": [
{
"type": "BODY",
"text": "Hi {{patient_name}}, your {{test_name}} report from {{collection_date}} is ready.",
"example": {
"body_text_named_params": [
{ "param_name": "patient_name", "example": "Asha" },
{ "param_name": "test_name", "example": "lipid profile" },
{ "param_name": "collection_date", "example": "17 October" }
]
}
}
]
}

Step 3 of 3 · lines 11–15

One example per name, as param_name + example objects. They can be listed in any order.

Jump to
The same template three ways: the create request, the send request and a small Node.js helper. Step through to see where names replace numbers and why order stops mattering.

Create (named), step 3 of 3, lines 11–15: One example per name, as param_name + example objects. They can be listed in any order.

What is the named parameter format?

Named parameters are the alternative to numbered template variables on the WhatsApp Business Platform. Instead of {{1}} and {{2}}, the template text uses descriptive placeholders such as {{first_name}} and {{order_number}}, and the template is created with parameter_format set to named. A template created without that field uses positional numbering, the default.

The names travel with the data. At creation, examples go in body_text_named_params — or header_text_named_params for a text header — as objects with a param_name and an example. At send time each header or body value carries a parameter_name next to its text, so the request says which value is the customer's name instead of relying on its place in an array. Meta states that example values and real values for named parameters can appear in any order, while positional values must follow the order of their placeholders.

Names must be unique within the template and made only of lowercase letters and underscores. Everything else about variables stays the same: every parameter still needs sample values, the text still cannot start or end with one, a text header still takes only one, and too many parameters for the message length still leads to rejection. Buttons are unchanged as well — a dynamic URL button is still filled through a button component addressed by its index. In short, a message template variable written as {{1}} and one written as {{first_name}} follow the same review rules; only how the template is created and how values are matched at send time differ.

Key takeaways

  • Named parameters are template variables written as {{first_name}} instead of {{1}}, matched by name rather than by position when you send.
  • Set parameter_format to named when you create the template; without it the template uses positional numbering.
  • Names must be unique within the template and use only lowercase letters and underscores.
  • Each send value carries a parameter_name, so the order of values in the parameters array no longer matters.
  • Placement, sample and length rules are the same as for positional variables, and moving a live template to names means a new submission plus a code change.

Why does the named parameter format matter?

Positional numbering gets fragile once templates grow or change hands. A developer reading parameters[2] has to open the template to learn it is the delivery date, and inserting a new variable in a later version shifts every number after it, silently mismatching the integration. Named parameters make the payload self-describing, let code build values straight from an object instead of a carefully ordered array, and make review notes and support tickets easier to follow because the template explains itself.

How does the named parameter format work?

  1. Name each placeholder

    Write the text with lowercase, underscore-separated names that describe the data — {{patient_name}}, {{test_name}}, {{collection_date}}. Names must be unique within the template.

  2. Create the template as named

    In the create request to the WABA's message_templates edge (the template management API), set parameter_format to named and give one example per name in body_text_named_params or header_text_named_params.

  3. Pass review as usual

    Review applies the same placement, sample, policy and category rules as positional templates. The names are never shown to the customer — only the values are.

  4. Send values by name

    In the /messages request, give each header or body parameter type: text, a parameter_name and its text. The order of the array no longer matters.

  5. Migrate deliberately

    An existing positional template keeps its format. To switch, submit a named version as a new template, deploy code that sends the names once it is approved, then retire the positional one.

The named parameter format in code

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": "report_ready",
    "language": "en",
    "category": "UTILITY",
    "parameter_format": "named",
    "components": [{
      "type": "BODY",
      "text": "Hi {{patient_name}}, your {{test_name}} report from {{collection_date}} is ready.",
      "example": { "body_text_named_params": [
        { "param_name": "patient_name", "example": "Asha" },
        { "param_name": "test_name", "example": "lipid profile" },
        { "param_name": "collection_date", "example": "17 October" }
      ] }
    }]
  }'

parameter_format applies to the whole template; each name gets its own example.

Common mistakes with the named parameter format

  • Building payloads without knowing the format

    A named template expects a parameter_name on every header and body value; a positional template expects values in order. Store parameter_format with each template record and build the payload from it, rather than assuming one style everywhere.

  • Using capitals or hyphens in names

    Placeholders such as {{FirstName}} or {{order-id}} break the lowercase-and-underscore rule. Use {{first_name}} and {{order_id}}, and keep the same spelling in your code.

  • Assuming names relax the content rules

    A body that is mostly placeholders is still rejected, and descriptive names do not make a vague template clearer to a reviewer. Keep the same amount of fixed text you would with numbers.

  • Renaming parameters in a live template

    A parameter's name is part of the contract your code depends on. Changing it means a new review and a payload change at the same moment; version the template instead and switch traffic once the new version is approved.

Example: A lab report template that survives a new version

A Hyderabad diagnostics lab sends a report_ready utility template: “Hi {{patient_name}}, your {{test_name}} report from {{collection_date}} is ready.” Its integration builds { patient_name, test_name, collection_date } straight from the lab record, so there is no array order to get wrong. When the lab later adds {{branch_name}} in a new version for patients who visit several centres, no existing value shifts position: the old template keeps working until the new one is approved and the code switches over in a single release.

Named Parameters FAQs

Can one template mix named and positional parameters?+
The format is chosen once for the whole template with `parameter_format`, so write every placeholder in that template in the same style.
Do customers see the parameter names?+
No. Customers see only the values you send. The names exist in the template definition and in the API payload.
Is a template with named parameters priced differently?+
No. Meta charges per delivered message by template category; how the variables are written makes no difference.
Should I convert all my positional templates?+
Not all at once. Use named parameters for new templates, and convert a positional one when you next need to change it anyway, since the switch means a new submission and a code change.

Best practices for the named parameter format

  • Name parameters after the fields in your data model so the mapping code is a single object.
  • Prefer specific names — {{delivery_date}} ages better than {{date}} once a template carries two dates.
  • Log the template name, version and parameter names with each send to make failed sends easy to trace.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms