Installation

This guide walks you through the complete installation process for the WhatsApp Assistant Bot, from system prerequisites to running the bot for the first time.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+

Download from nodejs.org or use a version manager like nvm

PostgreSQL

Install from postgresql.org or use a managed service

You’ll also need a PostgreSQL database with a connection URL. This can be:

A local PostgreSQL installation
A managed database service (AWS RDS, Supabase, Railway, etc.)

Verify Node.js version

Check that you have Node.js 18 or higher:

node --version

Expected output:

v18.17.0  # or higher

Set up PostgreSQL

You need a PostgreSQL database with SSL enabled. Here are a few options:

Local PostgreSQL
Supabase (recommended)
Railway

Install PostgreSQL locally and create a database:

# macOS (Homebrew)
brew install postgresql@15
brew services start postgresql@15

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql

# Create database
createdb whatsapp_bot

Local PostgreSQL typically doesn’t use SSL by default. For production, use a managed database service with SSL enabled.

Create a free account at supabase.com
Create a new project
Go to Settings → Database
Copy the Connection String (URI format)
Use this as your DATABASE_URL

Example format:

postgres://postgres:[YOUR-PASSWORD]@db.xxxxxxxxxxxxx.supabase.co:5432/postgres

Clone the repository

git clone https://github.com/yourusername/whatsapp-assistant-bot.git
cd whatsapp-assistant-bot

Verify project structure

Your directory should contain:

whatsapp-assistant-bot/
├── src/
│   ├── index.ts           # Main entry point
│   ├── handlers/          # Command handlers
│   ├── services/          # Business logic services
│   └── db/                # Database schema and config
├── package.json
├── tsconfig.json
└── .env.example           # Example environment variables

Install dependencies

Install all required packages:

npm install

The repository includes yt-dlp in the bin/ directory for Instagram video downloads. This binary is pre-installed and requires no additional setup.

This installs the following key dependencies:

Core dependencies

baileys (^7.0.0-rc.9) - WhatsApp Web API library
postgres (^3.4.7) - PostgreSQL client
drizzle-orm (^0.45.1) - TypeScript ORM for PostgreSQL
express (^5.2.1) - Web server for OAuth callbacks
dotenv (^17.2.3) - Environment variable management

Utilities

sharp (^0.34.5) - Image processing for stickers
wa-sticker-formatter (^4.4.4) - WhatsApp sticker creation
node-cron (^4.2.1) - Scheduled task execution for reminders
moment (^2.30.1) - Date/time parsing and formatting
pino (^9.6.0) - Logging library
qrcode-terminal (^0.12.0) - QR code display in terminal

Development dependencies

typescript (^5.7.2) - TypeScript compiler
tsx (^4.19.2) - TypeScript execution for development
drizzle-kit (^0.31.8) - Database migration tools
@types/node, @types/express - TypeScript type definitions

Environment configuration

Create .env file

Copy the example environment file:

cp .env.example .env

If .env.example doesn’t exist, create a new .env file:

touch .env

Configure environment variables

Open .env in your editor and add the following:

.env

# PostgreSQL connection string
DATABASE_URL=postgres://user:password@host:port/database

# Server port
PORT=3000

# Optional: Spotify OAuth credentials (for music control)
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here

Replace the DATABASE_URL with your actual PostgreSQL connection string. Ensure it includes ?sslmode=require for secure connections.

Environment variable reference

Variable	Required	Description	Example
`DATABASE_URL`	Yes	PostgreSQL connection string with SSL	`postgres://user:pass@host:5432/db`
`PORT`	No	Main Express server port	`3000` (default)
`SPOTIFY_CLIENT_ID`	No	Spotify OAuth client ID	From Spotify Developer Dashboard
`SPOTIFY_CLIENT_SECRET`	No	Spotify OAuth client secret	From Spotify Developer Dashboard

The Spotify OAuth callback server runs on port 8888 (hardcoded in src/index.ts:39). This port is not configurable via environment variables.

Spotify credentials are optional. The bot works without them, but you won’t be able to use music control features.

Database setup

The bot uses Drizzle ORM with PostgreSQL. The schema is defined in src/db/schema.ts:

src/db/schema.ts

import { pgTable, text, boolean, timestamp, integer, uuid } from 'drizzle-orm/pg-core';

// Users table
export const users = pgTable('users', {
    id: uuid('id').defaultRandom().primaryKey(),
    userId: text('user_id').notNull().unique(),
    lastActive: timestamp('last_active').defaultNow(),
    notificationsEnabled: boolean('notifications_enabled').default(true),
    timezone: text('timezone').default('UTC'),
    spotifyRefreshToken: text('spotify_refresh_token'),
    createdAt: timestamp('created_at').defaultNow(),
    updatedAt: timestamp('updated_at').defaultNow(),
});

// Todos, reminders, notes, and timers tables...

Generate database migrations

Create migration files from your schema:

npx drizzle-kit generate:pg

This creates SQL migration files in the drizzle/ folder.

Run migrations

Apply migrations to your database:

npx drizzle-kit push:pg

This creates all necessary tables:

users - User profiles and settings
todos - Task list items
reminders - Scheduled notifications
notes - Saved text snippets
timers - Active countdown timers

Verify database connection

The bot tests the database connection on startup:

src/db/index.ts

export const connectDatabase = async () => {
    try {
        await client`SELECT 1`;
        console.log('Connected to PostgreSQL successfully');
    } catch (error) {
        console.error('PostgreSQL connection error:', error);
        process.exit(1);
    }
};

