File & Video Templates

File and video templates display a document or video in the header section of the message, combined with a text body, optional footer, and optional buttons. These are ideal for sending contracts, invoices, instructional videos, and other media-rich messages.

Block Structure

Block	Required	Max per template	Description
File header	Yes	1	Document, video, or animated GIF 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 a video template with action buttons renders on WhatsApp:

Videos display with a play button overlay and file size badge. Documents (PDFs, Word, etc.) show a download button instead -- see the file example below.

File Header

The file header attaches a document or video at the top of the message. You must specify both the mediaUrl and contentType.

Codevoorbeeld

{
  "type": "file",
  "role": "header",
  "file": {
    "mediaUrl": "https://example.com/docs/invoice.pdf",
    "contentType": "application/pdf",
    "filename": "Invoice-2024.pdf"
  }
}

Property	Required	Description
mediaUrl	Yes	Public URL of the file (must be HTTPS)
contentType	Yes	MIME type of the file (see supported types below)
filename	No	Display name for the file
isAnimated	No	Renders the header as an animated GIF. Marketing templates only; requires video/mp4 ≤ 3.5 MB. See Animated GIF header

Supported content types

Documents (max 100 MB)

Content type	Format
application/pdf	PDF
application/vnd.ms-powerpoint	PowerPoint (.ppt)
application/msword	Word (.doc)
application/vnd.ms-excel	Excel (.xls)
application/vnd.openxmlformats-officedocument.wordprocessingml.document	Word (.docx)
application/vnd.openxmlformats-officedocument.presentationml.presentation	PowerPoint (.pptx)
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Excel (.xlsx)

Video (max 16 MB)

Content type	Format
video/mp4	MP4 video (H.264 video codec, AAC audio codec)
video/3gpp	3GPP video

A video/mp4 asset can also be used as an animated GIF header by setting isAnimated: true, in which case the limit is 3.5 MB.

Audio (max 16 MB)

Content type	Format
audio/mp4	MP4 audio
audio/mpeg	MPEG audio (MP3)
audio/amr	AMR audio
audio/ogg	OGG audio (must use opus codec)
audio/opus	Opus audio

Images via file block (max 5 MB)

Content type	Format
image/jpeg	JPEG
image/png	PNG

For images, prefer the dedicated image block type (see Image Template Blocks). The file block with image content types is supported but the image block provides a better display experience.

Video Header Example

Codevoorbeeld

{
  "type": "file",
  "role": "header",
  "file": {
    "mediaUrl": "https://example.com/videos/product-demo.mp4",
    "contentType": "video/mp4",
    "filename": "Product Demo"
  }
}

Animated GIF header

A marketing template can use an animated header that autoplays and loops in the chat, rendered as a GIF. Set isAnimated: true on a file header block. The asset is still an mp4 — WhatsApp submits it under its GIF header format, distinct from a regular video header.

Codevoorbeeld

{
  "type": "file",
  "role": "header",
  "file": {
    "mediaUrl": "https://example.com/promos/new-season.mp4",
    "contentType": "video/mp4",
    "isAnimated": true
  }
}

Constraints:

Rule	Value
contentType	Must be video/mp4. Any other type is rejected
Max size	3.5 MB (smaller than the 16 MB limit for a regular video header)
Category	Marketing templates only — rejected for utility and authentication

The header autoplays on a loop with no play button and no download/file-size badge — the tell-tale differences from the video header, which shows both:

Omit isAnimated (or set it to false) and the same video/mp4 asset renders as a standard tap-to-play video header instead, subject to the 16 MB video limit.

Using a variable for the file URL

To make the file dynamic at send time:

Codevoorbeeld

{
  "type": "file",
  "role": "header",
  "file": {
    "mediaUrl": "{{documentUrl}}",
    "contentType": "application/pdf",
    "filename": "{{documentName}}"
  }
}

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:

Codevoorbeeld

POST /workspaces/{workspaceId}/media-library-assets

{
  "name": "invoice-sample.pdf"
}

Returns an asset with id and uploadStatus: "pending".

Step 2 -- Get a presigned upload URL:

Codevoorbeeld

POST /workspaces/{workspaceId}/media-library-assets/{assetId}/presigned-upload

