Marketing Template Types (Carousel, Coupon, Catalog & More)

Marketing templates are the templates you use for promotions: sales, offers, new products, announcements and bringing customers back. Meta describes them as templates "used to drive engagement, brand awareness, and sales." They are also the only template type that can be sent through both the Cloud API and the Marketing Messages API for WhatsApp.

Most marketing templates are custom templates: you choose a header, write the body and add buttons. For some goals Meta offers special formats with their own layout, such as a swipeable carousel, a one-tap coupon code or a countdown timer. Each format has its own rules.

At a glance#

Custom marketing templates#

The standard, flexible option. A custom marketing template can have:

• 1 header (optional; any header type)
• 1 body (required)
• 1 footer (optional)
• up to 10 buttons (optional; any button type)

For the general component limits and how variables work, see Message Templates: Parts, Limits & Categories.

Coupon code templates#

A marketing template with a single copy code button. When the customer taps it, WhatsApp copies the coupon code to their clipboard, ready to paste at checkout.

• Only one copy code button per template.
• The copy code button text can't be customized.
• The coupon code is up to 20 characters. You give an example code when you create the template and the real code when you send it.
• Coupon code templates are not currently supported on WhatsApp Web.

Limited-time offer templates#

Shows an offer with an expiration date and a running countdown timer, plus the offer code. The timer text is not customizable, and it turns red if the customer views the message when the code expires within the next hour.

• Only for templates categorized as MARKETING.
• No footer allowed.
• Offer text (the heading, such as "Expiring offer!") is up to 16 characters. The offer code is up to 15 characters. Body text is up to 600 characters.
• You set the actual expiry time when you send the message, not when you create the template.
• Customers who open it on WhatsApp Web or desktop don't see the offer. They see a note that they received a message whose limited-time offer isn't supported there.

Carousel templates#

A carousel is one message with a row of cards the customer swipes sideways. There are two kinds:

In both kinds, all cards on a template must have the same components. In a media card carousel, if one card has body text, every card must have body text. The main message text above the cards can be up to 1024 characters.

Catalog-based templates#

These need an e-commerce product catalog, with inventory, connected to your WhatsApp Business account.

• Catalog template: shows a product thumbnail header image (you choose the product, or the first item in your catalog is used), your body text, and a fixed header and sub-header. Tapping View catalog opens your whole catalog inside WhatsApp.
• Multi-product message (MPM) template: up to 30 products, organized in up to 10 sections, in one message. Customers browse, add items to a cart and submit an order, and you get each order by webhook. Customers need WhatsApp v2.22.24 or later, and these messages can't be forwarded.
• Single-product message (SPM) template: one product with its image, title and price (pulled from your catalog), your own body text, an optional footer and a View button. Customers can add it to the cart and order, and you get the order by webhook. Customers need WhatsApp v2.22.24 or later, and forwarding is disabled.

Call permission request templates#

Ask a customer for permission to call them, so your business can call outside the customer service window. The customer can grant or deny it.

• Can be categorized as MARKETING or UTILITY.
• Body text is required and can't be empty.
• Can't be combined with other interactive components.

Rules that apply to every marketing template#

• Per-user marketing limit: WhatsApp limits how many marketing templates one person gets from businesses. Messages held back fail with error 131049. See Per-User Marketing Limit.
• Customers can stop your marketing: WhatsApp's Offers and announcements setting lets a customer stop or resume marketing messages from your business. If they've stopped, your message isn't sent. The status webhook shows failed with code 131050. Subscribe to the user_preferences webhook to hear about stops and resumes. A customer can also tap Not interested, which can affect the per-user limit (but doesn't trigger the webhook).
• No US numbers: WhatsApp does not currently deliver marketing templates to US phone numbers (+1 with a US area code).
• Opt-in still applies: only message people who have agreed to hear from you. See Opt-in rules.
• Content decides the category: anything promotional is marketing, even inside an order update. See Utility templates.
• Price: marketing messages are charged per delivered message at the marketing rate for the recipient's country. They are free only inside a free entry point window. Volume tiers (lower rates at high volume) apply to utility and authentication, not marketing. See Message Categories & Pricing.

Technical details#

Every type is created with POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates using "category": "marketing". What makes each type special is its components.

Coupon code button#

{
  "type": "buttons",
  "buttons": [
    { "type": "QUICK_REPLY", "text": "Unsubscribe" },
    { "type": "COPY_CODE", "example": "WINTER25" }
  ]
}

When sending, you pass the real code (up to 20 characters) in the copy code button component. index is the button's position on the template, starting at 0 (here the copy code button is second, so 1):

{
  "type": "button",
  "sub_type": "copy_code",
  "index": 1,
  "parameters": [
    { "type": "coupon_code", "coupon_code": "WINTER25" }
  ]
}

Limited-time offer component#

{
  "name": "limited_time_offer_caribbean_pkg_2023",
  "language": "en_US",
  "category": "marketing",
  "components": [
    { "type": "header", "format": "image", "example": { "header_handle": ["4::aW..."] } },
    {
      "type": "limited_time_offer",
      "limited_time_offer": { "text": "Expiring offer!", "has_expiration": true }
    },
    {
      "type": "body",
      "text": "Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!",
      "example": { "body_text": [["Pablo", "CARIBE25"]] }
    },
    {
      "type": "buttons",
      "buttons": [
        { "type": "copy_code", "example": "CARIBE25" },
        {
          "type": "url",
          "text": "Book now!",
          "url": "https://awesomedestinations.com/offers?code={{1}}",
          "example": ["https://awesomedestinations.com/offers?ref=n3mtql"]
        }
      ]
    }
  ]
}

has_expiration: true shows the expiry section in the delivered message. When you send it, the limited_time_offer component carries expiration_time_ms, the code's expiry as a UNIX timestamp in milliseconds.

Carousels#

Media card carousel templates use a carousel component with a cards array. Each card has its own image or video header, optional body and buttons. The number of cards you define is the number you must send. Product card carousels define two cards at creation and can send up to 10 product cards. The product details come from your catalog.

Frequently asked#

Gotchas & common mistakes#