DocumentationEngagement Platform API
Sign inGet started
Guides
API

Coupon Templates

Coupon templates let you send promotional messages with a copy-to-clipboard coupon code. When the user taps the coupon button, the code is copied to their clipboard for easy use. These templates can also include additional action and quick reply buttons.

Block Structure

A coupon template uses a single whatsapp-coupon block:
ComponentRequiredMaxDescription
HeaderNo1Text, image, or file header
Body textYes1Main message text (max 1024 characters)
Footer textNo1Text below the body (max 60 characters)
Coupon actionYes1Copy-code button for the coupon
Additional buttonsNo9Link, phone, or quick reply buttons
Here's how a coupon template with a text header, body, footer, and additional link button renders on WhatsApp:
The "Copy offer code" button copies the coupon code to the user's clipboard. The link preview at the top is automatically generated by WhatsApp from the link button URL.

Header

Coupon templates support three header types (all optional):
Text header:
Exemple de code
{
  "type": "text",
  "text": {
    "text": "Special Offer"
  }
}
Image header:
Exemple de code
{
  "type": "image",
  "image": {
    "mediaUrl": "https://example.com/images/sale-banner.jpg"
  }
}
File/video header:
Exemple de code
{
  "type": "file",
  "file": {
    "mediaUrl": "https://example.com/videos/promo.mp4",
    "contentType": "video/mp4"
  }
}
If you need to host media, use the Media Library API to upload files and get a mediaUrl. See Image Template Blocks -- Uploading media for the full upload flow.

Body

The body is mandatory. It should describe the offer and typically includes the coupon code variable.
Exemple de code
{
  "type": "text",
  "text": {
    "text": "Use code {{couponCode}} to get 25% off your next purchase! Valid until {{expiryDate}}."
  }
}

Footer

Optional text footer, max 60 characters.
Exemple de code
{
  "type": "text",
  "text": {
    "text": "Terms and conditions apply"
  }
}

Coupon Action

The coupon action creates a "Copy code" button. When tapped, the code is copied to the user's clipboard.
Exemple de code
{
  "type": "copy-code-action",
  "copyCodeAction": {
    "code": "{{couponCode}}"
  }
}
PropertyRequiredDescription
codeYesThe coupon code to copy. Can be a static string or a variable.
When using a variable for the coupon code, the same variable should appear in the body text so the user can see the code before copying it.

Additional Buttons

Coupon templates can include up to 9 additional buttons alongside the coupon action (for a combined total matching the standard button limits). These follow the same types and ordering rules as text templates.
Exemple de code
{
  "type": "link-action",
  "linkAction": {
    "text": "Shop now",
    "url": "https://example.com/shop"
  }
}
See Text Template Blocks -- Buttons for button types and ordering rules.

Complete Example

Exemple de code
{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "flash_sale_coupon"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "variables": [
    {
      "key": "couponCode",
      "description": "The discount coupon code",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["FLASH25"]
        }
      }
    },
    {
      "key": "customerName",
      "description": "Customer's first name",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["Sarah"]
        }
      }
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "whatsapp-coupon",
          "whatsappCoupon": {
            "header": {
              "type": "image",
              "image": {
                "mediaUrl": "https://example.com/images/flash-sale.jpg"
              }
            },
            "body": {
              "type": "text",
              "text": {
                "text": "Hi {{customerName}}, our Flash Sale is live! Use code {{couponCode}} to save 25% on everything. Hurry, offer ends tonight!"
              }
            },
            "footer": {
              "type": "text",
              "text": {
                "text": "Cannot be combined with other offers"
              }
            },
            "couponAction": {
              "type": "copy-code-action",
              "copyCodeAction": {
                "code": "{{couponCode}}"
              }
            },
            "actions": [
              {
                "type": "link-action",
                "linkAction": {
                  "text": "Shop the sale",
                  "url": "https://example.com/flash-sale"
                }
              },
              {
                "type": "reply-action",
                "replyAction": {
                  "text": "Remind me later",
                  "payload": "remind_flash_sale"
                }
              }
            ]
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Related