Create Template

What it does

Creates a new WhatsApp message template and submits it to Meta for approval. On success the Meta ID is returned and the template is written through to the local DB (best-effort; the request does not fail even if the DB write fails). A newly created template’s status is usually PENDING.

Endpoint

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

There are no query parameters.

Headers

Authorization

string

required

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

Content-Type

string

required

Always application/json.

Path parameters

app_id

string

required

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

Request Body

Top-level fields

name

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.

language

string

required

Language code (BCP-47), e.g. tr, en, en_US.

header object

format

string

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

text

string

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

examples

string | string[]

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

body object

text

string

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

examples

string[]

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

addSecurityRecommendation

boolean

AUTHENTICATION only; adds the security recommendation text.

text

string

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

codeExpirationMinutes

integer

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

buttons object

Each item in the buttons array:

type

string

One of QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, OTP.

text

string

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

url

string

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

phoneNumber

string

PHONE_NUMBER type phone in E.164 format.

example

string[]

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

otpType

string

For OTP: one of COPY_CODE, ONE_TAP, ZERO_TAP.

autofillText

string

ONE_TAP / ZERO_TAP autofill text (max 25 chars).

packageName

string

ONE_TAP / ZERO_TAP Android package name.

signatureHash

string

ONE_TAP / ZERO_TAP signature hash.

zeroTapTermsAccepted

boolean

ZERO_TAP terms acceptance.

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.

Response

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

isSuccess

boolean

true when the template was created and submitted.

data

object

Show data

sourceId

string

The template’s Meta ID.

name

string

Template name.

language

string

Language code.

Examples

Demo 1 — UTILITY (lean)

POST /public/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 /public/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 /public/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 — AUTHENTICATION (OTP)

POST /public/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 5 — error: same name+language already exists → 409

POST /public/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

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, 422)

HTTP	When
422	Invalid `name` pattern, body starts/ends with a variable, examples count mismatch, category-component rule violation (e.g. header in AUTH), button rule violation, `messageSendTtlSeconds` out of range.

Meta-side (`create_template_async`)

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

What it does

Endpoint

Headers

Path parameters

Request Body

Top-level fields

header object

body object

footer object

buttons object

Category rules

Response

Examples

Errors

Auth / tenant

Request validation (before reaching Meta, 422)

Meta-side (`create_template_async`)

​What it does

​Endpoint

​Headers

​Path parameters

​Request Body

​Top-level fields

​header object

​body object

​footer object

​buttons object

​Category rules

​Response

​Examples

​Errors

​Auth / tenant

​Request validation (before reaching Meta, 422)

​Meta-side (create_template_async)

What it does

Endpoint

Headers

Path parameters

Request Body

Top-level fields

header object

body object

footer object

buttons object

Category rules

Response

Examples

Errors

Auth / tenant

Request validation (before reaching Meta, 422)

Meta-side (`create_template_async`)