Skip to main content
Envie imagens, vídeos, documentos e áudio pelo WhatsApp com o mesmo endpoint usado para todo o resto: POST /v1/messages/send. Não existe um endpoint de mídia separado — a mídia é um dos três modos de envio mutuamente exclusivos:
  1. Envio de template — templateId (+ media opcional para sobrescrever)
  2. Envio de texto livre — text
  3. Envio direto de mídia — media + mediaType, sem templateId e sem text

​
Envio direto de mídia

Forneça media + mediaType sem templateId ou text. Nesse modo, buttons, header, footer e variables não são permitidos. Um caption opcional é permitido para image, video e document — mas não para audio, voice ou sticker.

​
Campos media e mediaType

  • media — uma URL http(s) pública ou um data URI base64 (data:<mime>;base64,...).
  • mediaType — image, video, document, audio, voice ou sticker. Defina-o explicitamente quando a extensão da URL não for óbvia (ex.: um PDF cuja URL não termina em .pdf).

​
Base64 vs. URL por provedor

​
Áudio é uma mensagem de voz (PTT)

Quando mediaType é audio, o arquivo é entregue como uma mensagem de voz (PTT) do WhatsApp em todos os provedores. Em números não oficiais (Pilot Status web), o destinatário vê brevemente um indicador de presença “gravando áudio” antes da entrega; a Meta Cloud API não possui API de presença de saída, então nenhum indicador aparece nos envios pela Meta.

​
Figurinhas (stickers)

mediaType: "sticker" envia uma figurinha do WhatsApp. É só envio direto de mídia — nunca com templateId — e não aceita caption nem mediaFilename (os dois retornam 400), porque figurinha não carrega texto. O arquivo precisa ser image/webp e ter exatamente 512×512 pixels: 512×512 é exigência rígida, não recomendação — qualquer outra medida é recusada, inclusive uma quase quadrada como 361×363. Outro formato ou arquivo maior é recusado pelo WhatsApp, não por esta API — o envio é aceito com 202 e a falha chega depois no webhook message.failed. Converta antes de enviar em vez de contar com a API para barrar.

​
Mídia com templates

Adicione media (+ mediaType) a um envio de template para anexar ou sobrescrever a mídia — ela tem precedência sobre qualquer URL de mídia embutida no template:
Observe que media/mediaType não podem ser combinados com um envio de text livre. A API aceita buttons junto com mediaType: "video" ou "document", embora a Meta possa rejeitar botões em algumas mensagens de vídeo/PDF dependendo do cliente do destinatário.

​
Relacionado