Update Template

What it does

Edits the content (components) of an existing template. On Meta the edit is full-replace: the component set you send becomes the new state, and any component you don’t send is removed. After a successful edit the status returns to PENDING (re-review) and the local DB is synced. name and language cannot be changed. The response body is controlled via Prefer. Internally, the template’s current category is first fetched from Meta (for auth / standard component structure), then the edit is submitted.

Template update = PUT semantics: always send the full component set, or missing components are deleted (or you get a 409).

Golden rule: to preserve existing components, send the full set. Sending only body drops the other components and is rejected (see Demo 7). Editing is allowed only when the template is APPROVED, REJECTED, or PAUSED.

Endpoint

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

Headers

string

required

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

string

required

Always application/json.

string

return=representation (default) returns the updated template; return=minimal returns no body. The applied preference is reported via the Preference-Applied header.

Path parameters

string

required

Application ID.

string

required

The template’s Meta ID.

Request Body

name and language cannot be sent. The inner objects (header / body / footer / buttons) use the same schema as Create Template. Full-replace: send every component you want to keep (at minimum body).

object

required

Body component. Must always be sent (structurally required).

object | null

Header component (send it if you want to keep it).

object | null

Footer component.

array | null

Buttons (max 10).

integer | null

Message time-to-live.

object | null

Limited-time offer component (text, hasExpiration) — same schema as Create Template. Because editing is full-replace, an existing offer is removed if you do not send it again.

string | null

Category change: UTILITY, MARKETING, or AUTHENTICATION. Effective only for REJECTED/PAUSED; for APPROVED Meta rejects it; subject to review. See Template Category.

Limited-time offer on edit — the same rules as on create apply here: body.text is required, header.format is limited to NONE / IMAGE / VIDEO, footer.text cannot be sent, and there may be at most two buttons, each COPY_CODE or URL with only one COPY_CODE. See Limited-time offer rules. The MARKETING check runs only when you also send a category; if you omit it, Meta validates the offer against the template’s existing category. (carousel is not accepted on edit at all, so that rule never applies here.)

Response

With Prefer: return=representation (default), the response is { "data": {...}, "isSuccess": true } — the full template re-fetched from Meta after the edit (with components), status: "PENDING". With return=minimal, it is { "isSuccess": true }.

boolean

true when the update was accepted.

object | null

The updated template — the same fields as Get Template Detail: sourceId, name, language, category, status (PENDING right after a successful edit), components, qualityScore, rejectedReason, parameterFormat. components has the same shape as in Get Template Detail. With Prefer: return=minimal the key is omitted from the envelope altogether — the response is exactly { "isSuccess": true }, still with HTTP 200.

Examples

Demo 1 — full update (representation)

POST /api/v1/wa/{app_id}/templates/842802041844912
Authorization: Bearer sk_...
Prefer: return=representation
Content-Type: application/json

{
  "header": { "format": "TEXT", "text": "Order #{{1}} update", "examples": ["12345"] },
  "body": { "text": "Hi {{1}}, your order {{2}} is now {{3}}. Thank you.", "examples": ["John", "#12345", "shipped"] },
  "footer": { "text": "Connexease" },
  "buttons": [ { "type": "QUICK_REPLY", "text": "Track" } ]
}