If the connection fails, the bot will exit with an error message.

Build the project

Compile TypeScript to JavaScript:

npm run build

This runs the TypeScript compiler (tsc) and creates compiled files in the dist/ folder:

dist/
├── index.js
├── handlers/
├── services/
└── db/

The dist/ folder is created automatically and should not be committed to version control (it’s in .gitignore).

Run the bot

You can run the bot in development or production mode:

npm run dev

Development mode

Uses tsx watch to automatically restart on file changes:

package.json

{
  "scripts": {
    "dev": "tsx watch src/index.ts"
  }
}

Perfect for:

Testing changes
Debugging
Adding new features

Production mode

Runs the compiled JavaScript from dist/:

package.json

{
  "scripts": {
    "start": "node dist/index.js"
  }
}

Use this for:

Deployment to servers
Running with process managers (PM2, systemd)
Production environments

First run

When you start the bot for the first time, you’ll see:

🤖 WhatsApp Reminder Bot Starting...

🌍 Main server listening on port 3000
🎵 Spotify Callback server listening on port 8888
Connected to PostgreSQL successfully
📱 Using WhatsApp Web v2.2431.6, isLatest: true

📱 Scan this QR code with WhatsApp to connect:

█▀▀▀▀▀█ ▀▀█▄ █▀▀ █▀▀▀▀▀█
█ ███ █ ▄▀██▀ ▀█ █ ███ █
█ ▀▀▀ █ ██▄█▄▀▄█ █ ▀▀▀ █

Scan the QR code

Open WhatsApp on your phone
Go to Settings → Linked Devices
Tap Link a Device
Scan the QR code in your terminal

Wait for confirmation

After scanning, you’ll see:

✅ Connected to WhatsApp successfully!
📝 Bot is now listening for messages...

Available commands:
  !help - List all commands
  !sticker - Convert image/gif to sticker
  !notify <time> <message> - Set a reminder
  !todo add <task> - Add a todo
  !note save <title> <content> - Save a note

Authentication persists

Authentication credentials are saved in the auth_info/ folder:

auth_info/
├── creds.json
└── keys/

Never share or commit the auth_info/ folder! It contains your WhatsApp session credentials. Add it to .gitignore.

On subsequent runs, the bot will automatically reconnect without requiring a new QR code scan.

Verify installation

Run through this checklist to ensure everything works:

✅ Database connection successful

Check the logs for:

Connected to PostgreSQL successfully

If you see an error:

Verify DATABASE_URL in .env
Ensure PostgreSQL is running
Check SSL configuration

✅ WhatsApp connection established

After scanning QR code, look for:

✅ Connected to WhatsApp successfully!

If connection fails:

Delete auth_info/ and try again
Check for WhatsApp Web version compatibility
Ensure no other sessions are blocking

✅ Commands work in DMs

Send !help to yourself in WhatsApp. You should receive a list of commands.If no response:

Verify you’re messaging yourself (DM), not a group
Check terminal logs for errors
Ensure the bot process is running

✅ Data persistence works

Test data persistence:

Add a todo: !todo add Test item
Stop the bot (Ctrl+C)
Restart: npm run dev
List todos: !todo list

You should see your todo. If not, check database connection.

Troubleshooting

Module not found errors

Error: Cannot find module 'baileys'

Solution: Reinstall dependencies

rm -rf node_modules package-lock.json
npm install

Database connection errors

PostgreSQL connection error: getaddrinfo ENOTFOUND

Solutions:

Verify DATABASE_URL format: postgres://user:pass@host:port/db
Ensure PostgreSQL server is accessible
Check firewall rules
For managed databases, verify SSL is enabled

TypeScript compilation errors

error TS2307: Cannot find module 'baileys'

Solution: Install type definitions

npm install --save-dev @types/node

QR code not displaying

If the QR code doesn’t appear:

Check that printQRInTerminal is set correctly in src/index.ts
Ensure your terminal supports Unicode characters
Try a different terminal emulator

Port already in use

Error: listen EADDRINUSE: address already in use :::3000

Solutions:

Change PORT in .env to a different value

Kill the process using port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Next steps

Quickstart guide

Send your first commands and test all features

Command reference

Learn all available commands and their usage

Deployment

Deploy to a VPS or cloud provider for 24/7 uptime

Customization

Add custom commands and modify bot behavior

Get Started

Commands

Configuration

Development

Installation

Installation

Prerequisites

Node.js 18+

PostgreSQL

Verify Node.js version

Set up PostgreSQL

Clone the repository

Install dependencies

Environment configuration

Database setup

Build the project

Run the bot

Development mode

Production mode

First run

Verify installation

Troubleshooting

Next steps

Quickstart guide

Command reference

Deployment

Customization

Build docs developers (and LLMs) love

Get Started

Commands

Configuration

Development

​Installation

​Prerequisites

Node.js 18+

PostgreSQL

​Verify Node.js version

​Set up PostgreSQL

​Clone the repository

​Install dependencies

​Environment configuration

​Database setup

​Build the project

​Run the bot

​Development mode

​Production mode

​First run

​Verify installation

​Troubleshooting

​Next steps

Quickstart guide

Command reference

Deployment

Customization

Build docs developers (and LLMs) love

Installation

Prerequisites

Verify Node.js version

Set up PostgreSQL

Clone the repository

Install dependencies

Environment configuration

Database setup

Build the project

Run the bot

Development mode

Production mode

First run

Verify installation

Troubleshooting

Next steps