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

# Media previews and HD images

> Read image sizes, durations, previews, link previews, and HD image pairs from message events, and send images with a preview.

Message events on Linked Devices numbers carry the display details WhatsApp
includes with a message. Use them to lay out a media bubble, show a preview
before you download the file, or render a link card. Every field is optional
and is omitted when the sender did not include it.

These fields appear on `message.received`, `message.update`, and
`message.sent` payloads. The existing `media` field is unchanged; download
media with it as before.

## Display fields

| Field | Message types | Value |
| - | - | - |
| `width`, `height` | `image`, `video`, `sticker` | Size in pixels, as declared by the sender. |
| `seconds` | `audio`, `video` | Duration in seconds. |
| `waveform` | `audio` | Up to 64 numbers from 0 to 1 that describe a voice note's loudness over time. |
| `pageCount` | `document` | Number of pages, as declared by the sender. |
| `thumbnail` | `image`, `video`, `document` | Embedded JPEG preview: `contentType` (`image/jpeg`), base64 `data`, and optional `width` and `height`. |
| `linkPreview` | `text` | Link card: `url`, and optional `title`, `description`, `previewType`, and `thumbnail`. |
| `association` | `image`, `video` | Present on the HD copy of a photo or video. See [HD image pairs](#hd-image-pairs). |
| `quality` | `image`, `video` | `hd` on an HD copy; `standard` on a message whose sender announced an HD copy. |

`thumbnail` is present only when the sender embedded a JPEG preview of at most
16 KiB. Polymorfa does not download previews that WhatsApp stores as separate
files, so some messages have no `thumbnail` even though WhatsApp shows one.
Sticker previews are not JPEG files and are not included.

`linkPreview.url` is the URL the preview describes, as it appears in the
message text. `previewType` is WhatsApp's preview kind in lower case, for
example `none`, `video`, or `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"
}
```

## HD image pairs

When a contact sends a photo or video in HD, WhatsApp delivers two messages: a
standard-quality message and a separate HD copy. The HD copy arrives as an
ordinary `image` or `video` event with:

* `association.type`: `hd_image` or `hd_video`;
* `association.parentMessageId`: the `id` of the standard-quality message; and
* `quality`: `hd`.

Show the HD copy in place of the standard message it names, rather than as a
second message. The two events can arrive in either order. If the HD copy
arrives first, keep it until the standard message with that `id` arrives.
`parentMessageId` uses the same identifier as the standard message's `id`, so
you can match them directly.

Polymorfa drops an HD copy whose sender differs from the sender of the message
it names, as WhatsApp does.

## Send images with a preview

When you send an image from a Linked Devices number, Polymorfa adds its width,
height, and a JPEG preview with a longest edge of 100 pixels, as WhatsApp
clients do. Your image is sent unchanged. Images Polymorfa cannot decode, or
larger than 24 megapixels, are sent without the preview.

For video and documents, you can supply your own preview in
`content.video.thumbnail` or `content.file.thumbnail`: a base64-encoded JPEG
of at most 16 KiB. A preview that is not a JPEG or is larger returns `400`
`invalid_parameter`. Official WhatsApp Business numbers ignore these previews.

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

### Image quality

`content.image.quality` accepts `standard` (the default) or `hd`. Polymorfa
does not send HD pairs: a request with `quality: "hd"` sends the image once,
as supplied, exactly like `standard`, and the response has no `hdMessageId`.
`hdMessageId` is present only when an HD copy was sent; `id` always
identifies the standard-quality message.

## Test numbers

Test numbers send and receive the same fields. Images sent from a test number
include their size and a 100-pixel preview, and video and document previews
you supply are delivered to the receiving test number.


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