Create Template

What it does

Creates a new WhatsApp message template and submits it to Meta for approval. A newly created template’s status is usually PENDING.

Endpoint

POST /api/v1/wa/{app_id}/templates

There are no query parameters.

Headers

string

required

Secret key in Bearer sk_... format. See Secret Key authentication.

string

required

Always application/json.

Path parameters

string

required

Application ID. Must belong to the organization (otherwise 404).

Request Body

Top-level fields

string

required

Template name (max 512 chars). Pattern: ^[a-z][a-z0-9_]*$ (must start with a lowercase letter; lowercase letters, digits, and underscores only). Must be unique.

string

required

Language code, e.g. tr, en, en_US. This is a closed list, not free-form BCP-47 — see Template Language. An unsupported code returns 422.

string

required

One of UTILITY, MARKETING, or AUTHENTICATION. Determines the component rules — see the Category rules section below, and Template Category for what each one is for.

object | null

Header component. See the header object below.

object

required

Body component. See the body object below.

object | null

Footer component. See the footer object below.

array | null

List of buttons (max 10). See the buttons object below. Not allowed together with carousel — carousel buttons belong to each card.

array | null

Turns the template into a carousel: a body bubble followed by 2–10 swipeable cards, each with its own media header, body, and buttons. MARKETING only. See the carousel card object and Carousel rules sections below.

boolean | null

If true, Meta may automatically re-classify the template’s category.

integer | null

Message time-to-live. UTILITY: 30–43200, MARKETING: 43200–2592000, AUTHENTICATION: 30–900 (or -1).

object | null

Turns the template into a limited-time offer — a MARKETING-only banner that WhatsApp renders above the body, optionally with a live expiration countdown. See the limitedTimeOffer object and Limited-time offer rules sections below.

header object

string

One of NONE (default), TEXT, IMAGE, VIDEO, DOCUMENT, LOCATION. See Header Format.

string

Only for TEXT headers (max 60 chars). Cannot start or end with a variable.

string | string[]

Variable example for a TEXT header; for media headers, the uploaded media handle.

body object

string

Body text (max 1024 chars); supports {{1}}, {{2}} variables. Cannot start or end with a variable. Required for UTILITY/MARKETING.

string[]

Example values for the variables (order matters). The count must equal the number of variables.

boolean

AUTHENTICATION only; adds the security recommendation text.

string

Footer text (max 60 chars). Cannot be used in AUTHENTICATION.

integer

AUTHENTICATION only (1–90); the code validity duration.

buttons object

Each item in the buttons array:

string

One of QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, OTP. See Button Type.

string

Button text (2–25 chars). Required for URL / PHONE_NUMBER / QUICK_REPLY.

string

