malvin-btns

A powerful, production-ready interactive button plugin for the Baileys WhatsApp library.

Send interactive buttons, quick replies, URL buttons, copy buttons, call buttons, and single-select menus — with optional image headers — without touching Baileys core files.

The Problem

By default, WhiskeySockets/Baileys cannot send interactive buttons. The root cause is that Baileys lacks the required binary node wrappers (biz, interactive, native_flow) that WhatsApp expects for interactive messages.

The Solution

malvin-btns fills the gap by:

1. Detecting button messages using WhatsApp's expected format
2. Converting simple button definitions to the correct protobuf structure
3. Injecting missing binary nodes (biz, interactive, native_flow, bot) via additionalNodes
4. Automatically handling private vs. group chat requirements
5. Processing images - automatically downloads, encrypts, and uploads images to WhatsApp's CDN

No core file edits. No monkey-patching. Just drop it in and go.

Features

| Feature | Status | |---|---| | No modifications to Baileys core | ✅ | | Automatic binary node injection | ✅ | | Private chat support (bot node with biz_bot: '1') | ✅ | | Group chat support (biz node only) | ✅ | | Quick reply buttons | ✅ | | URL, Copy, Call CTA buttons | ✅ | | Single-select menus | ✅ | | Send location button | ✅ | | Image header support (auto-upload & encryption) | ✅ | | Input validation with detailed errors | ✅ | | Works with multiple Baileys forks | ✅ | | Regular messages pass through unchanged | ✅ |

Installation

npm install malvin-btns

You also need a Baileys package:

# pick one
npm install mrxd-baileys
npm install @whiskeysockets/baileys

Quick Start

const { makeWASocket } = require('mrxd-baileys');
const { sendButtons } = require('malvin-btns');

const sock = makeWASocket({ /* your config */ });

await sendButtons(sock, jid, {
  title: 'Hello there!',
  text: 'Pick an option below',
  footer: 'Powered by malvin-btns',
  buttons: [
    { id: 'help',  text: '🆘 Help'  },
    { id: 'about', text: 'ℹ️ About' },
    {
      name: 'cta_url',
      buttonParamsJson: JSON.stringify({
        display_text: '🌐 Visit Website',
        url: 'https://host.malvintech.sbs'
      })
    }
  ]
});

Image Header Support

Add an image above your buttons by passing an image object. The image is automatically downloaded, encrypted, and uploaded to WhatsApp's CDN — you just provide the URL.

await sendButtons(sock, jid, {
  title: 'Product Showcase',
  text: 'Check out our latest collection',
  image: { url: 'https://example.com/product.jpg' },
  footer: 'Limited time offer',
  buttons: [
    { id: 'shop', text: '🛒 Shop Now' },
    { id: 'details', text: '📋 Details' }
  ]
});

You can also use a local file path or buffer:

// Local file
image: { path: '/path/to/image.jpg' }

// Buffer
image: { buffer: bufferData }

Handling Button Replies

When a user taps a button, WhatsApp sends back the button's id as a regular message:

sock.ev.on('messages.upsert', async ({ messages }) => {
  const msg = messages[0];
  const text =
    msg.message?.conversation ||
    msg.message?.extendedTextMessage?.text || '';

  if (text === 'help') {
    await sock.sendMessage(msg.key.remoteJid, { text: 'How can I help you?' });
  }

  if (text === 'about') {
    await sock.sendMessage(msg.key.remoteJid, { text: 'Made with malvin-btns 🚀' });
  }
});

Button Types

| Name | Purpose | Required buttonParamsJson keys | |---|---|---| | quick_reply | Simple reply that sends its id back | { display_text, id } | | single_select | In-button picker list | { title, sections: [{ title?, rows: [{ id, title, description?, header? }] }] } | | cta_url | Open a URL | { display_text, url, merchant_url? } | | cta_copy | Copy text to clipboard | { display_text, copy_code } | | cta_call | Tap to dial | { display_text, phone_number } | | cta_catalog | Open business catalog | { display_text? } | | send_location | Request user location | { display_text? } |

Advanced Usage

For full control over all button types in one message, use sendInteractiveMessage:

const { sendInteractiveMessage } = require('malvin-btns');

