convoup Docs
Sign in Start free
Docs / Guides / Dynamic Media

Dynamic Media Content

Templates can include dynamic media (images, videos, documents) in the header. This is essential for per-customer content like billing PDFs, product images, or personalized videos.

How Media Headers Work

When a template has a media header (IMAGE, VIDEO, or DOCUMENT format), you must provide a header_media object with:

FieldTypeDescription
type'image' | 'video' | 'document'Media type matching the template's header format
linkstringPublicly accessible URL where the media is hosted

The URL must be publicly reachable - Meta fetches the media from this URL to deliver it to the recipient.

Sending a Document (PDF Invoice)

TypeScript
await client.sendInvoice({
  to: '+918851479441',
  template: 'test_welcome_template',
  params: ['INV-1234'],
  pdfUrl: 'https://files.example.com/invoices/INV-1234.pdf',
});

Under the hood, pdfUrl is converted to:

TypeScript
headerMedia: { type: 'document', link: 'https://files.example.com/invoices/INV-1234.pdf' }

Sending an Image

TypeScript
await client.sendTemplate({
  to: '+918851479441',
  template: 'test_welcome_template',
  headerMedia: {
    type: 'image',
    link: 'https://files.example.com/products/widget-blue.png',
  },
  bodyParams: ['Widget Pro', 'Blue'],
});

Sending a Video

TypeScript
await client.sendTemplate({
  to: '+918851479441',
  template: 'test_welcome_template',
  headerMedia: {
    type: 'video',
    link: 'https://files.example.com/demos/product-tour.mp4',
  },
  bodyParams: ['Product Tour'],
});

cURL Equivalent (Document Header)

bash
curl -X POST https://api.convoup.com/api/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "to": "+918851479441",
    "template_name": "test_welcome_template",
    "language": "en_US",
    "body_params": [{"type": "text", "text": "INV-1234"}],
    "header_media": {
      "type": "document",
      "link": "https://files.example.com/invoices/INV-1234.pdf"
    }
  }'

Media Requirements

RequirementDetail
URL accessibilityMust be publicly reachable (no auth, no IP restrictions)
HTTPSURLs must use HTTPS
File sizeMax 5MB for images, 16MB for videos, 100MB for documents
Supported formatsImages: JPG, PNG; Videos: MP4; Documents: PDF
CachingMeta caches media for 30 days; use unique URLs for unique content
Common Mistake
Using a URL that requires authentication will fail silently - Meta cannot fetch the media. Always use publicly accessible URLs.

Next Steps