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 or video 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.

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

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

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

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

Using a variable for the file URL

To make the file dynamic at send time:

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

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:

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:

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

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

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

{
  "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. These rules are the same as for text templates.

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. Here's an example with a file (document) header:

Tapping "See all options" opens a bottom sheet with all buttons. See text template button overflow for an example of the bottom sheet.

---

Complete Example -- PDF Document

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

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

---

Related

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

• Image Template Blocks -- Templates with image headers

• Creating WhatsApp Message Templates -- Full template creation workflow