Skip to content

Templates

Message templates are pre-approved formats you can send at any time, including outside the 24-hour window.

The template object

JSON
{
  "id": "3c7d…",
  "messaging_account_id": "5b8e…",
  "name": "order_shipped",
  "language": "en",
  "category": "UTILITY",
  "sub_category": null,
  "previous_category": null,
  "status": "APPROVED",
  "rejected_reason": null,
  "quality_score": "GREEN",
  "parameter_format": "POSITIONAL",
  "meta_template_id": "1234567890",
  "message_send_ttl_seconds": null,
  "components": [
    { "type": "HEADER", "format": "IMAGE", "example": { "header_handle": ["https://…"] } },
    { "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped!",
      "example": { "body_text": [["Jane", "#48213"]] } },
    { "type": "FOOTER", "text": "Example Store" },
    { "type": "BUTTONS", "buttons": [
      { "type": "URL", "text": "Track order", "url": "https://example.com/t/{{1}}", "example": ["https://example.com/t/48213"] }
    ] }
  ],
  "created_at": "2026-11-10T08:15:00Z",
  "updated_at": "2026-11-11T10:42:00Z"
}

components uses Meta's template component schema, so anything you build in Engage maps 1:1 to WhatsApp Manager. The list returns { "data": [...] } (up to 1,000 templates, no cursor); deleted templates are hidden. Keys with messages:send can also list templates.

Creating a template

Body parameters
  • namestringrequired
    Lowercase letters, numbers and underscores; up to 512 characters.
  • languagestringrequired
    Locale code such as en, en_US, hi (up to 10 characters).
  • categoryenumrequired
    MARKETING · UTILITY · AUTHENTICATION
  • parameter_formatenumoptional
    POSITIONAL ({{1}}, the default) or NAMED ({{first_name}}).
  • componentsarrayrequired
    Header, body, footer, buttons, carousel components with examples.
  • submitbooleanoptional
    Submit to Meta for review now (default true). false saves a draft.
  • messaging_account_iduuidoptional
    Which WhatsApp Business Account to create it in, if you have more than one.
  • allow_category_changebooleanoptional
    Let Meta re-categorise the template instead of rejecting it.
  • message_send_ttl_secondsintegeroptional
    How long WhatsApp keeps trying to deliver messages using this template.

Creating a template with a name and language that already exist on the account updates that template. The response is 201 with the template object.

Media header samples

Templates with an IMAGE, VIDEO or DOCUMENT header need an example file. Upload it with POST /v1/templates/upload-sample (multipart file: JPEG/PNG up to 5 MB, MP4 up to 16 MB, PDF up to 100 MB) and put the returned handle in the header's example.header_handle.

Editing and deleting

  • PATCH accepts components, category, message_send_ttl_seconds and submit (default true, so patching a draft submits it).
  • Once a template is on Meta, only APPROVED, REJECTED or PAUSED templates can be edited; the template goes back to PENDING for review.
  • DELETE removes the template on Meta too. It is refused with 422 while a scheduled or sending campaign uses it.

Limits

ComponentLimit
Header text60 characters, at most 1 variable
Body1,024 characters; variables need sample values and can't be adjacent or at the very start/end
Footer60 characters, no variables
ButtonsUp to 10 total; up to 2 URL buttons, 1 phone number, 1 copy code
Quick-reply button text25 characters
CarouselUp to 10 cards with the same structure (checked by Meta)
Coupon codeUp to 20 characters (checked by Meta)

Statuses

StatusMeaning
DRAFTSaved in Engage, not yet submitted
PENDINGIn Meta review — usually minutes, up to 24 hours
APPROVEDReady to send
REJECTEDSee rejected_reason; edit and resubmit
PAUSEDPaused by Meta for low quality; resumes automatically or after edits
DISABLEDDisabled by Meta after repeated quality issues
IN_APPEALYou appealed a rejection; Meta is reviewing it
ARCHIVEDArchived in WhatsApp Manager
Subscribe to the template.status webhook to be notified when Meta approves, rejects or pauses a template, and template.quality for quality changes.
Something unclear or missing on this page? Tell us at contact@swastik.ai