DokumentacjaEngagement Platform API
Sign inGet started
Guides
API

Image templates

Image templates display an image in the header section of the message, combined with a text body, optional footer, and optional buttons. These are useful for visually rich marketing messages, product promotions, and announcements.

Block Structure

BlockRequiredMax per templateDescription
Image headerYes1Image displayed at the top of the message
Text bodyYes1Main message content (max 1024 characters)
Text footerNo1Text below the body (max 60 characters, no rich formatting)
ButtonsNo10 totalInteractive action or quick reply buttons
Here's how an image template with action buttons renders on WhatsApp:
When a link button is present, WhatsApp generates a link preview below the image header. The image replaces the text header position, with body and footer below it.

Image Header

The image header displays an image at the top of the message. The mediaUrl must be a publicly accessible URL pointing to a supported image format.
Supported formats: JPEG, PNG (max 5 MB)
Przykład kodu
{
  "type": "image",
  "role": "header",
  "image": {
    "mediaUrl": "https://example.com/images/promo-banner.jpg"
  }
}
PropertyRequiredDescription
mediaUrlYesPublic URL of the image (must be HTTPS)
For approved templates, the mediaUrl is used as the example image during Meta's review. When sending the message, you can override the image URL using a variable.

Using a variable for the image URL

To make the image dynamic at send time, use a variable in the mediaUrl:
Przykład kodu
{
  "type": "image",
  "role": "header",
  "image": {
    "mediaUrl": "{{imageUrl}}"
  }
}
Declare the variable in the variables array with an example URL:
Przykład kodu
{
  "key": "imageUrl",
  "description": "URL of the promotional image",
  "type": "string",
  "format": "none",
  "examplesLocale": {
    "en": {
      "exampleValueStrings": ["https://example.com/images/promo.jpg"]
    }
  }
}

Uploading media via the Media Library

If you don't already have a publicly hosted URL, use the Media Library API to upload a file and get a mediaUrl to use in the template.
Step 1 -- Create an asset:
Przykład kodu
POST /workspaces/{workspaceId}/media-library-assets

{
  "name": "promo-banner.jpg"
}
Returns an asset with id and uploadStatus: "pending".
Step 2 -- Get a presigned upload URL:
Przykład kodu
POST /workspaces/{workspaceId}/media-library-assets/{assetId}/presigned-upload

{
  "contentType": "image/jpeg"
}
Returns uploadUrl, uploadMethod, uploadFormData, and mediaUrl.
Step 3 -- Upload the file using the returned uploadUrl and uploadFormData (direct S3 upload).
Step 4 -- Complete the upload:
Przykład kodu
PATCH /workspaces/{workspaceId}/media-library-assets/{assetId}

{
  "mediaUrl": "https://media.api.bird.com/workspaces/{workspaceId}/media-library-assets/{assetId}/media"
}
Use the mediaUrl from step 2. The asset status changes to "complete" and the URL can now be used in template blocks.
WhatsApp media limits for images:
FormatMax size
JPEG, PNG5 MB

Body

The body is mandatory and supports up to 1024 characters with variables.
Przykład kodu
{
  "type": "text",
  "role": "body",
  "text": {
    "text": "Check out our latest collection! Use code {{promoCode}} for 20% off."
  }
}
The body is mandatory and supports up to 1024 characters with variables. For marketing templates, WhatsApp truncates the body after approximately 5 lines with a "Read more" link -- see body truncation.

Footer

Optional text footer, max 60 characters.
Przykład kodu
{
  "type": "text",
  "role": "footer",
  "text": {
    "text": "Offer valid until end of month"
  }
}

Buttons

Buttons are optional interactive elements appended after the footer. Templates support up to 10 buttons total, but there are restrictions on the number and combination of each type.

Action buttons

Action buttons trigger a specific action when tapped.
Link button
Opens a URL. Up to 2 link buttons per template. Button text max 20 characters. The URL can include a variable suffix:
Przykład kodu
{
  "type": "link-action",
  "linkAction": {
    "text": "View order",
    "url": "https://example.com/orders/{{orderId}}"
  }
}
Phone number button
Dials a phone number. 1 per template. Button text max 25 characters, phone number max 20 characters.
Przykład kodu
{
  "type": "call-phone-number-action",
  "callPhoneNumberAction": {
    "text": "Call support",
    "phoneNumber": "+14155551234"
  }
}
Copy code button
Copies a code to the clipboard. 1 per template. When used, the body must also contain the same variable.
Przykład kodu
{
  "type": "copy-code-action",
  "copyCodeAction": {
    "code": "{{code}}"
  }
}

Quick reply buttons

Quick reply buttons send a predefined response back when tapped. Up to 10 per template.
Przykład kodu
{
  "type": "reply-action",
  "replyAction": {
    "text": "Yes, confirm",
    "payload": "confirm_order"
  }
}

Button ordering rules

When combining button types, they must follow this order:
  1. copy-code-action
  2. link-action
  3. call-phone-number-action
  4. reply-action
Quick reply buttons and action buttons must be grouped separately -- they cannot be interleaved.

Button limits

Button typeMaximum per template
copy-code-action1
link-action2
call-phone-number-action1
reply-action10

Button Rendering Behavior

WhatsApp displays buttons differently depending on the total count.

3 or fewer buttons

When a template has 3 or fewer buttons, all buttons are shown directly below the message:

More than 3 buttons

When a template has more than 3 buttons, WhatsApp shows the first 2 buttons inline and collapses the rest behind a "See all options" link:
Tapping "See all options" opens a bottom sheet with all buttons. See text template button overflow for an example of the bottom sheet.
When a template includes a link-action button, WhatsApp generates a link preview between the image and the body text. Unlike text templates where the preview appears at the top, for image templates the preview sits below the image header.

Complete Example

Przykład kodu
{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "summer_sale_promo"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "variables": [
    {
      "key": "promoCode",
      "description": "Promotional discount code",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["SUMMER20"]
        }
      }
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "image",
          "role": "header",
          "image": {
            "mediaUrl": "https://example.com/images/summer-sale.jpg"
          }
        },
        {
          "type": "text",
          "role": "body",
          "text": {
            "text": "Our Summer Sale is here! Get up to 50% off on selected items. Use code {{promoCode}} at checkout."
          }
        },
        {
          "type": "text",
          "role": "footer",
          "text": {
            "text": "While stocks last"
          }
        },
        {
          "type": "link-action",
          "linkAction": {
            "text": "Shop now",
            "url": "https://example.com/summer-sale"
          }
        },
        {
          "type": "reply-action",
          "replyAction": {
            "text": "Not interested",
            "payload": "opt_out_promo"
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Related