Skip to main content

​
System Requirements

Before installing BuilderBot, ensure your system meets these requirements:

Node.js

Version 18 or higher is required

Package Manager

pnpm 8.6.12+ recommended, npm and yarn also supported
Node.js 16 and below are not supported. BuilderBot requires Node.js 18+ for optimal performance and compatibility.

​
Quick Installation

The fastest way to get started is with the BuilderBot CLI:
1

Run the create command

npm create builderbot@latest
This interactive CLI will guide you through:
  • Project name selection
  • Language choice (JavaScript or TypeScript)
  • Provider selection (WhatsApp, Telegram, etc.)
  • Database choice (Memory, MongoDB, MySQL, PostgreSQL, JSON)
2

Navigate to your project

cd your-project-name
3

Install dependencies

npm install
4

Start your bot

npm start

​
Manual Installation

For more control over your setup, you can install BuilderBot manually:

​
1. Initialize Your Project

mkdir my-chatbot
cd my-chatbot
npm init -y

​
2. Install Core Package

npm install @builderbot/bot

​
3. Install a Provider

Choose one based on your messaging platform: 
npm install @builderbot/provider-baileys
Baileys is a free, open-source WhatsApp Web API implementation. Best for development and small-scale bots.

​
4. Install a Database (Optional)

For development, the built-in MemoryDB is sufficient. For production, choose a persistent database: 
import { MemoryDB } from '@builderbot/bot'

const database = new MemoryDB()
No installation needed. Data is lost when the bot restarts.

​
5. Create Your Bot File

Create app.js (or app.ts for TypeScript): 
import { createBot, createProvider, createFlow, addKeyword } from '@builderbot/bot'
import { MemoryDB } from '@builderbot/bot'
import { BaileysProvider } from '@builderbot/provider-baileys'

const PORT = process.env.PORT ?? 3008

const welcomeFlow = addKeyword(['hi', 'hello', 'hola'])
  .addAnswer('🙌 Hello! Welcome to this chatbot.')

const main = async () => {
  const adapterFlow = createFlow([welcomeFlow])
  const adapterProvider = createProvider(BaileysProvider)
  const adapterDB = new MemoryDB()

  const { httpServer } = await createBot({
    flow: adapterFlow,
    provider: adapterProvider,
    database: adapterDB,
  })

  httpServer(+PORT)
  console.log(`Bot is running on port ${PORT}`)
}

main()

​
6. Configure package.json

Add the module type and start script:
package.json
{
  "name": "my-chatbot",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "@builderbot/bot": "^1.3.10",
    "@builderbot/provider-baileys": "latest"
  }
}
The "type": "module" field enables ES6 module syntax. If you prefer CommonJS, use require() instead of import.

​
TypeScript Setup

For TypeScript projects, add these configurations:

​
Install TypeScript Dependencies

npm install -D typescript @types/node tsx

​
Create tsconfig.json

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

​
Update package.json Scripts

package.json
{
  "scripts": {
    "dev": "tsx watch src/app.ts",
    "build": "tsc",
    "start": "node dist/app.js"
  }
}
Now you can develop with hot-reload: 
npm run dev

​
Environment Variables

Create a .env file for configuration:
.env
PORT=3008
NODE_ENV=development

# Database configuration (if using external DB)
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your-password
DB_NAME=builderbot

# Provider-specific variables
# For Meta provider:
META_ACCESS_TOKEN=your-token
META_PHONE_NUMBER_ID=your-phone-id
META_VERIFY_TOKEN=your-verify-token

# For Twilio provider:
TWILIO_ACCOUNT_SID=your-sid
TWILIO_AUTH_TOKEN=your-token
TWILIO_PHONE_NUMBER=your-number
Install dotenv to load environment variables: 
npm install dotenv
Load it in your app: 
import 'dotenv/config'
// Rest of your code

​
Verification

Verify your installation:
1

Check Node.js version

node --version
Should output v18.0.0 or higher.
2

Run your bot

npm start
You should see:
  • Bot initialization messages
  • QR code (for Baileys provider)
  • HTTP server started message
3

Test connection

For Baileys: Scan the QR code with WhatsAppFor other providers: Follow provider-specific setup instructions

​
Common Installation Issues

Error: The engine "node" is incompatible with this moduleSolution: Upgrade Node.js to version 18 or higher:
# Using nvm
nvm install 18
nvm use 18

# Or download from nodejs.org
Error: Cannot find module '@builderbot/bot'Solution: Ensure dependencies are installed:
rm -rf node_modules package-lock.json
npm install
Error: No QR code shown when using BaileysSolution:
  • Check your terminal supports displaying QR codes
  • Try running in a different terminal
  • Ensure port 3008 (or your PORT) is not in use
Error: Database connection errorsSolution:
  • Verify database server is running
  • Check connection credentials in .env
  • Ensure database exists
  • For development, use MemoryDB to bypass database issues

​
Next Steps

Quick Start

Build your first chatbot with step-by-step guidance

Core Concepts

Learn about flows, providers, and databases

Provider Configuration

Configure your chosen messaging platform

Testing

Test your bot before deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us