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. |
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.
{
"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_imageorhd_video;association.parentMessageId: theidof the standard-quality message; andquality: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.
{
"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, using a credential with media:read. The response is the file, or a redirect to it.
curl -L "https://api.polymorfa.com/messaging/media/$MEDIA_ID" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-o attachment.binconst download = await messaging.media.downloadStream("<media-id>");
console.log(download.contentType, download.filename);# 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:
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:
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#
Stickers and sticker packs covers the candidate operations, conversion limits and availability.