# 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: ```json "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. ```json { "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"] } ] } ] } ``` | 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` | {% hint style="info" %} 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. {% endhint %} 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](https://docs.bird.com/api/touchpoints-api/supported-projects/whatsapp-approved-message-templates/creating-whatsapp-message-templates) -- Full template creation workflow (project, channel group, template, activation) * [WhatsApp Template Webhooks](/api/touchpoints-api/supported-projects/whatsapp-approved-message-templates/whatsapp-template-webhooks.md) -- Real-time notifications for template status changes, quality ratings, and rejection reasons * [WhatsApp Template Status Lifecycle](/api/touchpoints-api/supported-projects/whatsapp-approved-message-templates/whatsapp-template-webhooks.md#whatsapp-template-lifecycle-events) -- How templates move through draft, pending, active, flagged, paused, and disabled states * [Sending WhatsApp Messages](https://docs.bird.com/api/channels-api/supported-channels/programmable-whatsapp/sending-whatsapp-messages) -- Using approved templates to send messages --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/touchpoints-api/supported-projects/whatsapp-approved-message-templates/creating-whatsapp-message-templates/whatsapp-template-blocks-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.