Media utility functions handle all aspects of media messages including downloading, encryption, thumbnail generation, and media upload preparation.
Downloads media from a WhatsApp message.
export const downloadMediaMessage = async <Type extends 'buffer' | 'stream'>(
message: WAMessage,
type: Type,
options: MediaDownloadOptions,
ctx?: DownloadMediaMessageContext
): Promise<Type extends 'buffer' ? Buffer : Transform>
The message containing media to download
type
'buffer' | 'stream'
required
Whether to return a Buffer or a Stream
options
MediaDownloadOptions
required
Download options including byte range
ctx
DownloadMediaMessageContext
Context with reupload request handler and logger
Start byte for partial download
End byte for partial download
Fetch options for the download request
Downloaded media as Buffer (type=‘buffer’) or Stream (type=‘stream’)
import { downloadMediaMessage } from '@whiskeysockets/baileys'
import fs from 'fs'
// Download as buffer
const buffer = await downloadMediaMessage(
message,
'buffer',
{ }
)
fs.writeFileSync('image.jpg', buffer)
// Download as stream
const stream = await downloadMediaMessage(
message,
'stream',
{ }
)
stream.pipe(fs.createWriteStream('video.mp4'))
// Partial download
const partialBuffer = await downloadMediaMessage(
message,
'buffer',
{
startByte: 0,
endByte: 1024 // Download first 1KB
}
)
// With reupload context
const bufferWithRetry = await downloadMediaMessage(
message,
'buffer',
{ },
{
reuploadRequest: async (msg) => {
// Request media re-upload from sender
return await sock.reuploadRequest(msg)
},
logger: myLogger
}
)
- To download images, videos, audio, documents from messages
- For saving media to disk
- When processing media files (thumbnails, transcoding, etc.)
- Automatically handles media decryption
downloadContentFromMessage
Downloads and decrypts media content from a downloadable message.
export const downloadContentFromMessage = async (
{ mediaKey, directPath, url }: DownloadableMessage,
type: MediaType,
opts?: MediaDownloadOptions
): Promise<Transform>
message
DownloadableMessage
required
Object containing mediaKey, directPath, and/or url
Type of media: ‘image’, ‘video’, ‘audio’, ‘document’, ‘sticker’, etc.
import { downloadContentFromMessage } from '@whiskeysockets/baileys'
const msg = message.message.imageMessage
const stream = await downloadContentFromMessage(
{
mediaKey: msg.mediaKey,
directPath: msg.directPath,
url: msg.url
},
'image'
)
const buffers = []
for await (const chunk of stream) {
buffers.push(chunk)
}
const buffer = Buffer.concat(buffers)
- For lower-level media downloading
- When you have the media message properties directly
- For streaming large files
encryptedStream
Encrypts media for upload to WhatsApp servers.
export const encryptedStream = async (
media: WAMediaUpload,
mediaType: MediaType,
options?: EncryptedStreamOptions
): Promise<{
mediaKey: Buffer
encFilePath: string
originalFilePath?: string
mac: Buffer
fileEncSha256: Buffer
fileSha256: Buffer
fileLength: number
}>
Media to encrypt (Buffer, Stream, or URL object)
Type of media being encrypted
EncryptedStreamOptions
options.saveOriginalFileIfRequired
Whether to save the original unencrypted file
Fetch options if media is a URL
Object containing encryption keys, file paths, hashes, and file length
import { encryptedStream } from '@whiskeysockets/baileys'
import fs from 'fs'
// Encrypt from buffer
const buffer = fs.readFileSync('image.jpg')
const encrypted = await encryptedStream(
buffer,
'image',
{ logger: myLogger }
)
console.log(encrypted.mediaKey) // Encryption key
console.log(encrypted.encFilePath) // Path to encrypted file
console.log(encrypted.fileSha256) // SHA256 of original
console.log(encrypted.fileEncSha256) // SHA256 of encrypted
// Encrypt from URL
const encryptedFromUrl = await encryptedStream(
{ url: 'https://example.com/image.jpg' },
'image'
)
// Encrypt from stream
const stream = fs.createReadStream('video.mp4')
const encryptedStream = await encryptedStream(
{ stream },
'video',
{ saveOriginalFileIfRequired: true }
)
console.log(encryptedStream.originalFilePath) // Saved original file
- Before uploading media to WhatsApp
- Automatically called by
sendMessage with media
- For manual media upload workflows
generateThumbnail
Generates a JPEG thumbnail for images or videos.
export async function generateThumbnail(
file: string,
mediaType: 'video' | 'image',
options: { logger?: ILogger }
): Promise<{
thumbnail?: string
originalImageDimensions?: { width: number; height: number }
}>
mediaType
'video' | 'image'
required
Type of media
Options with optional logger
Object with base64 thumbnail and original dimensions (for images)
import { generateThumbnail } from '@whiskeysockets/baileys'
// Generate image thumbnail
const { thumbnail, originalImageDimensions } = await generateThumbnail(
'/path/to/image.jpg',
'image',
{ logger: myLogger }
)
console.log(thumbnail) // Base64 encoded JPEG thumbnail
console.log(originalImageDimensions) // { width: 1920, height: 1080 }
// Generate video thumbnail
const { thumbnail: videoThumb } = await generateThumbnail(
'/path/to/video.mp4',
'video',
{ logger: myLogger }
)
console.log(videoThumb) // Base64 thumbnail from video frame
- Automatically used when sending images/videos
- For generating preview thumbnails
- Requires ffmpeg for video thumbnails
- Requires sharp or jimp for image thumbnails
getAudioDuration
Gets the duration of an audio file in seconds.
export async function getAudioDuration(
buffer: Buffer | string | Readable
): Promise<number | undefined>
buffer
Buffer | string | Readable
required
Audio file as Buffer, file path string, or Readable stream
Audio duration in seconds
import { getAudioDuration } from '@whiskeysockets/baileys'
import fs from 'fs'
// From buffer
const buffer = fs.readFileSync('audio.mp3')
const duration = await getAudioDuration(buffer)
console.log(`Duration: ${duration} seconds`)
// From file path
const duration2 = await getAudioDuration('/path/to/audio.mp3')
// From stream
const stream = fs.createReadStream('audio.ogg')
const duration3 = await getAudioDuration(stream)
- Automatically used when sending audio messages
- For displaying audio duration in UI
- Requires music-metadata package
Prepares raw media data for upload (used for newsletters).
export const getRawMediaUploadData = async (
media: WAMediaUpload,
mediaType: MediaType,
logger?: ILogger
): Promise<{
filePath: string
fileSha256: Buffer
fileLength: number
}>
Media to prepare (Buffer, Stream, or URL)
Object with file path, SHA256 hash, and file length
import { getRawMediaUploadData } from '@whiskeysockets/baileys'
import fs from 'fs'
const buffer = fs.readFileSync('image.jpg')
const uploadData = await getRawMediaUploadData(
buffer,
'image',
logger
)
console.log(uploadData.filePath) // Temp file path
console.log(uploadData.fileSha256) // SHA256 hash
console.log(uploadData.fileLength) // File size in bytes
// Use for newsletter upload
const { mediaUrl, directPath } = await sock.newsletterUpload(
uploadData.filePath,
{
fileEncSha256B64: uploadData.fileSha256.toString('base64'),
mediaType: 'image'
}
)
- When uploading media to newsletters
- For unencrypted media uploads
- Automatically used internally for newsletter messages
generateProfilePicture
Generates a profile picture by resizing and cropping an image.
export const generateProfilePicture = async (
mediaUpload: WAMediaUpload,
dimensions?: { width: number; height: number }
): Promise<{ img: Buffer }>
Image to process (Buffer, Stream, or URL)
dimensions
{ width: number; height: number }
Target dimensions (default: 640x640)
Processed profile picture as JPEG buffer
import { generateProfilePicture } from '@whiskeysockets/baileys'
import fs from 'fs'
const buffer = fs.readFileSync('photo.jpg')
const { img } = await generateProfilePicture(buffer)
// Update profile picture
await sock.updateProfilePicture(sock.user.id, img)
// Custom dimensions
const { img: smallImg } = await generateProfilePicture(
buffer,
{ width: 320, height: 320 }
)
- When updating profile pictures
- Automatically resizes and crops to square
- Requires sharp or jimp library