MANUAL

What is WhatsApp Baileys?

Baileys is an unofficial open-source library that connects to WhatsApp Web from Node.js. It is completely FREE and requires no business account or verification.

Architecture

+----------------+     +-----------------+     +----------------+     +----------------+
|   User         | --> |  WhatsApp Web   | --> |   Sidecar WA   | --> |   Fararoni     |
|   WhatsApp     |     |  (Baileys)      |     |   (:3000)      |     |   Gateway      |
+----------------+     +-----------------+     +----------------+     |   (:7071)      |
                                                                      +----------------+
                                                                             |
                                                                             v
                                                                      +----------------+
                                                                      |  LLM Agents    |
                                                                      +----------------+

Advantages

Limitations (Warning)

IMPORTANT: For enterprise production, use WhatsApp Enterprise.

When to use Baileys?

• Local development and testing
• Personal projects
• POCs (Proof of Concept)
• When you can't afford WhatsApp Enterprise
• Moderate use bots (no spam)

Required Software

• Node.js 20 or higher
• npm (comes with Node.js)
• Fararoni Core installed
• Java 25+ with --enable-preview

WhatsApp

• Phone with WhatsApp installed and working
• Active phone number on WhatsApp
• Phone must have internet connection

Ports

# Verify Node.js (must be 20+)
node --version

# Verify npm
npm --version

# Verify Java
java --version

Channel Encryption

# Local development
export FARARONI_DEV_MODE=true
# Key is auto-generated

cd /path/to/fararoni/fararoni-sidecar-wa
npm install

This will install: @whiskeysockets/baileys, express, axios, qrcode-terminal

Verify modules.yml

Location: ~/.fararoni/config/modules.yml

channels:
  whatsapp:
    enabled: true
    trust_level: UNTRUSTED_EXTERNAL
    egress_url: "http://localhost:3000/send"
    capabilities:
      - text
      - audio
      - image
    timeout_ms: 5000
    retry_count: 3

REST Gateway

gateway:
  rest:
    enabled: true
    port: 7071

Start Order (IMPORTANT)

1. Fararoni Core (Gateway)  <-- FIRST
2. Sidecar WhatsApp         <-- SECOND

Terminal 1: Start Fararoni Core

cd /path/to/fararoni/fararoni-core/target
java --enable-preview -jar fararoni-core-1.0.0.jar --server

Wait until you see:

[MODULE-REGISTRY] Loaded module: OmniChannelGatewayModule
[INGRESS] RestIngressServer listening on port 7071

Terminal 2: Start WhatsApp Sidecar

cd /path/to/fararoni/fararoni-sidecar-wa
npm start

The first time, you'll see a QR code in the terminal.

See QR in Terminal

█████████████████████████████████████
█████████████████████████████████████
████ ▄▄▄▄▄ █▀█ █▄ ▀▄█▀▄█ ▄▄▄▄▄ ████
...
[INFO] Scan the QR code with your WhatsApp

Open WhatsApp on Phone

1. Open WhatsApp on your phone
2. Tap the three dots (menu) in the top right corner
3. Select "Linked Devices"
4. Tap "Link a Device"
5. Point the camera at the QR in the terminal

Verify Successful Connection

[INFO] Connection established
[INFO] Session saved in ./baileys_auth_info/
[INFO] WhatsApp connected. Ready to receive messages.

Session is Saved

The session is saved in fararoni-sidecar-wa/baileys_auth_info/. Next time you won't need to scan again.

When Does the Session Expire?

How to Re-authenticate

cd fararoni-sidecar-wa && rm -rf baileys_auth_info && npm start

Deleting baileys_auth_info/ forces a clean authentication from scratch, as the local credentials become desynchronized with WhatsApp's server.

Gateway Health Check

curl http://localhost:7071/gateway/v1/health
# {"status": "healthy", "module": "gateway-rest-omnichannel"}

Sidecar Health Check

curl http://localhost:3000/health
# {"status": "connected", "phone": "+522291234567"}

End-to-End Test

1. From another phone, send a message to your WhatsApp number
2. You should receive an automatic response from Fararoni

Verify Logs

[INGRESS] +522299876543 -> "Hello, I need help"
[EGRESS] +522299876543 <- "Hello! I'm Fararoni, how can I help you?"

Group Filter

By default, the sidecar ONLY responds to private chats (1:1).

How the Filter Works

if (remoteJid.endsWith('@g.us')) {
    console.log('[FILTER] Ignoring group message:', remoteJid);
    return;
}

Enable Specific Groups

const ALLOWED_GROUPS = [
    '123456789-1234567890@g.us',
    '987654321-0987654321@g.us'
];

if (remoteJid.endsWith('@g.us') && !ALLOWED_GROUPS.includes(remoteJid)) {
    return;
}

Ban Risk

Recommendations: Use Baileys only for development and testing. For production, consider WhatsApp Enterprise. Don't spam.

QR doesn't appear

rm -rf baileys_auth_info
npm start

Error "Session closed" or "Connection Failure"

Cause: WhatsApp session expired or was invalidated.

cd fararoni-sidecar-wa && rm -rf baileys_auth_info && npm start

Then scan the new QR.

Error "ECONNREFUSED"

Cause: Gateway not running.

java --enable-preview -jar fararoni-core-1.0.0.jar --server

Bot doesn't respond

# Verify Gateway
curl http://localhost:7071/gateway/v1/health

# Verify Sidecar
curl http://localhost:3000/health

If health says "disconnected", delete the session and scan QR again.

Error "Number banned"

1. Wait 24-72 hours and retry
2. Appeal the ban from WhatsApp
3. Use another number
4. Consider WhatsApp Enterprise (no ban risk)

# Gateway health
curl http://localhost:7071/gateway/v1/health

# Sidecar health
curl http://localhost:3000/health

# View current QR
curl http://localhost:3000/qr

# Reset session
cd fararoni-sidecar-wa
rm -rf baileys_auth_info
npm start

# Stop services
pkill -f "fararoni-core"
pkill -f "fararoni-sidecar-wa"

Environment Variables

Implementation Checklist

REQUIREMENTS
[ ] Node.js 20+ installed
[ ] Fararoni Core installed
[ ] Java 25+ with --enable-preview
[ ] Phone with WhatsApp

INSTALLATION
[ ] npm install executed
[ ] modules.yml has whatsapp.enabled: true

GETTING STARTED
[ ] Gateway running on port 7071
[ ] Sidecar running on port 3000
[ ] QR code visible in terminal

LINKING
[ ] QR scanned from WhatsApp
[ ] Session saved in baileys_auth_info/

TESTING
[ ] Health checks OK
[ ] Message sent from another phone
[ ] Response received

Differences with Enterprise

Author: Fararoni Team | Version: 1.0