Skip to main content
POST
Upload de mídia para template

Conceituação

A Meta não aceita o arquivo direto na criação do template. Ela exige um header_handle produzido pela Resumable Upload API, que depende do token da aplicação — por isso o upload passa por aqui, e não pelo seu frontend. Este endpoint recebe o arquivo e devolve o handle pronto para usar.

Quando você precisa disso

Somente quando o template tem um componente HEADER do tipo IMAGE, VIDEO ou DOCUMENT. Templates com header de texto, ou sem header, não precisam de upload.

Fluxo

1

Suba o arquivo

POST /whatsapp/businesses/{wabaId}/templates/media com multipart/form-data, campos file e type.
2

Guarde o handle

A resposta traz o handle no campo h.
3

Use no componente HEADER

Passe o handle como example do HEADER em Criar template:
O handle tem validade. Suba o arquivo e crie o template na mesma sessão — não guarde o handle para usar dias depois.
Além de h, a API aceita o handle nas chaves handle, header_handle, headerHandle e mediaHandle. Use h, que é a forma canônica.

Pré-requisito de configuração

O upload depende do App ID e do App Secret da Meta cadastrados na conta. Sem isso a chamada retorna 422 com MISSING_APP_CREDENTIALS. Isso é configurado no painel, em Segurança — não há endpoint público para cadastrar as credenciais do app. Veja também Origens do SDK, que trata do outro pré-requisito do fluxo via SDK.

Limites

Autorizações

Authorization
string
header
obrigatório

Secret Key gerada no painel de Segurança do Omni Z-API

Parâmetros de caminho

wabaId
string
obrigatório

ID do WABA (obtido via Listar WABAs)

Exemplo:

"428083093730937"

Corpo

multipart/form-data
file
file
obrigatório

Arquivo do header (imagem, vídeo ou documento). Limite de 100 MB

type
string
obrigatório

MIME type do arquivo (ex: image/jpeg, video/mp4, application/pdf)

Exemplo:

"image/jpeg"

Resposta

Upload concluído

h
string

Handle a ser usado como example do componente HEADER na criação do template