Skip to main content
WhatsApp integration uses device linking to connect your bot without requiring WhatsApp Business API credentials.

​
Prerequisites

  • Node.js ≥18 installed on your system
  • A phone with WhatsApp installed
  • Access to WhatsApp’s “Linked Devices” feature

​
Features

  • ✅ No API key required
  • ✅ Direct device linking via QR code
  • ✅ Phone number-based access control
  • ✅ Simple setup and configuration

​
Setup

1

Check Node.js version

Verify Node.js version:
node --version
Must be ≥18.0.0. If not, install from https://nodejs.org/
2

Link device with QR code

Run the login command:
nanobot channels login
A QR code will appear in your terminal.
3

Scan QR code

On your phone:
  1. Open WhatsApp
  2. Go to Settings → Linked Devices
  3. Tap Link a Device
  4. Scan the QR code displayed in your terminal
You should see “nanobot” appear in your linked devices list.
4

Configure nanobot

Edit ~/.nanobot/config.json:
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}
Use full international format: +[country code][phone number]
5

Run two terminals

You need to keep both processes running:Terminal 1 (WhatsApp session):
nanobot channels login
Terminal 2 (Gateway):
nanobot gateway
6

Test the connection

  1. Send a WhatsApp message to the phone number linked to nanobot
  2. Your bot should respond!

​
Configuration Options

​
enabled
boolean
required
Enable the WhatsApp channel
​
allowFrom
array
required
List of phone numbers allowed to interact with the botFormat: Use international format with + prefixExamples:
  • Single number: ["+1234567890"]
  • Multiple: ["+1234567890", "+9876543210"]
Phone numbers must match exactly (including country code)

​
Running in Production

To keep both processes running:

​
Using pm2

pm2 start "nanobot channels login" --name whatsapp-session
pm2 start "nanobot gateway" --name nanobot-gateway
pm2 save

​
Using systemd

Create two service files:/etc/systemd/system/nanobot-whatsapp.service:
[Unit]
Description=Nanobot WhatsApp Session
After=network.target

[Service]
Type=simple
User=your-user
ExecStart=/usr/local/bin/nanobot channels login
Restart=always

[Install]
WantedBy=multi-user.target
/etc/systemd/system/nanobot-gateway.service:
[Unit]
Description=Nanobot Gateway
After=network.target nanobot-whatsapp.service

[Service]
Type=simple
User=your-user
ExecStart=/usr/local/bin/nanobot gateway
Restart=always

[Install]
WantedBy=multi-user.target
Enable and start:
sudo systemctl enable nanobot-whatsapp nanobot-gateway
sudo systemctl start nanobot-whatsapp nanobot-gateway

​
Troubleshooting

  1. Verify Node.js version: node --version (must be ≥18)
  2. Check terminal size (QR code needs space to render)
  3. Try running in a different terminal emulator
  4. Clear WhatsApp session: rm -rf ~/.nanobot/whatsapp-session and retry
  1. Verify phone number format in allowFrom (must include + and country code)
  2. Check both terminals are running:
    • nanobot channels login
    • nanobot gateway
  3. Verify device is still linked in WhatsApp → Settings → Linked Devices
  4. Check logs with: nanobot gateway -v
If the linked device session expires:
  1. Stop both processes
  2. Remove session data: rm -rf ~/.nanobot/whatsapp-session
  3. Re-run nanobot channels login and scan QR code again
  4. Restart gateway
Error: “Node.js 18 or higher is required”Solution: Upgrade Node.js
# Using nvm (recommended)
nvm install 18
nvm use 18

# Or download from nodejs.org
Use a process manager like pm2 or systemd to run both processes as background services.See “Running in Production” section above.

​
Complete Example

Full configuration: 
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890", "+9876543210"]
    }
  }
}

Configuration Overview

Learn about channel configuration

Security Settings

Set up access control

Build docs developers (and LLMs) love

Get started for freeTalk to us