URL type target link (https://...); can be dynamic using {{1}}.

string

PHONE_NUMBER type phone in E.164 format.

string[]

Dynamic URL example, or the COPY_CODE coupon code (required for COPY_CODE).

string

For OTP: one of COPY_CODE, ONE_TAP, ZERO_TAP. See OTP Type.

string

ONE_TAP / ZERO_TAP autofill text (max 25 chars).

string

ONE_TAP / ZERO_TAP Android package name.

string

ONE_TAP / ZERO_TAP signature hash.

boolean

ZERO_TAP terms acceptance.

carousel card object

Each item in the carousel array is one card. Every card must be structurally identical to the others (same header format, same button types in the same order).

object

required

The card’s media header. format must be IMAGE or VIDEO — no TEXT, DOCUMENT, or LOCATION — and examples must carry the media handle from Upload Media.

object

required

The card’s body. text is required and limited to 160 chars (shorter than the 1024 of the template body). Variables and examples follow the same rules as the template body.

array

required

1–2 buttons for this card. Only QUICK_REPLY, URL, and PHONE_NUMBER are allowed — no COPY_CODE or OTP.

limitedTimeOffer object

string

required

The offer text shown on the banner (1–16 chars), e.g. "Expiring offer!".

boolean

Defaults to false. When true, WhatsApp renders an expiration countdown on the offer; the expiration timestamp itself is supplied per message when the template is sent, not here.

Category rules

AUTHENTICATION — no header; no body.text (only addSecurityRecommendation); no footer.text (only codeExpirationMinutes); buttons may only be OTP.

UTILITY / MARKETING — body.text is required; addSecurityRecommendation and codeExpirationMinutes cannot be used; OTP buttons are not allowed; COPY_CODE is allowed in MARKETING only.

The body/header cannot start or end with a variable, and the number of examples must equal the number of variables.

Carousel rules

Sending carousel puts the template into carousel mode: the top-level template keeps only its body bubble, and every other component moves into the cards. All of the rules below are enforced locally and fail with 422 before the request reaches Meta.

Rule	Code
`category` must be `MARKETING`.	`WA_TPL_035`
No top-level `header` (omit it, or send `format: "NONE"`).	`WA_TPL_036`
No top-level `footer`.	`WA_TPL_037`
No top-level `buttons` — they belong to each card.	`WA_TPL_038`
Between 2 and 10 cards.	`WA_TPL_039`
Every card must use the same header format (all `IMAGE` or all `VIDEO`).	`WA_TPL_040`
Every card must have the same button types in the same order.	`WA_TPL_041`
A card header must be `IMAGE` or `VIDEO`.	`WA_TPL_042`
A card header must carry a media handle in `examples`.	`WA_TPL_043`
A card body `text` is required.	`WA_TPL_044`
A card body `text` is at most 160 chars.	`WA_TPL_045`
Card buttons may only be `QUICK_REPLY`, `URL`, or `PHONE_NUMBER`.	`WA_TPL_046`

Carousel is create-only. Update Template does not accept a carousel field, so an existing carousel template cannot have its cards edited through this API — create a new template instead.

carousel and limitedTimeOffer cannot be combined in the same template (WA_TPL_052). Each card needs its own uploaded media handle, so a 5-card carousel means 5 separate Upload Media calls.

Limited-time offer rules

Sending limitedTimeOffer puts the template into limited-time offer mode, which narrows what the other components may contain. All of the rules below are enforced locally and fail with 422 before the request reaches Meta; omitting limitedTimeOffer leaves every other rule on this page unchanged.

Rule	Code
`category` must be `MARKETING`.	`WA_TPL_048`
`body.text` is required and cannot be empty.	`WA_TPL_049`
`header.format` may only be `NONE`, `IMAGE`, or `VIDEO` — `TEXT`, `DOCUMENT`, and `LOCATION` are rejected.	`WA_TPL_050`
`footer.text` cannot be used.	`WA_TPL_051`
`carousel` cannot be combined with a limited-time offer.	`WA_TPL_052`
Buttons may only be `COPY_CODE` or `URL`.	`WA_TPL_053`
At most one `COPY_CODE` button.	`WA_TPL_054`
At most two buttons in total (instead of the usual 10).	`WA_TPL_055`

The common pairing is one COPY_CODE button carrying the coupon code plus one URL button linking to the campaign — that is the maximum a limited-time offer template allows.

hasExpiration only controls whether the countdown is rendered. The offer’s expiration timestamp is not part of the template; it is provided per message at send time, so the same approved template can be reused for different deadlines.

Response

The envelope is { "data": {...}, "isSuccess": true } (HTTP 200). The data is a lean creation response:

boolean

true when the template was created and submitted.

object

Show data

string

The template’s Meta ID.

string

Template name.

string

Language code.

string

UTILITY, MARKETING, or AUTHENTICATION. May differ from what you sent if Meta re-classifies the template.

string

Usually PENDING (under review) right after creation. The full set is APPROVED, PENDING, REJECTED, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION, DELETED, LIMIT_EXCEEDED, UNKNOWN — see Template Status.

The create response does not return components, qualityScore, rejectedReason, parameterFormat, or the DB id — use Get Template Detail or Get Templates for those.

Examples

Demo 1 — UTILITY (lean)

POST /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...
Content-Type: application/json

{
  "name": "shipping_update",
  "language": "en",
  "category": "UTILITY",
  "body": { "text": "Hi {{1}}, your order {{2}} is on its way.", "examples": ["John", "#12345"] }
}

{ "data": { "sourceId": "1029384756123", "name": "shipping_update", "language": "en", "category": "UTILITY", "status": "PENDING" }, "isSuccess": true }

Demo 2 — UTILITY (full: header + body + footer + buttons)

POST /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...
Content-Type: application/json

{
  "name": "order_confirmation",
  "language": "en",
  "category": "UTILITY",
  "header": { "format": "TEXT", "text": "Order #{{1}} confirmed", "examples": ["12345"] },
  "body": { "text": "Hello {{1}}, your order {{2}} has been confirmed. Estimated delivery is {{3}} business days.", "examples": ["John", "#12345", "3"] },
  "footer": { "text": "Sent via Connexease" },
  "buttons": [
    { "type": "URL", "text": "Track Order", "url": "https://example.com/track/{{1}}", "example": ["https://example.com/track/abc123"] },
    { "type": "PHONE_NUMBER", "text": "Call Us", "phoneNumber": "+905551234567" }
  ]
}

{ "data": { "sourceId": "1029384756124", "name": "order_confirmation", "language": "en", "category": "UTILITY", "status": "PENDING" }, "isSuccess": true }

Demo 3 — MARKETING (coupon / COPY_CODE)

POST /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...
Content-Type: application/json

{
  "name": "promo_coupon",
  "language": "en",
  "category": "MARKETING",
  "body": { "text": "Hey {{1}}, here is your exclusive coupon. Use it at checkout to save big.", "examples": ["John"] },
  "footer": { "text": "Limited time offer" },
  "buttons": [ { "type": "COPY_CODE", "example": ["SAVE25"] } ]
}

{ "data": { "sourceId": "1029384756125", "name": "promo_coupon", "language": "en", "category": "MARKETING", "status": "PENDING" }, "isSuccess": true }

Demo 4 — MARKETING (limited-time offer)

POST /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...
Content-Type: application/json

{
  "name": "flash_sale",
  "language": "en",
  "category": "MARKETING",
  "header": { "format": "IMAGE", "examples": ["4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value"] },
  "body": { "text": "Hi {{1}}, your flash discount is live. Use the code below before it expires.", "examples": ["John"] },
  "limitedTimeOffer": { "text": "Expiring offer!", "hasExpiration": true },
  "buttons": [
    { "type": "COPY_CODE", "example": ["FLASH40"] },
    { "type": "URL", "text": "Shop now", "url": "https://example.com/flash" }
  ]
}

{ "data": { "sourceId": "1029384756128", "name": "flash_sale", "language": "en", "category": "MARKETING", "status": "PENDING" }, "isSuccess": true }

Note that no footer is sent and there are exactly two buttons — both are requirements for a limited-time offer. The image header handle comes from Upload Media.

Demo 5 — error: limited-time offer with a footer → 422

POST /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...
Content-Type: application/json

{
  "name": "flash_sale_footer",
  "language": "en",
  "category": "MARKETING",
  "body": { "text": "Hi {{1}}, your flash discount is live.", "examples": ["John"] },
  "footer": { "text": "Sent via Connexease" },
  "limitedTimeOffer": { "text": "Expiring offer!" }
}

The request is rejected locally, before reaching Meta:

{ "errors": { "code": "WA_TPL_051", "group": "VALIDATION", "description": "Limited-time offer templates do not support a footer." }, "isSuccess": false }

Demo 6 — MARKETING (carousel)

Upload one media file per card first, then send the handles in the cards. Note the empty top level: only body is present, and no header/footer/buttons.

POST /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...
Content-Type: application/json

{
  "name": "summer_catalog",
  "language": "en",
  "category": "MARKETING",
  "body": { "text": "Hi {{1}}, here are this week's picks.", "examples": ["John"] },
  "carousel": [
    {
      "header": { "format": "IMAGE", "examples": ["4::aW1hZ2UvcG5n:ARZ9k1card_one_handle"] },
      "body": { "text": "Linen shirts, now 30% off." },
      "buttons": [ { "type": "URL", "text": "View", "url": "https://example.com/shirts" } ]
    },
    {
      "header": { "format": "IMAGE", "examples": ["4::aW1hZ2UvcG5n:ARZ9k1card_two_handle"] },
      "body": { "text": "Summer dresses from $29." },
      "buttons": [ { "type": "URL", "text": "View", "url": "https://example.com/dresses" } ]
    }
  ]
}

{ "data": { "sourceId": "1029384756129", "name": "summer_catalog", "language": "en", "category": "MARKETING", "status": "PENDING" }, "isSuccess": true }

Both cards use IMAGE headers and a single URL button — the structure must match across every card.

Demo 7 — error: carousel cards with different button sets → 422

{
  "name": "summer_catalog_mixed",
  "language": "en",
  "category": "MARKETING",
  "body": { "text": "Hi {{1}}, here are this week's picks.", "examples": ["John"] },
  "carousel": [
    {
      "header": { "format": "IMAGE", "examples": ["4::aW1hZ2UvcG5n:ARZ9k1card_one_handle"] },
      "body": { "text": "Linen shirts, now 30% off." },
      "buttons": [ { "type": "URL", "text": "View", "url": "https://example.com/shirts" } ]
    },
    {
      "header": { "format": "IMAGE", "examples": ["4::aW1hZ2UvcG5n:ARZ9k1card_two_handle"] },
      "body": { "text": "Summer dresses from $29." },
      "buttons": [ { "type": "QUICK_REPLY", "text": "Notify me" } ]
    }
  ]
}

The second card uses a different button type, so the request is rejected locally:

{ "errors": { "code": "WA_TPL_041", "group": "VALIDATION", "description": "All carousel cards must have the same button types in the same order." }, "isSuccess": false }

Demo 8 — AUTHENTICATION (OTP)

POST /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...
Content-Type: application/json

{
  "name": "login_otp",
  "language": "en",
  "category": "AUTHENTICATION",
  "body": { "addSecurityRecommendation": true },
  "footer": { "codeExpirationMinutes": 10 },
  "buttons": [ { "type": "OTP", "otpType": "COPY_CODE", "text": "Copy code" } ]
}

{ "data": { "sourceId": "1029384756126", "name": "login_otp", "language": "en", "category": "AUTHENTICATION", "status": "PENDING" }, "isSuccess": true }

Demo 9 — error: same name+language already exists → 409

POST /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...
Content-Type: application/json

{ "name": "order_confirmation", "language": "en", "category": "UTILITY", "body": { "text": "Hi {{1}}.", "examples": ["John"] } }

{ "errors": { "code": "META_017", "group": "CONFLICT", "description": "Template creation failed. Details: ..." }, "isSuccess": false }

Errors

object

Error details with code, group, and description; isSuccess is false.

Auth / tenant

HTTP	Code	When
401	`ORGANIZATION_SECRET_010`	Secret key is missing.
401	`ORGANIZATION_SECRET_011`	Secret key is invalid.
404	`APPLICATION_004`	`app_id` does not belong to the organization.

Request validation (before reaching Meta)

Every rule below is checked locally and returns 422 with group VALIDATION; the request never reaches Meta. Button rules

Code	When
`WA_TPL_001`	A `URL` button has no `url`.
`WA_TPL_002`	A `URL` button also carries `phoneNumber`.
`WA_TPL_003`	A `PHONE_NUMBER` button has no `phoneNumber`.
`WA_TPL_004`	A `PHONE_NUMBER` button also carries `url`.
`WA_TPL_005`	A `QUICK_REPLY` button carries `url` or `phoneNumber`.
`WA_TPL_015`	A `URL` / `PHONE_NUMBER` / `QUICK_REPLY` button has no `text`.
`WA_TPL_016`	A `COPY_CODE` button has no `example` (the coupon code).
`WA_TPL_017`	An `OTP` button has no `otpType`.
`WA_TPL_018`	A `ONE_TAP` / `ZERO_TAP` button has no `packageName`.
`WA_TPL_019`	A `ONE_TAP` / `ZERO_TAP` button has no `signatureHash`.
`WA_TPL_020`	A `ZERO_TAP` button does not set `zeroTapTermsAccepted: true`.

Header rules

Code	When
`WA_TPL_006`	A `NONE` header carries `text` or `examples`.
`WA_TPL_007`	A `TEXT` header has no `text`.
`WA_TPL_008`	Header text starts with a variable.
`WA_TPL_009`	Header text ends with a variable.
`WA_TPL_010`	An `IMAGE` / `VIDEO` / `DOCUMENT` header carries `text`.
`WA_TPL_021`	A `LOCATION` header carries `text` or `examples`.

Body rules

Code	When
`WA_TPL_011`	Body text starts with a variable.
`WA_TPL_012`	Body text ends with a variable.
`WA_TPL_013`	The body has variables but no `examples`.
`WA_TPL_014`	The `examples` count does not match the number of variables.

Category rules

Code	When
`WA_TPL_022`	An `AUTHENTICATION` template has a header.
`WA_TPL_023`	An `AUTHENTICATION` body carries `text` (Meta generates it).
`WA_TPL_024`	An `AUTHENTICATION` footer carries `text` instead of `codeExpirationMinutes`.
`WA_TPL_025`	An `AUTHENTICATION` template has a non-`OTP` button.
`WA_TPL_026`	`AUTHENTICATION` TTL is outside 30–900 seconds.
`WA_TPL_027`	A `UTILITY` / `MARKETING` body has no `text`.
`WA_TPL_028`	`addSecurityRecommendation` used outside `AUTHENTICATION`.
`WA_TPL_029`	`codeExpirationMinutes` used outside `AUTHENTICATION`.
`WA_TPL_030`	An `OTP` button used outside `AUTHENTICATION`.
`WA_TPL_031`	A `COPY_CODE` button used outside `MARKETING`.
`WA_TPL_032`	`UTILITY` TTL is outside 30–43200 seconds (30s–12h).
`WA_TPL_033`	`MARKETING` TTL is outside 43200–2592000 seconds (12h–30d).

Name rule

Code	When
`WA_TPL_034`	`name` does not match `^[a-z][a-z0-9_]*$`.

Field-level constraints (about-style max lengths, limit ranges, unknown enum values, a missing required field) are reported by FastAPI as VAL_* validation errors instead.

Carousel validation (before reaching Meta)

Returned only when carousel is present. Each row maps to a rule in the Carousel rules section above.

HTTP	Code	Group	When
422	`WA_TPL_035`	`VALIDATION`	`category` is not `MARKETING`.
422	`WA_TPL_036`	`VALIDATION`	A top-level `header` other than `NONE` was sent.
422	`WA_TPL_037`	`VALIDATION`	A top-level `footer` was sent.
422	`WA_TPL_038`	`VALIDATION`	Top-level `buttons` were sent.
422	`WA_TPL_039`	`VALIDATION`	Fewer than 2 or more than 10 cards.
422	`WA_TPL_040`	`VALIDATION`	Cards mix `IMAGE` and `VIDEO` headers.
422	`WA_TPL_041`	`VALIDATION`	Cards have different button types or a different order.
422	`WA_TPL_042`	`VALIDATION`	A card header is not `IMAGE` or `VIDEO`.
422	`WA_TPL_043`	`VALIDATION`	A card header has no media handle in `examples`.
422	`WA_TPL_044`	`VALIDATION`	A card body has no `text`.
422	`WA_TPL_045`	`VALIDATION`	A card body `text` is longer than 160 chars.
422	`WA_TPL_046`	`VALIDATION`	A card button is not `QUICK_REPLY` / `URL` / `PHONE_NUMBER`.

Limited-time offer validation (before reaching Meta)

Returned only when limitedTimeOffer is present. Each row maps to a rule in the Limited-time offer rules section above.

HTTP	Code	Group	When
422	`WA_TPL_048`	`VALIDATION`	`category` is not `MARKETING`.
422	`WA_TPL_049`	`VALIDATION`	`body.text` is missing or empty.
422	`WA_TPL_050`	`VALIDATION`	`header.format` is not `NONE` / `IMAGE` / `VIDEO`.
422	`WA_TPL_051`	`VALIDATION`	A `footer.text` was sent.
422	`WA_TPL_052`	`VALIDATION`	`carousel` was sent alongside the offer.
422	`WA_TPL_053`	`VALIDATION`	A button is not `COPY_CODE` or `URL`.
422	`WA_TPL_054`	`VALIDATION`	More than one `COPY_CODE` button.
422	`WA_TPL_055`	`VALIDATION`	More than two buttons.

Meta-side

HTTP	Code	When
401	`META_018`	Token invalid/expired (190).
403	`META_019`	Permission denied (10 / 200–299).
429	`META_020`	Rate limit (4 / 80007).
400	`META_021`	Invalid parameter (100, no subcode).
409	`META_017`	Same `name`+`language` already exists (subcode 2388024).
422	`META_022`	Character limit exceeded (2388040).
422	`META_023`	Header format error (2388047).
422	`META_024`	Body format error (2388072).
422	`META_025`	Footer format error (2388073).
422	`META_026`	Too many variables / text ratio (2388293).
422	`META_027`	Variable in first/last position (2388299).
422	`META_028`	WABA migration conflict (2388103).
422	`META_029`	Other policy/validation (unknown 2388xxx).
502	`META_003`	General/fallback creation error.

Getting Started

Analytics

Application

Template

Media

Developers

Reference

What it does

Endpoint

Headers

Path parameters

Request Body

Top-level fields

header object

body object

footer object

buttons object

carousel card object

limitedTimeOffer object

Category rules

Carousel rules

Limited-time offer rules

Response

Examples

Errors

Auth / tenant

Request validation (before reaching Meta)

Carousel validation (before reaching Meta)

Limited-time offer validation (before reaching Meta)

Meta-side

​What it does

​Endpoint

​Headers

​Path parameters

​Request Body

​Top-level fields

​header object

​body object

​footer object

​buttons object

​carousel card object

​limitedTimeOffer object

​Category rules

​Carousel rules

​Limited-time offer rules

​Response

​Examples

​Errors

​Auth / tenant

​Request validation (before reaching Meta)

​Carousel validation (before reaching Meta)

​Limited-time offer validation (before reaching Meta)

​Meta-side

What it does

Endpoint

Headers

Path parameters

Request Body

Top-level fields

header object

body object

footer object

buttons object

carousel card object

limitedTimeOffer object

Category rules

Carousel rules

Limited-time offer rules

Response

Examples

Errors

Auth / tenant

Request validation (before reaching Meta)

Carousel validation (before reaching Meta)

Limited-time offer validation (before reaching Meta)

Meta-side