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 Type	Description	Documentation
Text	Text header, body, footer, and buttons	Text Template Blocks
Image	Image header with text body, footer, and buttons	Image Template Blocks
File / Video	Document or video header with text body, footer, and buttons	File & Video Template Blocks

Rich Templates

These templates use a single composite block with embedded components:

Template Type	Description	Documentation
Carousel	Horizontally scrollable cards (2--10) with images/videos and buttons	Carousel Template Blocks
Catalog	Opens the full WhatsApp product catalog	Catalog Template Blocks
Coupon	Promotional code with a copy-to-clipboard button	Coupon Template Blocks
Flow	Launches an interactive WhatsApp Flow (forms, surveys, bookings)	Flow Template Blocks
Multi-Product	Curated product selection organized into sections	Multi-Product Template Blocks
Limited Time Offer	Time-sensitive promotions with countdown timer	Limited Time Offer Template Blocks

Authentication

Template Type	Description	Documentation
Authentication	OTP/verification codes with one-tap and zero-tap auto-fill	Authentication Template Blocks

---

Block Types Quick Reference

Content blocks

Block type	JSON type value	Used in
Text	text	Standard templates (header, body, footer roles)
Image	image	Standard templates (header role), carousel cards
File	file	Standard templates (header role), carousel cards
Location	location	Session messages (not approved templates)
Authentication body	authentication-body	Authentication templates

Action blocks

Block type	JSON type value	Used in
Link button	link-action	Standard, coupon, limited time offer, carousel cards
Reply button	reply-action	Standard, coupon, carousel cards
Phone number button	call-phone-number-action	Standard, coupon, carousel cards
Copy code button	copy-code-action	Standard (as action), coupon, limited time offer
Open catalog button	open-catalog-action	Catalog templates
Multi-product button	multi-product-action	Multi-product templates
Flow button	whatsapp-flow-action	Flow templates
Authentication button	authentication-action	Authentication templates

Composite blocks

Block type	JSON type value	Description
Carousel	whatsapp-carousel	Container for carousel cards
Carousel card	whatsapp-carousel-card	Individual card in a carousel
Catalog	whatsapp-catalog	Catalog message with open-catalog action
Coupon	whatsapp-coupon	Coupon message with copy-code action
Flow	whatsapp-flow	Flow message with flow-action button
Multi-product	whatsapp-multi-product	Multi-product message with product sections
Limited time offer	whatsapp-limited-time-offer	Time-limited offer with countdown
Product item	whatsapp-product-item	Single product reference
Product section	whatsapp-product-section	Group of products with a title
Limited time offer component	limited-time-offer	Offer text and expiration within LTO template

---

Common Deployments

All WhatsApp templates require these deployments in the template definition:

"deployments": [
  {
    "key": "whatsappTemplateName",
    "platform": "whatsapp",
    "value": "your_template_name"
  },
  {
    "key": "whatsappCategory",
    "platform": "whatsapp",
    "value": "MARKETING"
  },
  {
    "key": "whatsappAllowCategoryChange",
    "platform": "whatsapp",
    "value": "true"
  }
]

Key	Description
whatsappTemplateName	Template name registered with Meta (lowercase, underscores only)
whatsappCategory	Template category: MARKETING or UTILITY. The AUTHENTICATION category can only be used with Authentication Template Blocks.
whatsappAllowCategoryChange	Always 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.

{
  "id": "34dcb086-82c7-47f2-8939-7f0057def64e",
  "name": "seasonal_promo",
  "status": "active",
  "platformInfo": {
    "whatsapp:[phone]: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"]
        }
      ]
    }
  ]
}

Field	Description
status	Overall template status: draft, pending, active, inactive, or pendingReview
platformInfo	Per-WABA/locale status, keyed as whatsapp:{wabaId}:{locale}
platformInfo.status	Simplified status: active, inactive, or pending
platformInfo.category	Category assigned by Meta (may differ from your request if Meta re-categorized)
platformInfo.qualityRating	Quality rating: GREEN, YELLOW, RED, or UNKNOWN
platformContent[].approvals[].platformStatus	Detailed 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

• Creating WhatsApp Message Templates -- Full template creation workflow (project, channel group, template, activation)

• WhatsApp Template Webhooks -- Real-time notifications for template status changes, quality ratings, and rejection reasons

• WhatsApp Template Status Lifecycle -- How templates move through draft, pending, active, flagged, paused, and disabled states

• Sending WhatsApp Messages -- Using approved templates to send messages