Skip to main content

​
Quickstart

Get up and running with the WhatsApp Assistant Bot in under 5 minutes. This guide will walk you through starting the bot, connecting it to WhatsApp, and sending your first command.
This quickstart assumes you’ve already completed the installation steps. If you haven’t installed the bot yet, complete that first.

​
Start the bot

1

Start in development mode

Open your terminal and navigate to the project directory, then start the bot:
npm run dev
You’ll see output indicating the bot is starting:
🤖 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
2

Scan the QR code

A QR code will appear in your terminal:
📱 Scan this QR code with WhatsApp to connect:

█▀▀▀▀▀█ ▀▀█▄ █▀▀ █▀▀▀▀▀█
█ ███ █ ▄▀██▀ ▀█ █ ███ █
█ ▀▀▀ █ ██▄█▄▀▄█ █ ▀▀▀ █
To scan it:
  1. Open WhatsApp on your phone
  2. Go to Settings → Linked Devices
  3. Tap Link a Device
  4. Scan the QR code displayed in your terminal
The QR code will refresh every 30 seconds if not scanned. Make sure to scan it promptly.
3

Connection confirmed

Once scanned successfully, 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
Your bot is now active and ready to receive commands!

​
Send your first command

Let’s test the bot by sending a few commands in your WhatsApp DM.
1

Send the help command

Open WhatsApp and send a message to yourself (or to the linked device):
!help
You should receive a response listing all available commands:
📚 Available Commands:

*!notify*
Usage: !notify <task> <time>
Set a reminder for yourself

*!todo*
Usage: !todo <add/list/done/delete/clear>
Manage your persistent todo list

*!note*
Usage: !note <save/list/view/delete/search>
Manage your personal snippets
...
2

Set a reminder

Try setting a reminder:
!notify test reminder 5m
You’ll get a confirmation:
✅ Reminder set: "test reminder" in 5m
After 5 minutes, you’ll receive:
⏰ Reminder: test reminder
3

Create a todo

Add an item to your todo list:
!todo add Buy groceries
Response:
✅ Task added: Buy groceries
List your todos:
!todo list
Response:
📋 Your Todos:

1. [ ] Buy groceries
4

Create a sticker

Send an image, GIF, or video to yourself, then reply to it with:
!sticker
The bot will convert it to a WhatsApp sticker and send it back to you!
Use !sticker f or !sticker full to create a full-size sticker without cropping.
5

Download an Instagram reel (optional)

Send any Instagram reel or post URL:
https://www.instagram.com/reel/ABC123xyz/
The bot will automatically detect it and download the video:
⏳ Processing Instagram video... please wait.
✅ Here is your Instagram video!
No command needed - the bot automatically detects and processes Instagram URLs.

​
Verify it works

When you send !help or any command, you should receive an immediate response. If you don’t:
  • Check that the bot is still running in your terminal
  • Verify you’re sending messages to yourself (DM), not a group
  • Ensure the QR code was scanned successfully
  • Check the terminal for error messages
When you set a reminder with !notify, you should receive the notification at the specified time. If reminders don’t arrive:
  • Check that the NotificationService initialized successfully (look for logs in terminal)
  • Verify your system time is correct
  • Ensure the bot process hasn’t crashed
Todos, notes, and reminders should survive bot restarts:
  1. Add a todo: !todo add Test persistence
  2. Stop the bot (Ctrl+C)
  3. Restart the bot: npm run dev
  4. List todos: !todo list
You should see your todo still there. If not, check your PostgreSQL connection.

​
Common issues

If the QR code doesn’t appear or the connection fails, check these common issues:
QR code not showing
  • Ensure you’re running the latest version of the bot
  • Check that no other WhatsApp Web sessions are blocking the connection
  • Try deleting the auth_info/ folder and restarting
Connection closes immediately
  • Your WhatsApp account may have logged out
  • Delete the auth_info/ folder and scan the QR code again
  • Check terminal logs for specific error messages
Bot doesn’t respond to commands
  • Verify you’re sending messages in a DM, not a group (groups are ignored)
  • Check that commands start with ! (exclamation mark)
  • Look for error messages in the terminal
Database connection errors
  • Verify your DATABASE_URL in .env is correct
  • Ensure PostgreSQL is running and accessible
  • Check that SSL is properly configured (ssl: 'require')

​
Next steps

Now that your bot is running, explore more features:

Command reference

Learn about all available commands and their advanced usage

Spotify integration

Connect your Spotify account to control music from WhatsApp

Deployment guide

Deploy your bot to a VPS or cloud provider for 24/7 availability

Customization

Add your own commands and customize bot behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us