Troubleshoot WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH

You send a WhatsApp template and get an HTTP 400 back before any message goes out. Orbit validates the parameter list against the template body at accept time and refuses the send when the two disagree, so a bad payload is a cheap 400 instead of a rejected Meta delivery.

This page covers the send-side parameter check — the count and shape of the values you pass. For Meta-side template problems (pending, rejected, paused, reclassified, 24-hour window), see WhatsApp template status.

An example response:

{
  "error": {
    "code": "WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH",
    "message": "Template \"order_shipped\" expects 2 parameter(s) but 1 were supplied. Meta will reject the send (132000/131008) — fix the parameter list.",
    "details": {
      "template_name": "order_shipped",
      "expected": 2,
      "supplied": 1,
      "reason": "missing_params"
    }
  }
}

The same code fires for an empty value, with reason: empty_param_value and a details.empty_keys list naming the slots:

{
  "error": {
    "code": "WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH",
    "message": "Template \"order_shipped\" has empty parameter(s): 2. Meta rejects template sends with empty positional vars (132012). Provide non-empty values.",
    "details": {
      "template_name": "order_shipped",
      "expected": 2,
      "supplied": 2,
      "empty_keys": ["2"],
      "reason": "empty_param_value"
    }
  }
}

How parameter indexing works

A WhatsApp template body declares positional placeholders {{1}}, {{2}}, … {{N}}. On the send you pass template_params, an object whose keys are the 1-based placeholder numbers and whose values are the replacement strings:

Template body:  "Hi {{1}}, order {{2}} shipped!"

Send payload:   { "template_params": { "1": "Ava", "2": "1042" } }

The pre-flight check reads the approved template body, counts its placeholders, and compares that count against the parameters you supplied. Two call-site shapes count as the parameter source: the template_params object, or (for outbound templates saved with a Media header) the Meta-native metadata.templateComponents array — whichever is non-empty. Results of the comparison:

Fewer parameters than placeholders → 400, reason: missing_params.
More parameters than placeholders → 400, reason: extra_params.
Parameters on a zero-placeholder template → 400, reason: extra_params_on_zero_placeholder_template.
Same count but a value is an empty or whitespace-only string → 400, reason: empty_param_value, with details.empty_keys.

A count match only clears this check. If the keys are non-positional ("name", "first_name") or skip a number ("1", "3" for a two-placeholder template), the provider rejects the send again at build time with WHATSAPP_TEMPLATE_PARAM_MISSING even when the count lines up. Keys must be exactly the contiguous series "1" … "N".

Common mismatches

Work the table in order — each row is one fixable cause.

Cause	Symptom	Fix
Hard-coded parameters, template edited since	`missing_params` or `extra_params` on every send	Read the current template body (below) and bring the parameter list in line
A value passed as `""`, `null`, or whitespace	`empty_param_value` with the offending keys in `details.empty_keys`	Trim and validate values at your call site before the request leaves
Named keys instead of positional keys	`WHATSAPP_TEMPLATE_PARAM_MISSING` even when the count matches	Rename keys to `"1"…"N"`; order is assigned by key, not by insertion
Incorrect one of the two parameter shapes	`template_params` and `metadata.templateComponents` populated with different counts	Send one shape only — the checker uses whichever is non-empty and never adds the two together
A Media header variable passed in `template_params`	`extra_params` — body placeholders are one fewer than the total	Pass header and button variables through `metadata.templateComponents`; `template_params` fills the body only

Read the template body you are sending against

Do not count placeholders from memory — templates drift. Fetch the current body and count the {{N}} markers yourself:

curl -G "https://api.orbit.devotel.io/api/v1/messages/templates" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  --data-urlencode "search=order_shipped" \
  --data-urlencode "channel=whatsapp"

Fetch the full record at GET /api/v1/messages/templates/{id} for the complete body text. The count check only runs when the template body (or header) text is stored locally — authentication (OTP) templates and Meta-synced templates whose body lives inside the stored components defer to Meta instead, so a mismatch there surfaces as a harder-to-read 132000/131008 rejection after the fact.

Fix by example

Template with a Media header variable and one body placeholder:

Header: image with a variable URL (or fixed media)
Body: Your order {{1}} shipped today.

The correct send payload passes the header component through metadata.templateComponents and the body value through template_params:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+14155552671",
    "template_name": "order_shipped_media",
    "template_language": "en_US",
    "template_params": { "1": "1042" },
    "metadata": {
      "templateComponents": "[{\"type\":\"header\",\"parameters\":[{\"type\":\"image\",\"image\":{\"link\":\"https://example-cdn.devotel.io/order-1042.png\"}}]}]"
    }
  }'

The body placeholder {{1}} gets one parameter, the header variable rides in templateComponents, and the pre-flight passes. For a text-only template, drop metadata and fill every {{N}} from template_params alone.

Validate before you send

The remediation loop is short — treat the 400 as a compile error:

Fetch the template body (above) and count {{N}} placeholders.
Build template_params with keys "1"–"N" in that order.
Confirm no value is empty or whitespace-only.
For header/button variables, move them into metadata.templateComponents in the Meta component shape.
Re-send. The same check runs on every WhatsApp template request, so a fixed payload clears it immediately.

In the dashboard template editor, the preview fills sample values into each placeholder — use it to confirm which slots the template expects before wiring your send code.

Escalation checklist

If you have worked the page and the same 400 keeps coming back, email whatsapp-support@devotel.io with:

The template name and language exactly as Meta has them (order_shipped + en_US).
The full error response body, including details.expected, details.supplied, and details.reason.
The template body text as fetched from GET /api/v1/messages/templates/{id}.
The exact request payload you sent, with phone numbers and parameter values redacted.

Reference

Troubleshoot WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH

Troubleshoot WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH

How parameter indexing works

Common mismatches

Read the template body you are sending against

Fix by example

Validate before you send

Escalation checklist

See also

​Troubleshoot WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH

​How parameter indexing works

​Common mismatches

​Read the template body you are sending against

​Fix by example

​Validate before you send

​Escalation checklist

​See also

Troubleshoot WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH

How parameter indexing works

Common mismatches

Read the template body you are sending against

Fix by example

Validate before you send

Escalation checklist

See also