Pular para o conteúdo principal
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, ou o link público dele, 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.

Duas formas de enviar

O formato é escolhido pelo Content-Type da requisição.
multipart/form-data com o arquivo no campo file.O campo type é opcional. O MIME type usado é o da própria parte file; type só entra quando a parte chega sem tipo ou como application/octet-stream.

Fluxo

1

Suba o arquivo ou o link

POST /whatsapp/businesses/{wabaId}/templates/media, em uma das duas formas acima.
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 Referência da API:
O handle tem validade. Suba o arquivo e crie o template na mesma sessão — não guarde o handle para usar dias depois.
Em arquivos maiores, o handle pode vir com quebras de linha. Use o valor de h exatamente como recebido, sem remover nada.

Pré-requisito de configuração

O upload depende do App ID da Meta cadastrado na conta. Sem ele a chamada retorna 422, com o código 375 no corpo de erro. 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

Erros

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

file
file
obrigatório

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

type
string

Opcional. MIME type do arquivo (ex: image/jpeg, video/mp4, application/pdf). Só é usado quando a parte file chega sem tipo ou como application/octet-stream

Exemplo:

"image/jpeg"

Resposta

Upload concluído

h
string

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