{
  "contentType": "application/pdf"
}

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:

Codevoorbeeld

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 by type:

Type	Formats	Max size
Documents	PDF, DOC, DOCX, PPTX, XLSX	100 MB
Video	MP4 (H.264/AAC), 3GP	16 MB
Animated GIF	MP4 (isAnimated: true)	3.5 MB
Audio	AAC, AMR, MP3, M4A, OGG (opus)	16 MB
Images	JPEG, PNG	5 MB

The contentType in the presigned upload request must match the file format (e.g. application/pdf, video/mp4).

Body

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

Codevoorbeeld

{
  "type": "text",
  "role": "body",
  "text": {
    "text": "Hi {{customerName}}, please find your invoice attached for order {{orderNumber}}."
  }
}

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.

Codevoorbeeld

{
  "type": "text",
  "role": "footer",
  "text": {
    "text": "Contact support for questions"
  }
}

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:

Codevoorbeeld

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

Codevoorbeeld

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

Codevoorbeeld

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

Codevoorbeeld

{
  "type": "reply-action",
  "replyAction": {
    "text": "Yes, confirm",
    "payload": "confirm_order"
  }
}

Button ordering rules

When combining button types, they must follow this order:

copy-code-action
link-action
call-phone-number-action
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

{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "product_brochure"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "variables": [
    {
      "key": "customerName",
      "description": "Customer's name",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["Jane Doe"]
        }
      }
    },
    {
      "key": "promoCode",
      "description": "Promotional discount code",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["NEWSEASON20"]
        }
      }
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "file",
          "role": "header",
          "file": {
            "mediaUrl": "https://example.com/brochures/new-season.pdf",
            "contentType": "application/pdf",
            "filename": "New-Season-Collection.pdf"
          }
        },
        {
          "type": "text",
          "role": "body",
          "text": {
            "text": "Hi {{customerName}}, our new season collection is here! Download the brochure above and use code {{promoCode}} for 20% off your first order."
          }
        },
        {
          "type": "text",
          "role": "footer",
          "text": {
            "text": "Reply STOP to unsubscribe"
          }
        },
        {
          "type": "link-action",
          "linkAction": {
            "text": "Shop now",
            "url": "https://example.com/new-season"
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Complete Example -- Video

Codevoorbeeld

{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "product_tutorial"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "file",
          "role": "header",
          "file": {
            "mediaUrl": "https://example.com/videos/tutorial.mp4",
            "contentType": "video/mp4",
            "filename": "Getting Started Tutorial"
          }
        },
        {
          "type": "text",
          "role": "body",
          "text": {
            "text": "Watch our quick tutorial to get started with your new product. It only takes 2 minutes!"
          }
        },
        {
          "type": "reply-action",
          "replyAction": {
            "text": "Helpful",
            "payload": "tutorial_helpful"
          }
        },
        {
          "type": "reply-action",
          "replyAction": {
            "text": "Need more help",
            "payload": "tutorial_need_help"
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Complete Example -- Animated GIF

Codevoorbeeld

{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "season_launch_gif"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "file",
          "role": "header",
          "file": {
            "mediaUrl": "https://example.com/promos/new-season.mp4",
            "contentType": "video/mp4",
            "isAnimated": true
          }
        },
        {
          "type": "text",
          "role": "body",
          "text": {
            "text": "See our latest product launch above and what's new this season!"
          }
        },
        {
          "type": "text",
          "role": "footer",
          "text": {
            "text": "Tap below to learn more"
          }
        },
        {
          "type": "link-action",
          "linkAction": {
            "text": "Shop now",
            "url": "https://example.com/new-season"
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Text Template Blocks -- Templates with text-only headers
Image Template Blocks -- Templates with image headers
Creating WhatsApp Message Templates -- Full template creation workflow

File & Video Templates

Block Structure

File Header

Supported content types

Video Header Example

Animated GIF header

Using a variable for the file URL

Uploading media via the Media Library

Body

Footer

Buttons

Action buttons

Quick reply buttons

Button ordering rules

Button limits

Button Rendering Behavior

3 or fewer buttons

More than 3 buttons

Complete Example -- PDF Document

Complete Example -- Video

Complete Example -- Animated GIF