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, or its public link, 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.

Two ways to send

The format is chosen by the request Content-Type.
multipart/form-data with the file in the file field.The type field is optional. The MIME type used is the one from the file part itself; type only applies when the part arrives without a type or as application/octet-stream.

Flow

1

Upload the file or the link

POST /whatsapp/businesses/{wabaId}/templates/media, in one of the two ways above.
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 API reference:
The handle expires. Upload the file and create the template in the same session — do not store the handle to use days later.
For larger files, the handle may contain line breaks. Use the value of h exactly as received, without removing anything.

Configuration prerequisite

The upload depends on the Meta App ID registered on the account. Without it the call returns 422, with code 375 in the error body. 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

Errors

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

file
file
required

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

type
string

Optional. File MIME type (e.g. image/jpeg, video/mp4, application/pdf). Only used when the file part arrives without a type or as application/octet-stream

Example:

"image/jpeg"

Response

Upload completed

h
string

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