Rich Media & Link Previews
Relevant source files
The following files were used as context for generating this wiki page:
The Rich Media and Link Previews module provides the logic for handling complex message types beyond simple text. This includes the automated generation of URL previews, the preparation and encryption of media (images, videos, documents), and the construction of "Rich Responses" often associated with AI-driven interactions. These features are essential for creating an interactive user experience, supporting structured data like tables and code blocks, and ensuring that media attachments are correctly formatted and secured for the WhatsApp protocol.
This system is divided into several sub-components: media preparation (encryption and thumbnailing), link preview extraction/metadata fetching, and rich response composition (which utilizes a "Unified Response" format for complex UI primitives).
Media Message Preparation
Media preparation is a multi-step process that ensures content is compatible with WhatsApp's requirements. This involves identifying the media type, generating thumbnails, computing durations (for audio/video), and performing encryption before upload.
Core Logic and Processing
The prepareWAMessageMedia function serves as the primary entry point for media handling. It performs the following operations:
- Type Identification: Detects if the message is an image, video, audio, document, or sticker based on predefined keys.
- Caching: Uses a
mediaCacheto avoid re-processing identical media content by generating a cache key from the media URL or object. - Newsletter Handling: Messages sent to Newsletters use a "raw" upload path via
getRawMediaUploadDatawhich skips certain encryption steps required for standard chats. - Encryption: Standard media undergoes
encryptedStreamprocessing, producing a media key, file hashes (SHA256), and an encrypted file path. - Thumbnail & Metadata: Triggers
generateThumbnailfor images/videos andgetAudioDurationorgetAudioWaveformfor audio files.
Sources: lib/Utils/messages.js:61-197, lib/Utils/messages.js:25-33
Media Flow Diagram
The following diagram illustrates the lifecycle of a media attachment from input to the generation of a protocol-ready message object.
This diagram shows the branching logic between standard encrypted chats and newsletter media delivery.
Sources: lib/Utils/messages.js:61-197
Link Preview Generation
Link previews are automatically generated when a text message contains a URL. This process requires fetching metadata from the target website and generating a compact preview for the recipient.
Extraction and Retrieval
The process begins with extractUrlFromText, which uses a regex (defined in defaults) to find the first URL in a string. If a URL is found and the getUrlInfo option is provided, the system attempts to fetch the site's metadata.
The getUrlInfo function (located in link-preview.js) performs the following:
- Redirection Handling: Follows redirects (up to 5 levels) while ensuring security constraints.
- Metadata Extraction: Retrieves the title, description, and primary image from the target URL.
- Thumbnail Processing: If an image is found, it is either uploaded to WhatsApp servers via
prepareWAMessageMedia(to get ahighQualityThumbnail) or compressed into a low-resolution JPEG buffer usingextractImageThumb.
Sources: lib/Utils/messages.js:46-59, lib/Utils/link-preview.js:37-97
Link Preview Metadata Fields
| Field | Type | Description |
|---|---|---|
canonical-url | String | The final resolved URL after redirects. |
matched-text | String | The exact text snippet that matched the URL regex. |
title | String | The title of the webpage. |
description | String | A brief summary or meta-description of the page. |
jpegThumbnail | Buffer | A small JPEG preview image (max 192px width). |
highQualityThumbnail | Object | Full ImageMessage metadata including direct path and keys. |
Sources: lib/Utils/link-preview.js:83-91, lib/Utils/messages.js:370-385
AI-Rich Responses and Unified UI
"Rich Responses" represent a advanced UI framework, typically used by Meta AI, allowing for structured content like code snippets, tables, and LaTeX expressions to be rendered within the chat.
Composition Architecture
Rich messages are constructed by wrapping "Submessages" into a richResponseMessage, which is then nested inside a botForwardedMessage. A critical component of this is the unifiedResponse, which contains a Base64-encoded JSON payload of "UX Primitives".
Key Primitive Types:
- GenAIMarkdownTextUXPrimitive: Renders markdown text with potential inline entities (links, citations).
- GenATableUXPrimitive: Renders structured tables with headers and cells.
- GenAICodeUXPrimitive: Renders syntax-highlighted code blocks.
- GenAIImaginePrimitive: Renders images or videos generated via AI.
Sources: lib/Utils/rich-message-utils.js:45-98, lib/Utils/message-composer.js:525-585
Code Tokenization Logic
The system includes a custom tokenizer to support syntax highlighting. The tokenizeCode function breaks down source code into blocks categorized by CodeHighlightType.
| Highlight Type | Integer Value | Description |
|---|---|---|
| DEFAULT | 0 | Standard text or whitespace. |
| KEYWORD | 1 | Language-specific keywords (e.g., const, if). |
| METHOD | 2 | Function calls or method names. |
| STRING | 3 | Text literals enclosed in quotes. |
| NUMBER | 4 | Numeric literals. |
| COMMENT | 5 | Code comments starting with // or #. |
Sources: lib/Utils/message-composer.js:55-73, lib/Utils/rich-message-utils.js:15-43
Rich Message Construction Flow
This diagram shows how various utilities collaborate to transform structured input into a protocol-compliant rich message.
Sources: lib/Utils/rich-message-utils.js:100-244, lib/Utils/message-composer.js:587-595
Interactive Media and Carousels
Interactive media encompasses messages that combine media headers with clickable components like buttons, native flow actions, or carousel cards.
Carousel Messages
Carousels are composed of a series of InteractiveMessage cards. Each card must contain a media attachment (image, video, or product) in its header. The Carousel class in MessageBuilder.js validates that every card has a media attachment before sending.
Native Flow Buttons
The system supports converting shorthand button objects into the WhatsApp-compatible buttonParamsJson format. Supported types include:
- quick_reply: Simple ID-based responses.
- cta_url: External web links (supports webview mode).
- cta_copy: One-tap text copying.
- single_select: Traditional list-style selection within a button.
Sources: lib/Utils/messages.js:283-363, assets/buttonsbuilder/MessageBuilder.js:1152-1196, lib/Utils/interactive-message.js:106-124
Conclusion
The Rich Media and Link Previews module is a comprehensive suite of utilities that bridges the gap between raw data and the advanced UI capabilities of the WhatsApp platform. By automating media encryption, metadata extraction for links, and the generation of AI-style rich primitives, it allows developers to send highly structured and interactive content while maintaining protocol compliance and security.
Sources: lib/Utils/messages.js, lib/Utils/rich-message-utils.js, assets/buttonsbuilder/MessageBuilder.js