Skip to content
MessageBuilder
DocsBuildersEnumsPlayground
InstallationError classes
Documentation menu
Introduction

Introduction

MessageBuilder.js is an interactive WhatsApp message builder for Baileys with fluent chaining.

Getting started
v4.8/Baileys runtime
On this page

On this page

MessageBuilder.js is a small library for composing interactive WhatsApp messages without writing Baileys payloads by hand. Every builder uses fluent chaining: each setter and adder returns this, so a whole message can be built in one expression.

It does not replace Baileys. It works on top of @whiskeysockets/baileys and handles the parts that are usually painful: interactiveMessage structure, media headers, native flow nodes, and rich responses that carry two payload representations.

Status: version 4.8, created by Nixel, with contributions from Ahmad tumbuh kembang and popioo. The internal structure comes from reverse-engineering the WhatsApp schema and may change at any time.

Five core classes, one pattern

Class Payload Purpose
Button interactiveMessage + native flow Modern buttons: quick reply, CTA, copy, call, reminder, address, location, list.
ButtonV2 buttonsMessage Legacy format, up to three simple quick replies.
Carousel interactiveMessage.carouselMessage Horizontal cards with required media on every card.
AIRich richResponseMessage AI-style rich responses: text, code, tables, media, products, posts, widgets.
Toolkit — Static utilities for media, text, and MP4 metadata.

Button, ButtonV2, Carousel, and AIRich inherit from BaseBuilder, so setBody(), setFooter(), setContextInfo(), and addPayload() are available on all of them. Toolkit is standalone and exposes only static methods.

A quick example

import { Button } from './MessageBuilder.js';

const button = new Button(sock)
  .setBody('Pick an option below.')
  .setFooter('MessageBuilder v4.8')
  .addReply('Hello', 'hello')
  .addUrl('Open website', 'https://example.com', true);

await button.send('[email protected]');

Three things to keep in mind:

  1. sock must be a connected Baileys instance.
  2. jid is a destination JID, not a raw phone number.
  3. send() builds and sends. Use build() when you only want the payload.

Which builder should I use?

  • Menus, confirmations, and CTAs → Button.
  • Many nested options → Button with addSelection().
  • Visual catalogs → Carousel.
  • AI answers, reports, or mixed content → AIRich.
  • Older clients without native flow support → ButtonV2, with feature compromises.

Important: WhatsApp limits the number of buttons and the size of content. Test on target devices. Do not rely on undocumented client behavior.

Library design principles

  • Chainable — setters and adders return this.
  • Stateful — builders keep state until build() is called.
  • Media-aware — URLs, buffers, and base64 are normalized before sending.
  • Fallback-first — AIRich includes submessages so content remains readable on clients without rich response support.
  • Does not hide Baileys — build() returns a normal WAMessage, and send() uses relayMessage().

Known limitations

  • Not an official WhatsApp API. Schema changes can break payloads.
  • Some features only render in specific WhatsApp versions.
  • sharp and fluent-ffmpeg are required for image resizing and video thumbnails.
  • Rich responses use generated verification metadata; this is not official Meta bot verification.

Continue with Installation to set up dependencies, or jump to Quickstart if you already have a Baileys project.