HBotWWeb 🤖

WhatsApp bot framework powered by whatsapp-web.js with support for commands, media, locations, polls, and more.

📋 Features

• ✅ Simple command-based system
• ✅ Send text, images, videos, documents
• ✅ Send locations, polls, stickers
• ✅ Web interface for QR code scanning
• ✅ Auto-reply to last message sender
• ✅ Multiple message types support
• ✅ Easy-to-use API

🚀 Installation

npm install hbotwweb

Requirements

• Node.js v18 or higher
• Puppeteer (installed automatically as peer dependency)

📖 Quick Start

const { WhatsAppBot } = require('hbotwweb')

const bot = new WhatsAppBot(3000) // Port for web interface

// Add a simple command
bot.addKeyword(['hello', 'hi']).addAction(
    async (ctx, ctxFn) => {
        await ctxFn.reply(`Hello ${ctx.pushName}! 👋`)
    }
)

// Start the bot
bot.conectar().catch(console.error)

Open http://localhost:3000 to scan the QR code with WhatsApp.

📚 API Documentation

Creating a Bot

const bot = new WhatsAppBot(port)

Adding Commands

bot.addKeyword(['keyword1', 'keyword2']).addAction(
    async (ctx, ctxFn) => {
        // Your code here
    }
)

Context Object (ctx):

• ctx.from - Sender ID
• ctx.body - Message text
• ctx.pushName - Sender name
• ctx.originalMessage - Full message object

Context Functions (ctxFn):

• ctxFn.reply(text) - Reply with text
• ctxFn.send(text) - Send text message
• ctxFn.sendFile(path, caption) - Send file
• ctxFn.flowDynamic(...items) - Send multiple items

Sending Messages

Text Message

// Auto-reply to last sender
await bot.enviarMensaje('Hello!')

// Send to specific contact
await bot.enviarMensaje('Hello!', '[email protected]')

Image/Video/Document

// From URL
await bot.enviarMensaje({
    media: 'https://example.com/image.jpg',
    caption: 'Check this out!'
})

// From local file
await bot.enviarMensaje({
    media: './files/document.pdf',
    caption: 'Here is the document'
})

Location

await bot.enviarMensaje({
    location: {
        latitude: 18.4861,
        longitude: -69.9312,
        description: 'Santo Domingo, DR'
    }
})

Poll

await bot.enviarMensaje({
    poll: {
        name: 'What is your favorite language?',
        options: ['JavaScript', 'Python', 'Java', 'Go'],
        multipleAnswers: false
    }
})

Sticker

await bot.enviarMensaje({
    sticker: 'https://example.com/sticker.png'
})

List (formatted as text)

await bot.enviarMensaje({
    title: 'Menu',
    body: 'Select an option:',
    footer: 'Bot v1.0',
    list: {
        sections: [
            {
                title: 'Services',
                rows: [
                    { title: 'Support', description: 'Technical support' },
                    { title: 'Sales', description: 'Product information' }
                ]
            }
        ]
    }
})

Listening to Messages

bot.on('message', async (msg) => {
    console.log(`Message from ${msg.from}: ${msg.body}`)

    // Reply using whatsapp-web.js native method
    await msg.reply('Message received!')
})

Events

bot.on('qr', (qr) => {
    console.log('QR Code generated:', qr)
})

bot.on('connected', () => {
    console.log('Bot connected!')
})

bot.on('disconnected', (reason) => {
    console.log('Bot disconnected:', reason)
})

🎯 Examples

Echo Bot

bot.addKeyword('*').addAction(
    async (ctx, ctxFn) => {
        await ctxFn.reply(`You said: ${ctx.body}`)
    }
)

Welcome Message for Groups

bot.on('message', async (msg) => {
    if (msg.from.endsWith('@g.us') && msg.body.toLowerCase() === 'hello') {
        await msg.reply('Welcome to the group! 👋')
    }
})

Send File on Command

bot.addKeyword('document').addAction(
    async (ctx, ctxFn) => {
        await ctxFn.sendFile('./files/info.pdf', 'Here is the information')
    }
)

Menu System

bot.addKeyword(['menu', 'help']).addAction(
    async (ctx, ctxFn) => {
        await ctxFn.flowDynamic([
            '📋 *Bot Menu*',
            '• hello - Greeting',
            '• menu - Show this menu',
            '• location - Send location',
            '• poll - Create a poll'
        ])
    }
)

🌐 Web Interface

The bot includes a built-in web interface for QR code scanning:

• Accessible at http://localhost:<port>
• Shows bot status in real-time
• Displays QR code for authentication
• WebSocket-based updates

🔧 Configuration

Environment Variables

Create a .env file:

PORT=3000

Custom Port

const bot = new WhatsAppBot(4000) // Custom port

If the port is busy, the bot will automatically find an available one.

📝 Advanced Usage

Custom Message Handler

bot.on('message', async (msg) => {
    // Access full whatsapp-web.js message object
    if (msg.hasMedia) {
        const media = await msg.downloadMedia()
        console.log('Media received:', media.mimetype)
    }
})

Using Bot Socket Directly

const sock = bot.getSocket()
// Use whatsapp-web.js client methods directly

⚠️ Important Notes

• This is an unofficial library
• Use at your own risk - WhatsApp may block accounts using unofficial clients
• Recommended for personal/testing use only
• Not affiliated with WhatsApp

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📄 License

MIT License - see LICENSE file for details

🔗 Links

• whatsapp-web.js Documentation
• GitHub Repository
• Report Issues

💡 Tips

1. Auto-reply feature: If you don't specify a recipient, the bot automatically replies to the last message sender
2. Media types: Supports images, videos, audio, documents, and stickers
3. Keyword matching: Use * to match any message, or *keyword* to match messages containing the keyword
4. Web interface: The built-in web UI makes QR scanning easy without terminal

📞 Support

For questions and support, please open an issue on GitHub.

Made with ❤️ using whatsapp-web.js