> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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`.

```json theme={null}
{
  "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 theme={null}
{
  "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.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.