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 é suportado para image, video e document — mas não para audio, voice ou sticker (veja Áudio e nota de voz).

​
Campos media e mediaType

  • media — uma URL http(s) pública ou um data URI base64 (data:<mime>;base64,...). O base64 tem teto pelo tamanho decodificado: 50 MiB quando mediaType é document, 16 MiB nos demais tipos (e quando mediaType é omitido); acima disso a requisição é recusada com 400 Validation error. Envie arquivos maiores por URL — em números Meta Cloud API a URL segue os tetos da própria Meta (documento 100 MB, vídeo e áudio 16 MB, imagem 5 MB).
  • 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 e nota de voz

Como audio e voice chegam depende do número: Para enviar uma nota de voz em qualquer número, use voice. Use audio só quando quiser um arquivo de áudio em um número oficial. Em números oficiais, o PLAYED (o destinatário ouviu) só é informado para notas de voz — um envio audio nesses números não chega a PLAYED. O áudio é convertido antes do envio: para AAC em MP4 (audio/mp4) em números oficiais e para Ogg/Opus em números não oficiais. Legenda não é suportada em nenhum dos dois tipos. audio com caption retorna 400. Com voice, a legenda não é recusada, mas é descartada em números não oficiais e sua exibição em números oficiais não é garantida — não envie legenda. Logo antes da entrega, o contato vê um indicador de presença: “gravando áudio…” em números não oficiais e “digitando…” em números oficiais. A Cloud API não tem indicador de gravação e só mostra o “digitando” quando a conversa tem uma mensagem recente do contato à qual ancorá-lo.

​
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