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.
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#
| Campo | Tipos de mensagem | Valor |
|---|---|---|
width, height | image, video, sticker | Tamanho em pixels, conforme declarado pelo remetente. |
seconds | audio, video | Duração em segundos. |
waveform | audio | Até 64 números de 0 a 1 que descrevem o volume de uma mensagem de voz ao longo do tempo. |
pageCount | document | Número de páginas, conforme declarado pelo remetente. |
thumbnail | image, video, document | Prévia JPEG incorporada: contentType (image/jpeg), data em base64 e width e height opcionais. |
linkPreview | text | Cartão de link: url e, opcionalmente, title, description, previewType e thumbnail. |
association | image, video | Presente na cópia HD de uma foto ou vídeo. Consulte Pares de imagens HD. |
quality | image, video | hd 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.
{
"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_imageouhd_video;association.parentMessageId: oidda mensagem em qualidade padrão; equality: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.
{
"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 -L -o attachment.bin "https://api.polymorfa.com/messaging/media/$MEDIA_ID" \
-H "Authorization: Bearer $POLYMORFA_KEY"const download = await messaging.media.downloadStream("<media-id>");
console.log(download.contentType, download.filename);
// download.body is a ReadableStream<Uint8Array>. Read it once.# 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.binTypeScript:
No Node.js, grave o arquivo direto em disco:
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.