Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Prévias de mídia e imagens HD

Leia tamanhos de imagem, durações, prévias, prévias de links e pares de imagens HD nos eventos de mensagem, e envie imagens com prévia.

Ver em Markdown

Os eventos de mensagem de números com Dispositivos vinculados trazem os detalhes de exibição que o WhatsApp inclui em uma mensagem. Use-os para montar o balão de mídia, mostrar uma prévia antes de baixar o arquivo ou exibir um cartão de link. Todos os campos são opcionais e são omitidos quando o remetente não os incluiu.

Esses campos aparecem nas cargas de message.received, message.update e message.sent. O campo media existente não mudou; continue baixando a mídia com ele.

Campos de exibição#

CampoTipos de mensagemValor
width, heightimage, video, stickerTamanho em pixels, conforme declarado pelo remetente.
secondsaudio, videoDuração em segundos.
waveformaudioAté 64 números de 0 a 1 que descrevem o volume de uma mensagem de voz ao longo do tempo.
pageCountdocumentNúmero de páginas, conforme declarado pelo remetente.
thumbnailimage, video, documentPrévia JPEG incorporada: contentType (image/jpeg), data em base64 e width e height opcionais.
linkPreviewtextCartão de link: url e, opcionalmente, title, description, previewType e thumbnail.
associationimage, videoPresente na cópia HD de uma foto ou vídeo. Consulte Pares de imagens HD.
qualityimage, videohd em uma cópia HD; standard em uma mensagem cujo remetente anunciou uma cópia HD.

thumbnail só aparece quando o remetente incorporou uma prévia JPEG de no máximo 16 KiB. A Polymorfa não baixa prévias que o WhatsApp armazena como arquivos separados, então algumas mensagens não têm thumbnail mesmo que o WhatsApp mostre uma prévia. Prévias de figurinhas não são arquivos JPEG e não são incluídas.

linkPreview.url é a URL que a prévia descreve, como aparece no texto da mensagem. previewType é o tipo de prévia do WhatsApp em letras minúsculas, por exemplo none, video ou image.

JSON
{
  "type": "image",
  "mimeType": "image/jpeg",
  "width": 1600,
  "height": 1200,
  "thumbnail": {
    "contentType": "image/jpeg",
    "data": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
    "width": 100,
    "height": 75
  },
  "quality": "standard"
}

Pares de imagens HD#

Quando um contato envia uma foto ou um vídeo em HD, o WhatsApp entrega duas mensagens: uma mensagem em qualidade padrão e uma cópia HD separada. A cópia HD chega como um evento image ou video comum com:

  • association.type: hd_image ou hd_video;
  • association.parentMessageId: o id da mensagem em qualidade padrão; e
  • quality: hd.

Mostre a cópia HD no lugar da mensagem padrão que ela indica, e não como uma segunda mensagem. Os dois eventos podem chegar em qualquer ordem. Se a cópia HD chegar primeiro, guarde-a até chegar a mensagem padrão com esse id. parentMessageId usa o mesmo identificador do id da mensagem padrão, então você pode relacioná-las diretamente.

A Polymorfa descarta uma cópia HD cujo remetente seja diferente do remetente da mensagem que ela indica, assim como o WhatsApp faz.

Enviar imagens com prévia#

Quando você envia uma imagem de um número com Dispositivos vinculados, a Polymorfa adiciona a largura, a altura e uma prévia JPEG com 100 pixels no lado maior, como os clientes do WhatsApp fazem. A sua imagem é enviada sem alterações. Imagens que a Polymorfa não consegue decodificar, ou maiores que 24 megapixels, são enviadas sem a prévia.

Para vídeos e documentos, você pode fornecer a sua própria prévia em content.video.thumbnail ou content.file.thumbnail: um JPEG codificado em base64 de no máximo 16 KiB. Uma prévia que não seja JPEG ou que seja maior retorna 400 invalid_parameter. Números oficiais do WhatsApp Business ignoram essas prévias.

JSON
{
  "conversation": { "phoneNumber": "+15550001111" },
  "content": {
    "video": {
      "url": "https://example.com/clip.mp4",
      "caption": "Product tour",
      "thumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
    }
  }
}

Qualidade da imagem#

content.image.quality aceita standard (o padrão) ou hd. A Polymorfa não envia pares HD: uma solicitação com quality: "hd" envia a imagem uma vez, como foi fornecida, exatamente como standard, e a resposta não tem hdMessageId. hdMessageId só aparece quando uma cópia HD foi enviada; id sempre identifica a mensagem em qualidade padrão.

Baixar mídia #

Baixe um arquivo recebido com Download linked media, usando uma credencial com media:read. A resposta é o arquivo em streaming binário ou um redirecionamento 302.

cURL
curl -L -o attachment.bin "https://api.polymorfa.com/messaging/media/$MEDIA_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
const download = await messaging.media.downloadStream("<media-id>");
console.log(download.contentType, download.filename);
// download.body is a ReadableStream<Uint8Array>. Read it once.
Graph API
# Metadata, with a Polymorfa-hosted download URL
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$MEDIA_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

# The file itself
curl -L "https://api.polymorfa.com/graph/whatsapp/v26.0/$MEDIA_ID/download" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -o attachment.bin

TypeScript:

No Node.js, grave o arquivo direto em disco:

TypeScript
import { downloadMediaToFile } from "@polymorfa/sdk/node";

await downloadMediaToFile(messaging.media, "<media-id>", "./attachment.bin", {
  maxBytes: 50 * 1024 * 1024,
});

O helper grava em um arquivo temporário e só o move para o lugar final depois que o download termina. Trate filename como nome de exibição, não como caminho.

Quando um projeto não armazena mídia, os eventos de mídia recebida trazem um descritor media criptografado no lugar. messaging.media.downloadFromWhatsApp(event.payload) baixa e descriptografa o arquivo do WhatsApp sem chamar a API da Polymorfa. O descritor contém uma chave de descriptografia, então nunca registre em log os corpos de eventos armazenados.

Números de teste#

Números de teste enviam e recebem os mesmos campos. Imagens enviadas de um número de teste incluem o tamanho e uma prévia de 100 pixels, e as prévias de vídeo e documento que você fornece são entregues ao número de teste que as recebe.

Figurinhas e pacotes de figurinhas descreve as operações candidatas e seus limites de lançamento.