Skip to main content
POST
Upload template media

Concepts

Meta does not accept the file directly when creating the template. It requires a header_handle produced by the Resumable Upload API, which depends on the application token — that is why the upload goes through here and not through your frontend. This endpoint takes the file and returns the handle, ready to use.

When you need this

Only when the template has a HEADER component of type IMAGE, VIDEO or DOCUMENT. Templates with a text header, or with no header, need no upload.

Flow

1

Upload the file

POST /whatsapp/businesses/{wabaId}/templates/media with multipart/form-data, fields file and type.
2

Keep the handle

The response returns the handle in the h field.
3

Use it on the HEADER component

Pass the handle as the HEADER example in Create template:
The handle expires. Upload the file and create the template in the same session — do not store the handle to use days later.
Besides h, the API accepts the handle under the keys handle, header_handle, headerHandle and mediaHandle. Use h, which is the canonical form.

Configuration prerequisite

The upload depends on the Meta App ID and App Secret registered on the account. Without them the call returns 422 with MISSING_APP_CREDENTIALS. This is configured in the dashboard, under Security — there is no public endpoint to register the app credentials. See also SDK origins, which covers the other prerequisite of the SDK flow.

Limits

Authorizations

Authorization
string
header
required

Secret Key generated in the Omni Z-API Security panel

Path Parameters

wabaId
string
required

WABA ID (obtained via List WABAs)

Example:

"428083093730937"

Body

multipart/form-data
file
file
required

Header file (image, video or document). 100 MB limit

type
string
required

File MIME type (e.g. image/jpeg, video/mp4, application/pdf)

Example:

"image/jpeg"

Response

Upload completed

h
string

Handle to use as the HEADER component example when creating the template