await sendInteractiveMessage(sock, jid, {
  text: 'Advanced button demo',
  footer: 'malvin-btns',
  image: { url: 'https://example.com/header.jpg' },
  interactiveButtons: [
    {
      name: 'quick_reply',
      buttonParamsJson: JSON.stringify({ display_text: 'Reply A', id: 'reply_a' })
    },
    {
      name: 'single_select',
      buttonParamsJson: JSON.stringify({
        title: 'Pick One',
        sections: [{
          title: 'Options',
          rows: [
            { id: 'opt_hello', title: 'Hello', description: 'Say hi' },
            { id: 'opt_bye',   title: 'Bye',   description: 'Say bye' }
          ]
        }]
      })
    }
  ]
});

URL + Copy + Call in One Message

await sendInteractiveMessage(sock, jid, {
  text: 'Contact actions',
  interactiveButtons: [
    {
      name: 'cta_url',
      buttonParamsJson: JSON.stringify({ display_text: '🌐 Docs', url: 'https://host.malvintech.sbs/doc' })
    },
    {
      name: 'cta_copy',
      buttonParamsJson: JSON.stringify({ display_text: '📋 Copy Code', copy_code: 'MALVIN-2025' })
    },
    {
      name: 'cta_call',
      buttonParamsJson: JSON.stringify({ display_text: '📞 Call Support', phone_number: '+1234567890' })
    }
  ]
});

Single-Select Menu

await sendInteractiveMessage(sock, jid, {
  text: 'Choose a plan',
  interactiveButtons: [
    {
      name: 'single_select',
      buttonParamsJson: JSON.stringify({
        title: 'Plans',
        sections: [{
          title: 'Available Plans',
          rows: [
            { id: 'plan_free', title: 'Free',    description: '4,000 requests/day' },
            { id: 'plan_pro',  title: 'Premium', description: 'Unlimited — one-time payment' }
          ]
        }]
      })
    }
  ]
});

Error Handling

const { sendButtons, InteractiveValidationError } = require('malvin-btns');

try {
  await sendButtons(sock, jid, { text: 'Hi', buttons: [] });
} catch (err) {
  if (err instanceof InteractiveValidationError) {
    console.error(err.formatDetailed());
  }
}

How It Works

What You Write

{
  text: 'Hello',
  footer: 'Footer',
  image: { url: 'https://example.com/img.jpg' },
  interactiveButtons: [{ name, buttonParamsJson }, ...]
}

What Gets Sent to WhatsApp

{
  interactiveMessage: {
    header: {
      hasMediaAttachment: true,
      imageMessage: { url: 'https://mmg.whatsapp.net/...', ... }
    },
    nativeFlowMessage: { buttons: [...] },
    body:   { text: 'Hello' },
    footer: { text: 'Footer' }
  }
}

Binary Nodes Injected

| Chat Type | Nodes Added | |---|---| | Private | biz + interactive/native_flow + bot (biz_bot: '1') | | Group | biz + interactive/native_flow only |

API Reference

sendButtons(sock, jid, data, options?)

Simplified sending for quick replies and basic CTAs.

| Parameter | Type | Description | |---|---|---| | sock | WASocket | Baileys socket instance | | jid | string | Recipient JID | | data.text | string | Message body (required) | | data.title | string | Header title (optional) | | data.footer | string | Footer text (optional) | | data.image | object | Image header - { url, path, or buffer } (optional) | | data.buttons | array | Button objects |

sendInteractiveMessage(sock, jid, content, options?)

Full control over all button types and structures.

| Parameter | Type | Description | |---|---|---| | sock | WASocket | Baileys socket instance | | jid | string | Recipient JID | | content.text | string | Message body (required) | | content.footer | string | Footer text (optional) | | content.image | object | Image header - { url, path, or buffer } (optional) | | content.interactiveButtons | array | Full button definitions |

Compatibility

| Baileys Package | Compatible | |---|---| | mrxd-baileys | ✅ Yes | | @whiskeysockets/baileys | ✅ Yes (7.0.0-rc.2+) | | baileys | ✅ Yes | | @adiwajshing/baileys | ✅ Yes |

Requirements

• Node.js v20 or higher
• Baileys 7.0.0-rc.2+

Author

mrxdking — @XdKing2

• 📺 YouTube / TikTok / Instagram: @malvintech
• 💬 Telegram: @malvintech

License

ISC © Malvin Tech