DocumentazioneEngagement Platform API
Sign inGet started
Guides
API

WhatsApp Template Blocks Reference

This page provides an overview of all block types available for WhatsApp approved message templates. Each template type has its own detailed documentation page with examples, constraints, and complete API payloads.

Template Types

WhatsApp templates are built from blocks that define the message structure. There are 10 supported template types:

Standard Templates

These templates use a combination of header, body, footer, and button blocks:
Template TypeDescriptionDocumentation
TextText header, body, footer, and buttonsText Template Blocks
ImageImage header with text body, footer, and buttonsImage Template Blocks
File / VideoDocument, video, or animated GIF header with text body, footer, and buttonsFile & Video Template Blocks

Rich Templates

These templates use a single composite block with embedded components:
Template TypeDescriptionDocumentation
CarouselHorizontally scrollable cards (2--10) with images/videos and buttonsCarousel Template Blocks
CatalogOpens the full WhatsApp product catalogCatalog Template Blocks
CouponPromotional code with a copy-to-clipboard buttonCoupon Template Blocks
FlowLaunches an interactive WhatsApp Flow (forms, surveys, bookings)Flow Template Blocks
Multi-ProductCurated product selection organized into sectionsMulti-Product Template Blocks
Limited Time OfferTime-sensitive promotions with countdown timerLimited Time Offer Template Blocks

Authentication

Template TypeDescriptionDocumentation
AuthenticationOTP/verification codes with one-tap and zero-tap auto-fillAuthentication Template Blocks

Block Types Quick Reference

Content blocks

Block typeJSON type valueUsed in
TexttextStandard templates (header, body, footer roles)
ImageimageStandard templates (header role), carousel cards
FilefileStandard templates (header role), carousel cards. Set isAnimated: true for an animated GIF header
LocationlocationSession messages (not approved templates)
Authentication bodyauthentication-bodyAuthentication templates

Action blocks

Block typeJSON type valueUsed in
Link buttonlink-actionStandard, coupon, limited time offer, carousel cards
Reply buttonreply-actionStandard, coupon, carousel cards
Phone number buttoncall-phone-number-actionStandard, coupon, carousel cards
Copy code buttoncopy-code-actionStandard (as action), coupon, limited time offer
Open catalog buttonopen-catalog-actionCatalog templates
Multi-product buttonmulti-product-actionMulti-product templates
Flow buttonwhatsapp-flow-actionFlow templates
Authentication buttonauthentication-actionAuthentication templates

Composite blocks

Block typeJSON type valueDescription
Carouselwhatsapp-carouselContainer for carousel cards
Carousel cardwhatsapp-carousel-cardIndividual card in a carousel
Catalogwhatsapp-catalogCatalog message with open-catalog action
Couponwhatsapp-couponCoupon message with copy-code action
Flowwhatsapp-flowFlow message with flow-action button
Multi-productwhatsapp-multi-productMulti-product message with product sections
Limited time offerwhatsapp-limited-time-offerTime-limited offer with countdown
Product itemwhatsapp-product-itemSingle product reference
Product sectionwhatsapp-product-sectionGroup of products with a title
Limited time offer componentlimited-time-offerOffer text and expiration within LTO template

Common Deployments

All WhatsApp templates require these deployments in the template definition:
Esempio di codice
"deployments": [
  {
    "key": "whatsappTemplateName",
    "platform": "whatsapp",
    "value": "your_template_name"
  },
  {
    "key": "whatsappCategory",
    "platform": "whatsapp",
    "value": "MARKETING"
  },
  {
    "key": "whatsappAllowCategoryChange",
    "platform": "whatsapp",
    "value": "true"
  }
]
KeyDescription
whatsappTemplateNameTemplate name registered with Meta (lowercase, underscores only)
whatsappCategoryTemplate category: MARKETING or UTILITY. The AUTHENTICATION category can only be used with Authentication Template Blocks.
whatsappAllowCategoryChangeAlways set to "true". Meta enforces category changes regardless of this value. Still required by the API but may be deprecated in a future release.

Template Status and platformInfo

After a template is created and activated, the API response includes status and platformInfo fields that track the template's approval state across each WABA and locale.
Esempio di codice
{
  "id": "34dcb086-82c7-47f2-8939-7f0057def64e",
  "name": "seasonal_promo",
  "status": "active",
  "platformInfo": {
    "whatsapp:114128184961630:en": {
      "status": "active",
      "category": "MARKETING",
      "qualityRating": "GREEN"
    }
  },
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "seasonal_promo"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "platform": "whatsapp",
      "approvals": [
        {
          "approvalReference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "platformAccountIdentifier": "114128184961630",
          "platform": "whatsapp",
          "status": "approved",
          "platformStatus": "whatsapp_approved",
          "reasonCode": null,
          "reasonDescription": null,
          "channelIds": ["c1d2e3f4-a5b6-7890-cdef-123456789abc"]
        }
      ]
    }
  ]
}
FieldDescription
statusOverall template status: draft, pending, active, inactive, or pendingReview
platformInfoPer-WABA/locale status, keyed as whatsapp:{wabaId}:{locale}
platformInfo.statusSimplified status: active, inactive, or pending
platformInfo.categoryCategory assigned by Meta (may differ from your request if Meta re-categorized)
platformInfo.qualityRatingQuality rating: GREEN, YELLOW, RED, or UNKNOWN
platformContent[].approvals[].platformStatusDetailed Meta status: whatsapp_approved, whatsapp_flagged, whatsapp_rejected, whatsapp_paused, whatsapp_disabled, whatsapp_in_appeal, or whatsapp_reinstated
A top-level status of active does not mean all WABAs/locales are healthy -- individual platformInfo entries may be inactive while others remain active. Always check individual entries.
For the full status lifecycle -- including how templates move between draft, pending, active, flagged, paused, disabled, and reinstated states -- see WhatsApp Template Status Lifecycle. To receive real-time notifications when template status or quality changes, see WhatsApp Template Webhooks.

Template Combination Rules

WhatsApp enforces strict rules about which blocks can be combined:
  1. Standard templates (text/image/file) use individual blocks: one optional header, one required body, one optional footer, and up to 10 buttons.
  2. Rich templates (carousel, catalog, coupon, flow, multi-product, limited time offer) use a single composite block that contains all components internally.
  3. Authentication templates use exactly two blocks: authentication-body and authentication-action.
  4. You cannot mix block types from different template categories (e.g., you cannot put a carousel block and a text body block in the same template).

Related