Skip to content

fix: use newsletter media types for channel media downloads#201709

Open
themazim wants to merge 2 commits intowwebjs:mainfrom
themazim:fix/newsletter-media-download
Open

fix: use newsletter media types for channel media downloads#201709
themazim wants to merge 2 commits intowwebjs:mainfrom
themazim:fix/newsletter-media-download

Conversation

@themazim
Copy link
Copy Markdown
Contributor

Description

WhatsApp Web uses separate, unencrypted media types for newsletter/channel content (e.g. newsletter-image instead of image). The downloadMedia() method was passing the regular msg.type to downloadAndMaybeDecrypt, which caused failures for newsletter messages because:

  1. Newsletter media is unencrypted, so mediaKey may be null — but the old code required both directPath and mediaKey for direct downloads.
  2. Wrong media type: Passing type: "image" instead of type: "newsletter-image" made the download manager select encrypted download entries for unencrypted content, resulting in 404 errors or decryption failures.
  3. Internal resolve crashes: The internal msg.downloadMedia() call crashes for newsletter JIDs because getMaybeChat() returns null (newsletter JIDs are not in ChatCollection).

Fix

Uses WA Web's own internal functions to handle newsletter media correctly:

  • WAWebMmsMediaTypes.getMsgMediaType(msg) — computes the correct newsletter-prefixed media type (e.g. newsletter-image, newsletter-video, newsletter-gif)
  • WAWebMediaCryptoEligibilityUtils.isMediaCryptoExpectedForMediaType(mediaType) — determines whether mediaKey is actually required for the given type

For unencrypted newsletter media, directPath alone is now sufficient to attempt the download. The internal msg.downloadMedia() resolve is skipped for non-chat JIDs (@newsletter, @broadcast) since it cannot resolve these.

Behavior changes

  • Newsletter/channel image, video, audio, sticker, ptt, and ptv downloads now work correctly
  • Regular (non-newsletter) media downloads are completely unaffected — getMsgMediaType returns the same type as msg.type for regular messages, and isMediaCryptoExpected returns true, preserving the existing directPath + mediaKey requirement
  • No changes to the returned MessageMedia object — returns still use type: "image" and mimetype: "image/jpeg", the newsletter-prefixed type is only used internally for the download call

Related Issue(s)

Testing Summary

Test Details

  • subscribed to channel and waited for a message with media.
  • Verified channel messages can download media as expected
  • Confirmed regular chat media downloads remain unaffected

Environment

  • Machine OS: Ubuntu 24.04
  • Phone OS: Android 14
  • Library Version: latest (main)
  • WhatsApp Web Version: 2.3000.1036680724
  • Browser Type and Version: Chrome (headless)
  • Node Version: 22.14.0

Type of Change

  • Dependency change (package changes such as removals, upgrades, or additions)
  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Non-code change (documentation, README, etc.)

Checklist

  • My code follows the style guidelines of this project.
  • All new and existing tests pass (npm test).
  • Typings (e.g. index.d.ts) have been updated if necessary.
  • Usage examples (e.g. example.js) / documentation have been updated if applicable.

@github-actions github-actions bot added the api changes API modifications label Apr 10, 2026
WhatsApp Web uses separate, unencrypted media types for newsletter/channel
content (e.g. "newsletter-image" instead of "image"). The downloadMedia()
method was passing the regular msg.type to downloadAndMaybeDecrypt, which
caused failures for newsletter messages because:

1. Newsletter media is unencrypted, so mediaKey may be null — but the old
   code required both directPath and mediaKey for direct downloads.
2. Passing type "image" instead of "newsletter-image" made the download
   manager select encrypted download entries for unencrypted content.
3. The internal msg.downloadMedia() resolve crashes for newsletter JIDs
   because getMaybeChat() returns null (not in ChatCollection).

Fix by using WA Web's own getMsgMediaType() to compute the correct
newsletter-prefixed type, and isMediaCryptoExpectedForMediaType() to
determine whether mediaKey is actually required. For unencrypted newsletter
media, directPath alone is now sufficient to attempt the download.
@themazim themazim force-pushed the fix/newsletter-media-download branch from 662c99a to 27d627b Compare April 10, 2026 08:38
@BenyFilho BenyFilho added the waiting for testers Needs testing label Apr 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api changes API modifications waiting for testers Needs testing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants