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

## Download media

**API:**

Download a received file with
[Download linked media](https://docs.polymorfa.com/api/media/download-linked-media), using a
credential with `media:read`. The response is the file, or a redirect to it.

```bash cURL
curl -L "https://api.polymorfa.com/messaging/media/$MEDIA_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -o attachment.bin
```

```typescript TypeScript
const download = await messaging.media.downloadStream("<media-id>");
console.log(download.contentType, download.filename);
```

```bash 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
```

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Supported.

[Get media](https://docs.polymorfa.com/api/graph/media/get-media) returns Meta's media
metadata, with `url`, `mime_type`, `sha256` and `file_size`, and
[Download uploaded media](https://docs.polymorfa.com/api/graph/media/download-uploaded-media)
returns the bytes. Both need `media:read`.

*TypeScript:*

`download.body` is a `ReadableStream<Uint8Array>`; read it once. In Node.js,
write it straight to a file. The helper writes to a temporary file and moves it
into place only after the download finishes:

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

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

Treat `filename` as a display name, not a path. When a project does not store
media, inbound media events carry an encrypted `media` descriptor instead, and
`messaging.media.downloadFromWhatsApp(event.payload)` downloads and decrypts the
file from WhatsApp without calling the Polymorfa API. The descriptor contains
a decryption key, so never log stored event bodies.

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

## See also

- [Send messages](https://docs.polymorfa.com/messaging/send#media)
- [Receive messages](https://docs.polymorfa.com/messaging/receive)

[Stickers and sticker packs](https://docs.polymorfa.com/messaging/stickers) covers the candidate operations, conversion limits and availability.
