Template Media Headers

1. Choose the right pattern

2. How DOCUMENT delivery works

1. Create and approve a UTILITY (or other allowed) template in the dashboard with header format DOCUMENT. Upload any valid sample PDF for Meta review.
2. At send time, pass a public HTTPS URL to the customer-specific file via header_media_url, or upload the bytes via multipart header_media_file.
3. Washeej forwards the template to Meta with a document header parameter.
4. Meta downloads the file from that URL (server-to-server) and delivers a WhatsApp document. The end user sees a file, not the raw URL.

3. Media URL requirements

• Must be HTTPS and reachable from the public internet (not localhost, not private VPC-only hosts).
• Must return HTTP 200 on GET with the binary body (query-string download endpoints are fine if they return the file).
• Preferred Content-Type: application/pdf for documents, matching image/video MIME for other headers.
• Meta document size limit: 100 MB (images 5 MB, videos 16 MB).
• Prefer a path or Content-Disposition filename ending in .pdf so WhatsApp shows a clear file name.
• Signed / short-lived URLs are OK if they remain valid long enough for Meta to fetch at send time.
• Auth walls, HTML login pages, or HTML error bodies will fail Meta media download (often surfaced as media upload errors).

4. Scenario A — Dynamic PDF via public URL (JSON)

Best when your system already stores each document behind a stable or signed HTTPS link.

curl -X POST "https://staging-mobile.washeej.com/v1/templates/send" \
  -H "client-id: YOUR_CLIENT_ID" \
  -H "client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "mobile_code": "966",
    "mobile": "500000000",
    "whatsapp_account_id": YOUR_CLOUD_ACCOUNT_ID,
    "header_media_url": "https://files.example.com/docs/INV-1001.pdf",
    "body_variables": ["Ahmed", "INV-1001"]
  }'

5. Scenario B — Upload the PDF at send time (multipart)

Best when the file lives only on your app server and you do not want a public URL.

curl -X POST "https://staging-mobile.washeej.com/v1/templates/send" \
  -H "client-id: YOUR_CLIENT_ID" \
  -H "client-secret: YOUR_CLIENT_SECRET" \
  -F "template_id=YOUR_TEMPLATE_ID" \
  -F "mobile_code=966" \
  -F "mobile=500000000" \
  -F "whatsapp_account_id=YOUR_CLOUD_ACCOUNT_ID" \
  -F "header_media_file=@/path/to/invoice.pdf;type=application/pdf" \
  -F "body_variables[]=Ahmed" \
  -F "body_variables[]=INV-1001"

Accepted file fields: header_media_file or media_file. Washeej stores the upload temporarily and passes a public fetch URL to Meta.

6. Scenario C — DOCUMENT header + dynamic body text

Use when the customer should get both a PDF bubble and personalized text (name, invoice number, amount, …).

1. Header format: DOCUMENT (sample PDF for Meta review).
2. Body example: Hello {{1}}, invoice {{2}} is attached. Amount due: {{3}} {{4}}.
3. Send with header_media_url (or file upload) and ordered body_variables.

7. Scenario D — IMAGE or VIDEO headers

Same API fields as documents. Only the approved template header_format changes.

{
  "template_id": "YOUR_TEMPLATE_ID",
  "mobile_code": "966",
  "mobile": "500000000",
  "whatsapp_account_id": YOUR_CLOUD_ACCOUNT_ID,
  "header_media_url": "https://cdn.example.com/receipts/1001.jpg",
  "body_variables": ["Order 1001"]
}

• IMAGE — JPEG/PNG, max 5 MB.
• VIDEO — MP4, max 16 MB.
• DOCUMENT — PDF preferred, max 100 MB.

8. Scenario E — URL in the message text (not a file)

If the product requirement is a link inside the chat text, do not use a DOCUMENT header. Create a text template and pass the URL in body_variables. Full walkthrough: Dynamic Invoice Link.

9. Scenario F — Free-form document inside the 24-hour window

Within 24 hours of the customer’s last inbound message you may send a regular document with POST /messages (session message). Outside that window, WhatsApp requires an approved template — use this guide’s DOCUMENT header pattern.

10. Discover template IDs and header format

1. Call GET /templates (scope templates:read).
2. Use either the Washeej numeric id or Meta whatsapp_template_id as template_id when sending.
3. Confirm header_format is DOCUMENT, IMAGE, or VIDEO before relying on header_media_url.
4. Send only from a Cloud API channel (whatsapp_account_id). Device/QR channels do not support Meta templates.

11. Legacy Cloud API

The same fields work on the legacy path (existing integrations):

curl -X POST "https://staging-mobile.washeej.com/external-api/inbox/send-template-message" \
  -H "client-id: YOUR_CLIENT_ID" \
  -H "client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "mobile_code": "966",
    "mobile": "500000000",
    "whatsapp_account_id": YOUR_CLOUD_ACCOUNT_ID,
    "header_media_url": "https://files.example.com/docs/INV-1001.pdf"
  }'

New integrations should prefer POST /v1/templates/send.

12. Troubleshooting