Limited-Time Offer Templates

This document describes limited-time offer templates and how to use them.

Limited-time offer templates allow you to display expiration dates and running countdown timers for offer codes in template messages, making it easy for you to communicate time-bound offers and drive customer engagement.

Limitations

Only templates categorized as MARKETING are supported.
Footer components are not supported.
Users who view a limited-time offer template message using that WhatsApp web app or desktop app will not see the offer, but will instead see a message indicating that they have received a message but that it's not supported in the client they are using.

Creating Limited-Time Offer Templates

Use the WhatsApp Business Account > Message Templates endpoint to create a limited-time offer template.

Request Syntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/messages_templates

Post Body

{
  "name": "<TEMPLATE_NAME>",
  "language": "<TEMPLATE_LANGUAGE>",
  "category": "marketing",
  "components": [

    /* Header component optional */
    {
      "type": "header",
      "format": "<HEADER_FORMAT>",
      "example": {
        "header_handle": [
          "<HEADER_ASSET_HANDLE>"
        ]
      }
    },

    /* Limited-time offer component required */
    {
      "type": "limited_time_offer",
      "limited_time_offer": {
        "text": "<LIMITED_TIME_OFFER_TEXT>",
        "has_expiration": <HAS_EXPIRATION>
      }
    },

    /* Body component required */
    {
      "type": "body",
      "text": "<BODY_TEXT>",
      "example": {
        "body_text": [<BODY_TEXT_VARIABLE_EXAMPLES>]
      }
    },

    /* Copy code button component optional */
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "copy_code",
          "example": "<OFFER_CODE_EXAMPLE>"
        },
        {
          "type": "url",
          "text": "<URL_BUTTON_TEXT>",
          "url": "<URL_BUTTON_URL>",
          "example": [
            "<URL_EXAMPLE_WITH_VARIABLE_EXAMPLE>"
          ]
        }
      ]
    }
  ]
}

Body Properties

Placeholder Description Example Value

Placeholder	Description	Example Value
`<BODY_TEXT>` String	Required. Body component text. Supports variables. Maximum 600 characters.	`Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!`
`<BODY_TEXT_VARIABLE_EXAMPLES>` Array of strings	Required if body component text uses variables. Array of example variable strings. Must supply examples for all placeholders in `<BODY_TEXT>` string. No maximum, but counts against `<BODY_TEXT>` maximum.	`["Pablo","CARIBE25"]`
`<HAS_EXPIRATION>` Boolean	Optional. Set to `true` to have the offer expiration details appear in the delivered message.	`true`
`<HEADER_ASSET_HANDLE>` Media asset handle	Required if using an image or video header. Uploaded media asset handle. Use the Resumable Upload API to generate an asset handle.	`4::aW...`
`<HEADER_FORMAT>` Enum	Required if using a header. Can be `IMAGE`, or `VIDEO`.	`IMAGE`
`<LIMITED_TIME_OFFER_TEXT>` String	Required. Offer details text. Maximum 16 characters.	`Expiring offer!`
`<OFFER_CODE_EXAMPLE>` String	Required. Example offer code. Maximum 15 characters.	`CARIBE25`
`<TEMPLATE_LANGUAGE>` Enum	Required. Template language and locale code.	`en_US`
`<TEMPLATE_NAME>` String	Required. Template name. Maximum 512 characters.	`limited_time_offer_caribbean_pkg_2023`
`<URL_BUTTON_TEXT>` String	Required. URL button label text. Supports 1 variable. 25 characters maximum.	`Book now!`
`<URL_BUTTON_URL>` String	Required. URL of website that loads in the device's default mobile web browser when the URL button is tapped by the WhatsApp user. Supports 1 variable appended to the end of the URL string. Maximum 2000 characters.	`https://awesomedestinations.com/offers?code={{1}}`
`<URL_EXAMPLE_WITH_VARIABLE_EXAMPLE>` String	Required if URL uses a variable. Example URL with example variable appended to the end. No maximum, but value counts against `<URL_BUTTON_URL>` maximum.	`https://awesomedestinations.com/offers?ref=n3mtql`

<BODY_TEXT>

String

Required.

Body component text. Supports variables.

Maximum 600 characters.

Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!

<BODY_TEXT_VARIABLE_EXAMPLES>

Array of strings

Required if body component text uses variables.

Array of example variable strings.

Must supply examples for all placeholders in <BODY_TEXT> string.

No maximum, but counts against <BODY_TEXT> maximum.

["Pablo","CARIBE25"]

<HAS_EXPIRATION>

Boolean

Optional.

Set to true to have the offer expiration details appear in the delivered message.

true

<HEADER_ASSET_HANDLE>

Media asset handle

Required if using an image or video header.

Uploaded media asset handle. Use the Resumable Upload API to generate an asset handle.

4::aW...

<HEADER_FORMAT>

Enum

Required if using a header.

Can be IMAGE, or VIDEO.

IMAGE

<LIMITED_TIME_OFFER_TEXT>

String

Required.

Offer details text.

Maximum 16 characters.

Expiring offer!

<OFFER_CODE_EXAMPLE>

String

Required.

Example offer code.

Maximum 15 characters.

CARIBE25

<TEMPLATE_LANGUAGE>

Enum

Required.

Template language and locale code.

en_US

<TEMPLATE_NAME>

String

Required.

Template name.

Maximum 512 characters.

limited_time_offer_caribbean_pkg_2023

<URL_BUTTON_TEXT>

String

Required.

URL button label text. Supports 1 variable.

25 characters maximum.

Book now!

<URL_BUTTON_URL>

String

Required.

URL of website that loads in the device's default mobile web browser when the URL button is tapped by the WhatsApp user.

Supports 1 variable appended to the end of the URL string.

Maximum 2000 characters.

https://awesomedestinations.com/offers?code={{1}}

<URL_EXAMPLE_WITH_VARIABLE_EXAMPLE>

String

Required if URL uses a variable.

Example URL with example variable appended to the end.

No maximum, but value counts against <URL_BUTTON_URL> maximum.

https://awesomedestinations.com/offers?ref=n3mtql

Offer Expiration Details

The delivered message can display an offer expiration details section with a heading, an optional expiration timer, and the offer code itself.

The expiration timer is a text string that is not customizable, but it will change to red text if the message is viewed and the offer code is expiring within the next hour. (You include the actual offer code and its expiration timestamp when you send the template in a template message.)

Example Request

This is an example request to create a limited-time offer template that uses:

an image header component
body text component with variables
the limited time offer component
a copy code button
a button URL with a variable

curl 'https://graph.facebook.com/v17.0/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "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"
          ]
        }
      ]
    }
  ]
}'

Example Response

{
  "id": "546151681022936",
  "status": "PENDING",
  "category": "MARKETING"
}

Sending Limited-Time Offer Templates

Once your limited-time offer template is approved, you can use the Cloud API to send it in a limited-time offer template message.