Named Variables

Write templates with readable placeholders like {{name}} instead of {{1}}, and fill them by name from the API, campaigns, chatbots, and Team Chats.

Named variables let you write a template as Hello {{name}}, I'm {{vendor_name}} instead of Hello {{1}}, I'm {{2}}. When you send it, you pass values by name, so you never have to track which number means what. A name can appear more than once, and every place it appears gets the same value.

In the app: Dashboard → Settings → Named Variables

Meta still sees a normal template

Pingmate turns each name into a numbered slot when it submits the template, and keeps the name-to-slot map itself. Meta reviews and delivers an ordinary positional template, so approval works exactly as before. This is separate from Meta's own "named parameter" format.

Kinds of variables

Custom variables

You create these in Settings. Each one has:

Field	Required	What it does
Key	Yes	The name used in templates, for example `vendor_name`. Lowercase letters, digits and `_`, starting with a letter, up to 50 characters. It can't be changed after creation.
Label	No	A friendly name shown in pickers. Defaults to the key.
Sample value	Yes	Sent to Meta as the example for review, so make it realistic ("Narayan", "₹1,500").
Fallback value	No	Used when a send doesn't supply a value. Without one, a send that leaves the variable out fails.

System variables

These are built in and fill themselves from the recipient or your account:

Variable	Value
`customer.name`	The customer's saved name
`customer.phone`	The customer's phone number
`customer.email`	The customer's `email` attribute
`customer.attributes.<attribute>`	Any customer attribute, for example `customer.attributes.city`
`business.name`	Your WhatsApp business display name
`date.today`	Today's date (DD-MM-YYYY) in your account's timezone

If a system variable has no data for a recipient (for example, no email saved), the send fails for that recipient unless you pass the value yourself. For data that may be missing, create a custom variable with a fallback instead.

Using them in a template

In the template editor, click Named variable next to the header, body, or URL button field.

Pick an existing variable from My variables, System, or Attributes, or click Create new to add one without leaving the editor.

The placeholder is inserted as {{key}}. Sample values fill in automatically from each variable's sample.

A template uses either named or numbered placeholders, never both. A few rules come from Meta and are checked before the template is submitted:

The header can contain at most one variable.

The body can't start or end with a variable.

A URL button can contain one variable, and only at the end of the URL.

Carousel cards don't support named variables yet.

Templates list, previews, and the copy button all show the named form, for example Hello {{name}}.

Filling values

Resolution order for each variable: the value you pass → the system value → the custom variable's fallback. Blank values count as missing.

Where	How
Campaigns	Step 3 shows one row per variable name. Map each to a CSV column, a customer attribute, or a static value. System variables are filled per recipient automatically. See Campaigns.
Team Chats	The template picker shows one input per name.
Chatbot	The Send Template node shows one input per name. Values can use flow expressions such as `{{customer.name}}`.
API	Pass a `named_variables` object, shown below.

API

Send named_variables instead of body_variables / header_variables. Sending both returns 400.

curl -X POST "https://your-host/api/v1/messages/send" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "message": {
      "message_type": "template",
      "template_name": "vendor_intro",
      "template_language": "en_US",
      "named_variables": {
        "name": "Manjeet",
        "vendor_name": "Narayan"
      }
    }
  }'

For the template Hello {{name}}, my name is {{vendor_name}}. Regards, {{vendor_name}}, this sends "Hello Manjeet, my name is Narayan. Regards, Narayan". System variables like {{customer.name}} can be left out. If a custom variable is missing and has no fallback, the response is 400 and lists the missing names.

With the GET send endpoint, pass each value as a query parameter: namedVariables[name]=Manjeet&namedVariables[vendor_name]=Narayan.

To list your variables from code, call GET /api/v1/named-variables. For the built-in ones, call GET /api/v1/named-variables/system. SDK examples: TypeScript, PHP, Java, C#.

Editing and deleting

Edit changes the label, sample, and fallback. The key stays the same.

Delete is blocked while any template still uses the variable. The error lists those templates. Delete or replace them first.

If a template is edited directly in Meta so its variables no longer line up, Pingmate drops its name map on the next sync. The template then goes back to numbered {{1}} values.