Skip to main content
Baileys accepts media in three forms via the WAMediaUpload type: a raw Buffer, a { url: '...' } object pointing to a remote or local path, or a { stream: Stream } object backed by a Node.js Readable. All three forms work identically across image, video, audio, document, and sticker messages.
Prefer { url } or { stream } over a raw Buffer. When you pass a URL, Baileys never loads the entire file into memory — it encrypts and streams the media directly to WhatsApp’s servers, which significantly reduces RAM usage for large files.

Sending media

Image message

Video message

Set ptv: true to send the video as a video note (circle video).

GIF message

WhatsApp does not support .gif files. Send GIFs as .mp4 videos with the gifPlayback flag set to true.

Audio message

For audio to play correctly across all devices, convert your file with ffmpeg before sending. The key flags are libopus codec, single channel (-ac 1), and avoid_negative_ts make_zero.
The required ffmpeg flags are:
  • codec: libopus — produces an .ogg file
  • ac: 1 — single audio channel
  • avoid_negative_ts make_zero — fixes timestamp issues

View-once message

Add viewOnce: true to any media content object to make the message self-destruct after the recipient views it. This works with images, videos, and audio.

Thumbnail generation

Baileys generates thumbnails automatically when optional peer dependencies are present: Without these dependencies, thumbnails are omitted and messages still send successfully.

Downloading received media

Use downloadMediaMessage to save incoming media. Pass 'stream' as the second argument to get a Readable (recommended for large files), or 'buffer' to get the full file as a Buffer. Pass reuploadRequest: sock.updateMediaMessage so Baileys can automatically re-request media that has expired from WhatsApp’s servers.

Re-uploading old media

WhatsApp automatically removes media from its servers after a period of time. If a device still has the original file, it can re-upload it so other devices can download it again. Call updateMediaMessage with the message object to trigger a re-upload request:
Passing reuploadRequest: sock.updateMediaMessage to downloadMediaMessage handles this automatically — Baileys retries the download after requesting a re-upload when it receives a 404 or 410 HTTP error from WhatsApp’s media servers.