POST/v1/templates/lintbeta

Check a template draft

Needs: Read your data (mcp:read)
Plan: Any plan with API access
Limits: 300 a minute per key
Undo: Nothing to undo: nothing is saved.

Checks a template draft against WhatsApp's rules — names, categories, lengths, variables and buttons — without saving or submitting anything. Every issue comes with a fix.

Try it

Edit as JSON

template *

A template draft.

namerequiredstring

Template name: lowercase letters, digits, underscores (e.g. order_shipped_v2).

languagerequiredstring

Meta language code, e.g. en, en_US, ar, hi, pt_BR.

categoryrequiredstring

MARKETING | UTILITY | AUTHENTICATION.

header

Optional header.

formatrequiredstring

TEXT | IMAGE | VIDEO | DOCUMENT | LOCATION.

textoptionalstring

TEXT header: ≤ 60 chars, at most one {{1}}.

exampleoptionalstring

TEXT header with {{1}}: its sample value.

media_handleoptionalstring

IMAGE/VIDEO/DOCUMENT header: the Meta upload handle used as the sample (`POST /v1/templates/samples`).

body

Body.

textoptionalstring

Body text (≤ 1024 chars) with {{1}}, {{2}} … variables. Omit for AUTHENTICATION (Meta fixes it).

examplesoptionallist

One sample per body variable, in order ({{1}} first).

add_security_recommendationoptionalboolean

AUTHENTICATION only: append "For your security, do not share this code."

footer

Optional footer.

textoptionalstring

Footer text (≤ 60 chars, no variables).

code_expiration_minutesoptionalinteger

AUTHENTICATION only: code expiry shown in the footer (1-90).

buttonsoptionallist (JSON)

Buttons in display order (≤ 10).

limited_time_offer

Limited-time offer (MARKETING; needs a COPY_CODE button).

textrequiredstring

Offer text shown on the chip (≤ 16 chars).

has_expirationoptionalboolean

Show a countdown (the expiry is set when sending).

carousel

Media carousel (MARKETING): the body is the message above the cards; no top-level header, footer or buttons.

cardsrequiredlist (JSON)

2-10 cards.

This only reads. It uses your real data and changes nothing.

curl -X POST 'https://mcp.wa-api.cloud/v1/templates/lint' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "template": {
    "name": "order_shipped",
    "language": "en_US",
    "category": "UTILITY",
    "body": {
      "text": "Hi {{1}}, your order {{2}} is on its way.",
      "examples": [
        "Jane"
      ]
    }
  }
}'

The code reads your key from $API_KEY.

Body

