Toolkit · MessageBuilder

Overview

Toolkit does not need instantiation. Every method is called on the class and holds no state. Builders use it internally, but you can call it directly when you need more control.

Media

resolve, resize, upload

Text

hyperlinks, citations, latex

Video

duration, thumbnails

extractIE

static

Toolkit.extractIE(text, options)

Parses a custom markdown dialect to extract inline entities: hyperlinks, citations, and LaTeX images. Used internally by addText and addTable.

Parameter

Parameter	Type	Default	Description
`text`required	string	—	Source text.
`options.extract`	boolean	true	When false, return the text unchanged without parsing.
`options.hyperlink`	boolean	true	Enable [label](url) parsing.
`options.citation`	boolean	true	Enable [](url) parsing.
`options.latex`	boolean	true	Enable [text\|w\|h\|fh\|pad]<url> parsing.

Return{ text: string, ie: object[], inline_entities: object[] }

Prefix a URL with ! to mark an untrusted hyperlink: [Name](!https://url).
Citations use an empty label: [](https://url).

const result = Toolkit.extractIE(
  'Read the [documentation](https://example.com) and [](https://source.com)'
);

console.log(result.text); // text with placeholders
console.log(result.inline_entities);

resize

asyncstatic

Toolkit.resize(buffer, x, y, fit)

Resizes an image buffer using sharp. Output is always PNG with a transparent background and center crop.

Parameter

Parameter	Type	Default	Description
`buffer`required	Buffer	—	Source image buffer.
`x`required	number	—	Target width.
`y`required	number	—	Target height.
`fit`	string	'cover'	Sharp fit mode: cover, contain, fill, inside, outside.

ReturnPromise<Buffer>

waitAllPromises

asyncstatic

Toolkit.waitAllPromises(input)

Recursively resolves promises nested inside objects and arrays. Used during build to await resolveMedia results.

Parameter

Parameter	Type	Default	Description
`input`required	any	—	A value that may contain nested promises.

ReturnPromise<any>

fetchBuffer

asyncstatic

Toolkit.fetchBuffer(url, options, config)

Downloads URL content into a Buffer using native fetch.

Parameter

Parameter	Type	Default	Description
`url`required	string	—	Source URL.
`options`	object	{}	Native fetch options.
`config.silent`	boolean	true	When false, errors are thrown; when true, an empty buffer is returned.

ReturnPromise<Buffer>

toUrl

asyncstatic

Toolkit.toUrl(_client, path, mediaType)

Uploads a buffer or path to WhatsApp servers through prepareWAMessageMedia and returns the CDN URL.

Parameter

Parameter	Type	Default	Description
`_client`required	WASocket	—	Baileys socket.
`path`required	string \| Buffer	—	Media source.
`mediaType`	string	'document'	image, video, audio, document, or sticker.

ReturnPromise<string>

resolveMedia

asyncstatic

Toolkit.resolveMedia(_client, media, mediaType, options)

The core media normalizer: accepts a URL, Buffer, base64, or array; reuploads when requested; and returns a URL, buffer, or base64 value.

Parameter

Parameter	Type	Default	Description
`_client`required	WASocket	—	Baileys socket.
`media`required	string \| Buffer \| Array	—	Source media.
`mediaType`	string	'image'	Media type.
`options.resolveUrl`	boolean	false	Force fetch and reupload for non-WhatsApp URLs.
`options.resolveWAUrl`	boolean	false	Force download and reupload for *.whatsapp.net URLs.
`options.result`	string	'url'	url, buffer, or base64.
`options.resize`	boolean	false	Resize before returning (requires result other than url).
`options.width`	number	300	Resize width.
`options.height`	number	300	Resize height.

ReturnPromise<string | Buffer | Array>

Arrays are processed in parallel with Promise.all, recursively.
*.whatsapp.net URLs are used directly unless resolveWAUrl is true.
Buffers are uploaded through toUrl unless result is buffer or base64.

getMp4Duration

static

Toolkit.getMp4Duration(buffer, options)

Reads video duration from the MP4 atom structure (moov → mvhd) without external dependencies.

Parameter

Parameter	Type	Default	Description
`buffer`required	Buffer	—	MP4 video buffer.
`options.silent`	boolean	true	When false, parsing errors are thrown; when true, return 0.

Returnnumber

getMp4Preview

asyncstatic

Toolkit.getMp4Preview(videoBuffer, options)

Extracts one video frame as a PNG thumbnail using fluent-ffmpeg.

Parameter

Parameter	Type	Default	Description
`videoBuffer`required	Buffer	—	Video buffer.
`options.time`	number	20% of duration (max 10s)	Frame capture time.
`options.result`	string	'buffer'	buffer or base64.
`options.resize`	boolean	true	Resize the result.
`options.width`	number	300	Target width.
`options.height`	number	300	Target height.
`options.silent`	boolean	true	Ignore errors and return null.

ReturnPromise<Buffer | string>

stringifyEscaped

static

Toolkit.stringifyEscaped(obj)

JSON.stringify with unicode escaping for every non-ASCII character. Used when building the AIRich unifiedResponse payload.

Parameter

Parameter	Type	Default	Description
`obj`required	object	—	Object to serialize.

Returnstring

Media example

An explicit flow from a source URL to a message header.

media.js

import { Toolkit } from './lib/MessageBuilder.js';

// 1. Fetch an image from a URL
const buffer = await Toolkit.fetchBuffer('https://example.com/cover.jpg');

// 2. Resize to 300x300 PNG
const resized = await Toolkit.resize(buffer, 300, 300, 'cover');

// 3. Upload to WhatsApp servers
const url = await Toolkit.toUrl(sock, resized, 'image');

// 4. Use it in a message
await new Button(sock)
  .setImage(url)
  .setBody('New cover')
  .addReply('OK', 'ok')
  .send(jid);

Read video metadata without uploading again:

video.js

const duration = Toolkit.getMp4Duration(videoBuffer); // seconds

const thumb = await Toolkit.getMp4Preview(videoBuffer, {
  time: Math.min(duration * 0.2, 10),
  width: 300,
  height: 300,
  result: 'buffer',
});

Notes

Static API

Every Toolkit method is called on the class, not an instance. There is no internal state.

sharp and ffmpeg

resize requires sharp; getMp4Preview requires fluent-ffmpeg. Make sure both are installed in your bot runtime.

Network failures

fetchBuffer is silent by default: network errors return an empty buffer. Set { silent: false } when you need to catch errors.