{
  "data": {
    "sourceId": "842802041844912",
    "name": "order_confirmation",
    "language": "en",
    "category": "UTILITY",
    "status": "PENDING",
    "components": [
      { "type": "HEADER", "format": "TEXT", "text": "Order #{{1}} update", "example": { "headerText": ["12345"] } },
      { "type": "BODY", "text": "Hi {{1}}, your order {{2}} is now {{3}}. Thank you.", "example": { "bodyText": [["John", "#12345", "shipped"]] } },
      { "type": "FOOTER", "text": "Connexease" },
      { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Track" } ] }
    ],
    "qualityScore": "UNKNOWN",
    "rejectedReason": "NONE",
    "parameterFormat": "POSITIONAL"
  },
  "isSuccess": true
}

Demo 2 — minimal (Prefer: return=minimal)

POST /api/v1/wa/{app_id}/templates/842802041844912
Authorization: Bearer sk_...
Prefer: return=minimal
Content-Type: application/json

{
  "header": { "format": "TEXT", "text": "Order #{{1}} update", "examples": ["12345"] },
  "body": { "text": "Hi {{1}}, your order {{2}} is now {{3}}. Thank you.", "examples": ["John", "#12345", "shipped"] },
  "footer": { "text": "Connexease" },
  "buttons": [ { "type": "QUICK_REPLY", "text": "Track" } ]
}

Still HTTP 200; data is omitted entirely rather than sent as null:

{ "isSuccess": true }

Demo 3 — change category (REJECTED/PAUSED)

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

{ "category": "UTILITY", "body": { "text": "Hi {{1}}, your order {{2}} has been received. We'll update you soon.", "examples": ["John", "#12345"] } }

{
  "data": { "sourceId": "1234567890", "name": "promo_blast", "language": "en", "category": "MARKETING", "status": "PENDING", "qualityScore": "UNKNOWN", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" },
  "isSuccess": true
}

Demo 4 — edit a limited-time offer (re-send the offer to keep it)

POST /api/v1/wa/{app_id}/templates/842802041844912
Authorization: Bearer sk_...
Prefer: return=representation
Content-Type: application/json

{
  "header": { "format": "IMAGE", "examples": ["4::aW1hZ2UvcG5n:ARZ9k1sample_handle_value"] },
  "body": { "text": "Hi {{1}}, the flash discount is back with a bigger saving.", "examples": ["John"] },
  "limitedTimeOffer": { "text": "Ends tonight!", "hasExpiration": true },
  "buttons": [
    { "type": "COPY_CODE", "example": ["FLASH50"] },
    { "type": "URL", "text": "Shop now", "url": "https://example.com/flash" }
  ]
}

{
  "data": {
    "sourceId": "842802041844912",
    "name": "flash_sale",
    "language": "en",
    "category": "MARKETING",
    "status": "PENDING",
    "qualityScore": "UNKNOWN",
    "rejectedReason": "NONE",
    "parameterFormat": "POSITIONAL"
  },
  "isSuccess": true
}

Dropping limitedTimeOffer from this payload would remove the offer from the template — full-replace applies to it exactly as it does to the other components.

Demo 5 — error: non-editable status (template PENDING) → 409

{
  "errors": { "code": "META_096", "group": "CONFLICT", "description": "Template update failed. Template is not in an editable status (editable only when APPROVED, REJECTED or PAUSED; it may be PENDING after a recent edit)." },
  "isSuccess": false
}

Demo 6 — error: 24h edit limit → 429

{
  "errors": { "code": "META_097", "group": "LIMIT_EXCEEDED", "description": "Template update failed. Details: You can only edit an active template once in 24 hours." },
  "isSuccess": false
}

Demo 7 — error: sending only body and breaking structure → 409

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

{ "body": { "text": "Hello {{1}}, your order {{2}} has been confirmed.", "examples": ["John", "#12345"] } }

{
  "errors": { "code": "META_096", "group": "CONFLICT", "description": "Template update failed. Details: The status for this message template can't be changed. You can only delete or add templates." },
  "isSuccess": false
}

Errors

object

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

Auth / tenant

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

Pre-fetch (while fetching the current template)

HTTP	Code	When
404	`META_075`	`source_id` not found.
401	`META_034`	Token invalid during fetch (190).
403	`META_035`	Fetch permission denied.
429	`META_036`	Fetch rate limit.
502	`META_004`	General fetch error.

Request validation (422)

The button, header, and body rules are identical to Create Template: WA_TPL_001–WA_TPL_005 and WA_TPL_015–WA_TPL_020 (buttons), WA_TPL_006–WA_TPL_010 and WA_TPL_021 (header), WA_TPL_011–WA_TPL_014 (body).

The category rules (WA_TPL_022–WA_TPL_033) and the name rule (WA_TPL_034) are not evaluated here: name cannot be sent, and the category-vs-component compatibility check only runs on create. Meta still enforces the equivalent rules on its side, so a category-incompatible edit comes back as a META_0xx error instead of a WA_TPL_0xx one.

HTTP	When
422	A button / header / body rule above, or an invalid `category` enum value.

Limited-time offer validation (422)

Returned only when limitedTimeOffer is present.

HTTP	Code	Group	When
422	`WA_TPL_048`	`VALIDATION`	A `category` was sent and it 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_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.

Update

HTTP	Code	When (Meta)
401	`META_092`	Token invalid (190).
403	`META_093`	Permission denied (10 / 200–299).
429	`META_094`	Rate limit (4 / 80007).
400	`META_095`	Invalid parameter (100, no subcode).
409	`META_096`	Non-editable status (2388003) / structural rejection (2388039).
429	`META_097`	24h edit limit (2388124).
409	`META_017`	Same name+language conflict (2388024).
422	`META_022`	Character limit (2388040).
422	`META_023`	Header format (2388047).
422	`META_024`	Body format (2388072).
422	`META_025`	Footer format (2388073).
422	`META_026`	Variable / text ratio (2388293).
422	`META_027`	Variable in first/last position (2388299).
422	`META_028`	WABA migration (2388103).
422	`META_029`	Other policy/validation (unknown 2388xxx).
502	`META_091`	General/fallback (or Meta `success:false`).

Getting Started

Analytics

Application

Template

Media

Developers

Reference

What it does

Endpoint

Headers

Path parameters

Request Body

Response

Examples

Errors

Auth / tenant

Pre-fetch (while fetching the current template)

Request validation (422)

Limited-time offer validation (422)

Update

​What it does

​Endpoint

​Headers

​Path parameters

​Request Body

​Response

​Examples

​Errors

​Auth / tenant

​Pre-fetch (while fetching the current template)

​Request validation (422)

​Limited-time offer validation (422)

​Update

What it does

Endpoint

Headers

Path parameters

Request Body

Response

Examples

Errors

Auth / tenant

Pre-fetch (while fetching the current template)

Request validation (422)

Limited-time offer validation (422)

Update