> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digifist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables & Localization

> Dynamic variable placeholders in WhatsApp templates — how they are defined, mapped, and managed across multiple languages in Galantis.

Variables make templates personal. Instead of a fixed message that reads identically for every recipient, variables allow a single approved template to address each customer by name, reference their order, or include their specific product — all within a Meta-approved structure. Localization ensures the same variable-driven personalization is available across every language your customers speak.

## What this covers

* Variable placeholder syntax and how placeholders are defined
* The `template_variables_mapping` structure
* Available data sources for variable values
* Example values and why they are required
* Localization — one template per language
* Managing multiple language versions

## Variable placeholder syntax

Variables in WhatsApp templates use positional syntax: `{{1}}`, `{{2}}`, `{{3}}`, and so on. Each number refers to the position of the variable in the template — `{{1}}` is the first variable, `{{2}}` is the second, regardless of where in the body text they appear.

**Rules for placeholders:**

* Positions must be sequential starting from `{{1}}` — skipping a number (e.g., using `{{1}}` and `{{3}}` without `{{2}}`) causes submission to fail
* Variables can appear in the body text and in the text header — not in the footer, and not as the entire content of a button label
* A URL button supports one variable in the URL path: `https://yourstore.com/checkout/{{1}}`
* There is no enforced maximum number of variables, but templates with many variables become harder to maintain and map correctly

## Variable mapping

When a template is selected for use in a campaign or automation, each placeholder must be mapped to a data source. Galantis stores this mapping as `template_variables_mapping`:

```json theme={null}
[
  { "initialValue": "{{1}}", "selectedValue": "customer.first_name" },
  { "initialValue": "{{2}}", "selectedValue": "order.total_price" },
  { "initialValue": "{{3}}", "selectedValue": "static:SUMMER20" }
]
```

Each placeholder is assigned either a dynamic field from customer or order data, or a static text value entered at configuration time.

## Available variable data sources

<Tabs>
  <Tab title="Customer Fields">
    | Field                 | Description                        |
    | --------------------- | ---------------------------------- |
    | `customer.first_name` | Customer's first name from Shopify |
    | `customer.last_name`  | Customer's last name from Shopify  |
    | `customer.email`      | Customer's email address           |
    | `customer.phone`      | Customer's phone number            |

    `customer.first_name` is the most used variable across all template types. Opening with the customer's name meaningfully improves engagement compared to a generic greeting — and costs nothing beyond the variable slot.

    <Note>
      Avoid mapping `customer.email` or `customer.phone` to visible body text variables. Reflecting a customer's own contact details back to them in a promotional message is unexpected and can feel surveillance-like. These fields are available for edge-case technical use, not general personalization.
    </Note>
  </Tab>

  <Tab title="Order Fields">
    | Field                | Description                            |
    | -------------------- | -------------------------------------- |
    | `order.order_number` | Shopify order number                   |
    | `order.total_price`  | Order total value                      |
    | `order.product_name` | Name of the first product in the order |

    Order variables are most appropriate for post-purchase templates — cross-sell sequences, shipping confirmations, or review requests — where the customer expects their recent order to be referenced.
  </Tab>

  <Tab title="Store & Static">
    **Store name** — The name of your Shopify store. Useful for brand reinforcement in templates sent from a number the customer may not immediately recognize.

    **Custom static text** — A fixed string entered directly at mapping configuration time. The same value is sent to all recipients for that placeholder — it does not vary per customer.

    Use static text for:

    * Discount codes that apply to all recipients (`SUMMER20`, `FREESHIP`)
    * Fixed URLs for specific landing pages
    * Consistent offer terms or product names used across a campaign

    Static text is the correct choice any time a variable slot needs a value that does not come from customer data.
  </Tab>
</Tabs>

## Example values — why they are required

Meta requires that every variable placeholder in a submitted template include an example value — a concrete sample of what that variable will contain at send time. Example values are reviewed by Meta as part of the approval process to confirm that the variable content is appropriate for the declared template category.

**What to provide:**

* `{{1}}` mapped to `customer.first_name` → example: `Sarah`
* `{{2}}` mapped to `order.total_price` → example: `$89.00`
* `{{3}}` mapped to a discount code → example: `SUMMER20`

**What not to provide:**

* Generic placeholders like `[name]` or `[value]` — these do not satisfy the example requirement
* Empty strings — a blank example value causes rejection
* Misleading examples that do not represent the actual variable content

<Warning>
  Submitting a template with missing or empty variable examples is one of the most common rejection causes. Fill in realistic, representative examples for every `{{N}}` placeholder before clicking Submit.
</Warning>

## Localization

WhatsApp templates are language-specific. Each template is tied to a single `language` code — for example, `en` for English, `es` for Spanish, `pt_BR` for Brazilian Portuguese. A template approved for `en` cannot be sent to a customer whose preferred language is `es` — a separate template record must exist for each language.

**Creating templates per language:**

1. Build the template content in one language and submit it for approval
2. Create a new template with the same name and structure, set the language to the target language, translate the content, and submit that template separately
3. Repeat for each additional language

Each language version is a fully independent template record with its own approval status, quality metrics, and usage history. An `APPROVED` status in one language does not transfer to another — each must be reviewed and approved by Meta independently.

**Routing customers to language-appropriate templates:**

In automations, use a `CUSTOMER_COUNTRY` or `CUSTOMER_LANGUAGE` condition node to branch customers to the Action Node configured with the appropriate language template. See [Automations — Conditions](/whatsapp/automations/conditions).

In campaigns, create separate campaigns per language and select the corresponding language's template and audience segment for each send.

## Managing variable mapping across language versions

Variable positions must be consistent across language versions of the same template. If `{{1}}` maps to `customer.first_name` in the English version, it must also map to `customer.first_name` in the Spanish version — not to a different field. Inconsistent variable positions across language versions cause confusion when configuring automation Action Nodes that may serve multiple markets.

Establish variable position conventions before creating your first template and apply them consistently across all language versions.

## Best practices

* **Use `{{1}}` for `customer.first_name` consistently across all templates.** Making first name the first variable creates a predictable convention that simplifies mapping configuration across many templates.
* **Keep the variable count low.** Each variable is a mapping task at campaign and automation configuration time. Templates with 5+ variables are harder to configure correctly and more likely to produce awkward messages if any mapping is misconfigured.
* **Write example values that reflect real data.** Use a realistic name, a realistic order value, and a real discount code format. Example values that look nothing like actual customer data can contribute to a misleading category impression during Meta's review.
* **Name language variants consistently.** A naming pattern like `welcome_en`, `welcome_es`, `welcome_pt_BR` makes it easy to identify and select the correct language version when configuring campaigns and automations.
* **Audit variable mappings when updating templates.** If a template is edited and resubmitted with a different variable structure, review and update all campaign and automation configurations that reference it.

## Related guides

* [Creating Templates](./creating-templates) — Where variable placeholders are defined in the template builder
* [Campaigns — Personalization](/whatsapp/campaigns/personalization) — Variable mapping configuration in campaigns
* [Automations — Actions](/whatsapp/automations/actions) — Variable mapping in automation Action Nodes
* [Automations — Conditions](/whatsapp/automations/conditions) — CUSTOMER\_COUNTRY condition for language-based routing