Message Generation
generateWAMessage
Generates a complete WhatsApp message with all metadata.
async function generateWAMessage(
jid: string,
content: AnyMessageContent,
options: MessageGenerationOptions
): Promise<WAMessage>
Recipient JID (chat identifier)
content
AnyMessageContent
required
Message content - can be text, media, location, contact, etc.
{ text: string } - Text message{ image: WAMediaUpload } - Image message{ video: WAMediaUpload } - Video message{ audio: WAMediaUpload } - Audio message{ document: WAMediaUpload } - Document message{ sticker: WAMediaUpload } - Sticker message{ location: LocationMessage } - Location share{ contacts: ContactsArrayMessage } - Contact card{ poll: PollMessage } - Poll message{ react: ReactionMessage } - Reaction to message
options
MessageGenerationOptions
required
Message generation options
Your JID (user identifier)
upload
WAMediaUploadFunction
required
Function to upload media files
Message to quote/reply to
Disappearing message timer (in seconds)
Custom message ID (auto-generated if not provided)
Complete WhatsApp message ready to send
const msg = await generateWAMessage(
'[email protected]',
{ text: 'Hello!' },
{
userJid: sock.user.id,
upload: sock.waUploadToServer,
logger
}
)
generateWAMessageContent
Generates the content portion of a WhatsApp message.
async function generateWAMessageContent(
message: AnyMessageContent,
options: MessageContentGenerationOptions
): Promise<WAMessageContent>
message
AnyMessageContent
required
Raw message content to generate
options
MessageContentGenerationOptions
required
Content generation options including upload function and media cache
Generated message content ready for protobuf encoding
generateWAMessageFromContent
Generates a WAMessage from already-prepared message content.
function generateWAMessageFromContent(
jid: string,
message: WAMessageContent,
options: MessageGenerationOptionsFromContent
): WAMessage
Pre-generated message content
options
MessageGenerationOptionsFromContent
required
Options including userJid, timestamp, quoted message, and ephemeral settings
Complete WAMessage with key and metadata
Downloads media from a message. Supports automatic re-upload requests on failure.
async function downloadMediaMessage<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 Stream
options
MediaDownloadOptions
required
Download options
Start downloading from specific byte (for partial downloads)
Stop downloading at specific byte
ctx
DownloadMediaMessageContext
Optional context for automatic re-upload requests
Function to request media re-upload from sender
Downloaded media as Buffer or Stream depending on type parameter
When a 404 or 410 error occurs, the function automatically requests re-upload from the sender if context is provided.
// Download as buffer
const buffer = await downloadMediaMessage(
message,
'buffer',
{},
{ reuploadRequest: sock.updateMediaMessage, logger }
)
await fs.writeFile('media.jpg', buffer)
// Download as stream
const stream = await downloadMediaMessage(message, 'stream', {})
stream.pipe(fs.createWriteStream('media.jpg'))
Prepares media for sending by encrypting and uploading it.
async function prepareWAMessageMedia(
message: AnyMediaMessageContent,
options: MessageContentGenerationOptions
): Promise<WAMessageContent>
message
AnyMediaMessageContent
required
Media message content to prepare
{ image: WAMediaUpload, caption?: string }{ video: WAMediaUpload, caption?: string, ptv?: boolean }{ audio: WAMediaUpload, ptt?: boolean }{ document: WAMediaUpload, fileName?: string, mimetype?: string }{ sticker: WAMediaUpload }
options
MessageContentGenerationOptions
required
Options including upload function, media cache, and logger
Prepared message content with encrypted media URL
- Automatic thumbnail generation for images and videos
- Audio duration detection
- Waveform generation for voice messages (ptt)
- Media caching to avoid re-uploads
- Encryption and hashing
Message Helpers
getContentType
Extracts the content type key from a message.
function getContentType(
content: proto.IMessage | undefined
): keyof proto.IMessage | undefined
Message content to analyze
The key representing the message type (e.g., ‘conversation’, ‘imageMessage’, ‘videoMessage’)
const msgType = getContentType(message.message)
// Returns: 'conversation', 'imageMessage', 'videoMessage', etc.
normalizeMessageContent
Normalizes ephemeral and view-once messages to regular content.
function normalizeMessageContent(
content: WAMessageContent | null | undefined
): WAMessageContent | undefined
Message content to normalize
Unwrapped message content (extracts inner message from ephemeral/viewOnce wrappers)
const normalized = normalizeMessageContent(message.message)
// Extracts actual content from ephemeralMessage, viewOnceMessage, etc.
Extracts the true message content, including from template messages.
function extractMessageContent(
content: WAMessageContent | undefined | null
): WAMessageContent | undefined
Extracted core message content
getDevice
Predicts the device type based on message ID pattern.
function getDevice(id: string): 'ios' | 'web' | 'android' | 'desktop' | 'unknown'
Detected device type based on ID pattern
const device = getDevice(message.key.id)
// Returns: 'ios', 'android', 'web', 'desktop', or 'unknown'
generateForwardMessageContent
Generates content for forwarding a message.
function generateForwardMessageContent(
message: WAMessage,
forceForward?: boolean
): WAMessageContent
Force showing as forwarded even if from you (default: false)
Message content configured for forwarding with incremented forwarding score
const forwardContent = generateForwardMessageContent(originalMessage)
await sock.sendMessage(recipientJid, forwardContent)
Message Aggregation
getAggregateVotesInPollMessage
Aggregates all votes in a poll message.
function getAggregateVotesInPollMessage(
message: Pick<WAMessage, 'pollUpdates' | 'message'>,
meId?: string
): Array<{ name: string; voters: string[] }>
Poll message with updates
List of poll options with their voters
Array of JIDs who voted for this option
updateMessageWithReaction
Updates a message with a new reaction.
function updateMessageWithReaction(
msg: Pick<WAMessage, 'reactions'>,
reaction: proto.IReaction
): void
Message to update (mutated in place)
Reaction data to add/update
updateMessageWithPollUpdate
Updates a message with a new poll vote.
function updateMessageWithPollUpdate(
msg: Pick<WAMessage, 'pollUpdates'>,
update: proto.IPollUpdate
): void
URL Utilities
Extracts the first URL from text using regex.
function extractUrlFromText(text: string): string | undefined
First URL found in the text, or undefined
const url = extractUrlFromText('Check out https://example.com')
// Returns: 'https://example.com'
generateLinkPreviewIfRequired
Generates link preview metadata if URL is detected.
async function generateLinkPreviewIfRequired(
text: string,
getUrlInfo: (url: string) => Promise<WAUrlInfo>,
logger?: ILogger
): Promise<WAUrlInfo | undefined>
Link preview metadata including title, description, and thumbnail
Media Utilities
Detailed guide on media message handling
Socket Events
Message events and event handling