Body fields
Field	Type	What it is
templaterequired	object	A template draft.
namerequired	string	Template name: lowercase letters, digits, underscores (e.g. order_shipped_v2).0–1000 characters
languagerequired	string	Meta language code, e.g. en, en_US, ar, hi, pt_BR.0–20 characters
categoryrequired	string	MARKETING \| UTILITY \| AUTHENTICATION.0–40 characters
header	object	Optional header.
formatrequired	string	TEXT \| IMAGE \| VIDEO \| DOCUMENT \| LOCATION.one of: `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT`, `LOCATION`
text	string	TEXT header: ≤ 60 chars, at most one {{1}}.0–1000 characters
example	string	TEXT header with {{1}}: its sample value.0–1000 characters
media_handle	string	IMAGE/VIDEO/DOCUMENT header: the Meta upload handle used as the sample (`POST /v1/templates/samples`).0–4000 characters
body	object	Body.default `{}`
text	string	Body text (≤ 1024 chars) with {{1}}, {{2}} … variables. Omit for AUTHENTICATION (Meta fixes it).0–5000 characters
examples	array of string	One sample per body variable, in order ({{1}} first).0–100 items
add_security_recommendation	boolean	AUTHENTICATION only: append "For your security, do not share this code."
footer	object	Optional footer.
text	string	Footer text (≤ 60 chars, no variables).0–1000 characters
code_expiration_minutes	integer	AUTHENTICATION only: code expiry shown in the footer (1-90).-9007199254740991–9007199254740991
buttons	array of object	Buttons in display order (≤ 10).0–30 items
typerequired	string	QUICK_REPLY \| URL \| PHONE_NUMBER \| COPY_CODE \| FLOW \| VOICE_CALL \| OTP.one of: `QUICK_REPLY`, `URL`, `PHONE_NUMBER`, `COPY_CODE`, `FLOW`, `VOICE_CALL`, `OTP`
text	string	Button label (≤ 25 chars). Not used for COPY_CODE.0–200 characters
url	string	URL buttons: https URL; for a dynamic URL end it with {{1}} (e.g. https://shop.example/track/{{1}}).0–4000 characters
url_example	string	Dynamic URL buttons: a full example URL with the variable filled in.0–4000 characters
phone_number	string	PHONE_NUMBER buttons: E.164 number, e.g. +971501234567.0–64 characters
coupon_code	string	COPY_CODE buttons: the coupon code to copy (≤ 20 chars).0–64 characters
flow_id	string	FLOW buttons: the WhatsApp flow id.0–64 characters
flow_action	string	FLOW buttons: NAVIGATE (default) or DATA_EXCHANGE for endpoint flows.one of: `NAVIGATE`, `DATA_EXCHANGE`
navigate_screen	string	FLOW buttons with NAVIGATE: the first screen id.0–200 characters
otp_type	string	OTP buttons: COPY_CODE (default), ONE_TAP or ZERO_TAP.one of: `COPY_CODE`, `ONE_TAP`, `ZERO_TAP`
supported_apps	array of object	ONE_TAP / ZERO_TAP OTP buttons: your Android app(s).0–5 items
package_namerequired	string	Android package name.0–255 characters
signature_hashrequired	string	App signing key hash.0–64 characters
limited_time_offer	object	Limited-time offer (MARKETING; needs a COPY_CODE button).
textrequired	string	Offer text shown on the chip (≤ 16 chars).0–200 characters
has_expiration	boolean	Show a countdown (the expiry is set when sending).
carousel	object	Media carousel (MARKETING): the body is the message above the cards; no top-level header, footer or buttons.
cardsrequired	array of object	2-10 cards.0–20 items
header_formatrequired	string	Card media type (the same on every card).one of: `IMAGE`, `VIDEO`
media_handlerequired	string	Meta upload handle for the card media (`POST /v1/templates/samples`).0–4000 characters
body	object	Card text.
buttonsrequired	array of object	1-2 buttons (QUICK_REPLY, URL, PHONE_NUMBER), the same layout on every card.0–5 items

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`

Response `200`

The result of the check.

Response fields
Field	Type	What it is
validrequired	boolean	true when there are no errors (warnings may remain).
errorsrequired	number
warningsrequired	number
issuesrequired	array of object
rulerequired	string
severityrequired	string	one of: `error`, `warning`, `info`
pathrequired	string
messagerequired	string
fixrequired	string
variablesrequired	object
headerrequired	number
bodyrequired	number
previewrequired	string or null	Body with samples filled in.

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.

Examples

A draft with a missing sample

Request body

{
  "template": {
    "name": "order_shipped",
    "language": "en_US",
    "category": "UTILITY",
    "body": {
      "text": "Hi {{1}}, your order {{2}} is on its way.",
      "examples": [
        "Jane"
      ]
    }
  }
}

Response 200

{
  "valid": false,
  "errors": 1,
  "warnings": 0,
  "issues": [
    {
      "rule": "body.samples",
      "severity": "error",
      "path": "body.examples",
      "message": "The body has 2 variables but 1 sample.",
      "fix": "Add a sample for {{2}}, e.g. \"#1001\"."
    }
  ],
  "variables": {
    "header": 0,
    "body": 2
  },
  "preview": null
}

Operation path

The same operation is also at POST /v1/ops/messaging_lint_template, with every field in the JSON body.

Try it

Code and response

Body

Headers

Response 200

Errors

Examples

Operation path

Response `200`