MANUAL

Software

• Node.js 18+
• npm or yarn
• Fararoni Core running (port 7071)

Hardware

• Phone with WhatsApp installed
• Stable internet connection

# 1. Navigate to the sidecar directory
cd fararoni-sidecar-wa

# 2. Install dependencies
npm install

# 3. Copy example configuration
cp .env.example .env

# 4. Edit configuration
nano .env

# Fararoni REST Gateway URL
GATEWAY_URL=http://localhost:7071/gateway/v1/inbound

# HTTP server port for receiving responses
SIDECAR_PORT=3000

# Log level (debug, info, warn, error)
LOG_LEVEL=info

# Operation mode
# private_only = Only responds in private chats
# groups_only = Only responds in groups
# all = Responds in all (CAUTION)
CHAT_MODE=private_only

node sidecar.js

A QR code will appear in the terminal. Steps to link:

1. Open WhatsApp on your phone
2. Go to Settings → Linked Devices
3. Tap Link a Device
4. Scan the QR code from the terminal

Once linked:

[SIDECAR] WhatsApp connected as: +52 1 229 XXX XXXX
[SIDECAR] HTTP Server listening on port 3000
[SIDECAR] Ready to send and receive messages

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User          │     │   Sidecar WA    │     │  Fararoni Core  │
│   WhatsApp      │     │   (Node.js)     │     │   (Java)        │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  Incoming message     │                       │
         │──────────────────────>│                       │
         │                       │  POST /gateway/v1/inbound
         │                       │──────────────────────>│
         │                       │                       │ Process with LLM
         │                       │  POST /send           │
         │                       │<──────────────────────│
         │  Response message     │                       │
         │<──────────────────────│                       │

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

gateway:
  rest:
    enabled: true
    port: 7071

channels:
  whatsapp:
    enabled: true
    egress_url: "http://localhost:3000/send"
    allowed_numbers: []  # Empty = all allowed
    blocked_numbers: []

# Start Fararoni Core
cd fararoni-core/target
java --enable-preview -jar fararoni-core-1.0.0.jar --server

# Start WhatsApp Sidecar (another terminal)
cd fararoni-sidecar-wa
node sidecar.js

# View logs in real time
tail -f ~/.fararoni/logs/fararoni.log

# Reset WhatsApp session (delete credentials)
rm -rf fararoni-sidecar-wa/baileys_auth_info/
node sidecar.js  # Will scan QR again

QR code doesn't appear

rm -rf node_modules
npm install

Frequent disconnections

• Check internet connection
• Don't use WhatsApp Web in the browser simultaneously
• Make sure the phone has enough battery

Messages don't reach Fararoni

# Verify Fararoni is running
curl http://localhost:7071/gateway/v1/health

WhatsApp Credentials

• NEVER push baileys_auth_info/ to git
• Already in .gitignore
• Contains sensitive session tokens

Blocked Numbers

# In modules.yml
channels:
  whatsapp:
    blocked_numbers:
      - "5212291234567"  # Block specific number

RESOLVED: Bot no longer responds in groups (PHASE 71.4)

// PHASE 71.4: Ignore group messages
if (msg.key.remoteJid.endsWith('@g.us')) {
  logger.debug(`[INGRESS] Ignoring group message: ${msg.key.remoteJid}`);
  return;
}

Enable Specific Groups (future)

const ALLOWED_GROUPS = [
  '5212291234567-1234567890@g.us',
  '5212299876543-0987654321@g.us'
];

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

Author: Eber Cruz | Version: 1.0