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

Block	Required	Max per template	Description
Image header	Yes	1	Image displayed at the top of the message
Text body	Yes	1	Main message content (max 1024 characters)
Text footer	No	1	Text below the body (max 60 characters, no rich formatting)
Buttons	No	10 total	Interactive 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)

{
  "type": "image",
  "role": "header",
  "image": {
    "mediaUrl": "https://example.com/images/promo-banner.jpg"
  }
}

Property	Required	Description
mediaUrl	Yes	Public 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:

{
  "type": "image",
  "role": "header",
  "image": {
    "mediaUrl": "{{imageUrl}}"
  }
}

Declare the variable in the variables array with an example URL:

{
  "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:

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:

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:

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:

Format	Max size
JPEG, PNG	5 MB

---

Body

The body is mandatory and supports up to 1024 characters with variables.

{
  "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.

{
  "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:

{
  "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.

{
  "type": "call-phone-number-action",
  "callPhoneNumberAction": {
    "text": "Call support",
    "phoneNumber": "[phone]"
  }
}

Copy code button

Copies a code to the clipboard. 1 per template. When used, the body must also contain the same variable.

{
  "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.

{
  "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 type	Maximum per template
copy-code-action	1
link-action	2
call-phone-number-action	1
reply-action	10

---

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.

Link preview

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

{
  "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

• Text Template Blocks -- Templates with text-only headers

• File & Video Template Blocks -- Templates with document or video headers

• Creating WhatsApp Message Templates -- Full template creation workflow