POST/v1/templates/samplesbeta

Upload a template header sample

Needs: Send WhatsApp messages; manage templates, quick messages and WhatsApp short links (messaging:write)
Plan: Any plan with API access
Limits: 60 a minute per key
Dry run: Yes — every check runs with ?dry_run=true, nothing changes
Undo: Nothing to undo: an unused sample expires on its own.

WhatsApp reviews an IMAGE, VIDEO or DOCUMENT header by a sample file. Give the public https URL of one file (JPEG or PNG up to 5 MB, MP4 up to 16 MB, or PDF); it is downloaded, checked and uploaded to WhatsApp, and you get a handle to put in the draft's header.media_handle for Create a WhatsApp template.

The URL must be the file itself (no web page, no redirects) on a public address. Nothing is sent to customers. With ?dry_run=true (and with a test key) the file is not downloaded: only the URL (public https) and the file type its name declares are checked, and nothing is uploaded. The file's real type and size are checked when it is uploaded.

Try it

Edit as JSON

urlrequiredstring

Public https URL of the file.

business_account_idoptionalstring

The WhatsApp account the template will belong to. Needed only when your workspace has several.

channel_idoptionalstring

Instead of `business_account_id`: a connected WhatsApp channel; its account is used.

Idempotency-Keyoptional — made for you if empty

Protects against doing it twice if you retry: a retry with the same key gets the first answer back instead of running again.

Test mode (dry run): nothing will change

Run liveTurns test mode off for this page only. It switches back when you leave the page.

curl -X POST 'https://mcp.wa-api.cloud/v1/templates/samples?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://cdn.example.com/banner.png"
}'

The code reads your key from $API_KEY.

Body

Body fields
Field	Type	What it is
urlrequired	string	Public https URL of the file.12–2000 characters
business_account_id	string	The WhatsApp account the template will belong to. Needed only when your workspace has several.0–64 characters
channel_id	string	Instead of `business_account_id`: a connected WhatsApp channel; its account is used.0–64 charactersSigned in? Pick one from your data with “My data”.

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`
Idempotency-Key	header	Any unique string (8–128 characters). A retry with the same key returns the first answer instead of running twice. Kept 24 hours.pattern `^[A-Za-z0-9._:-]+$` · 8–128 characters

Response `200`

The handle, and the header format the file fits.

Response fields
Field	Type	What it is
handlerequired	string	Put this in the draft's header.mediaHandle (valid for the template submission).
header_formatrequired	string	The header format this file fits.one of: `IMAGE`, `VIDEO`, `DOCUMENT`
mime_typerequired	string
bytesrequired	number
business_account_idrequired	string
business_account_namerequired	string
dry_run	boolean	`true` when this was a dry run: every check ran and nothing changed.

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field. The URL is not a public https file, the type or size is not allowed, or the workspace has several WhatsApp accounts and none was chosen.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
409	conflict	Also returned while a request with the same Idempotency-Key is still running.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
502	upstream_error	WhatsApp did not accept the file.
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.
504	timeout	The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.

Examples

An image header sample

Request body

{
  "url": "https://cdn.example.com/banner.png"
}

Response 200

{
  "handle": "4::aW1hZ2UvcG5n:ARbExample",
  "header_format": "IMAGE",
  "mime_type": "image/png",
  "bytes": 48213,
  "business_account_id": "4410",
  "business_account_name": "Main WhatsApp"
}

Operation path

The same operation is also at POST /v1/ops/messaging_upload_template_sample, with every field in the JSON body.