🐱 WILDCAT

WhatsApp Integration Layer for Data Connectivity And Transfer

Unofficial WhatsApp integration using reverse-engineered libraries. Use at your own risk and ensure compliance with WhatsApp's terms of service.

Enterprise-Grade WhatsApp REST API for Node.js

WILDCAT is a production-ready Node.js API server providing REST endpoints for WhatsApp messaging, media handling, and webhook delivery. Built with Baileys and MongoDB for reliable multi-account support.

Perfect for chatbots, CRM integrations, marketing automation, and business workflows.

Get Started → · API Docs → · Setup Guide →

---

✨ Why Choose WILDCAT?

🎯 Key Features

Feature	Details
🚀 Multi-Account Support	Manage unlimited WhatsApp numbers simultaneously
📱 Full WhatsApp Features	Messages, media, reactions, statuses, and more
🔗 Webhook Integration	Real-time message delivery to external services
🧾 Media Storage	Automatic GridFS with direct-access endpoints
🤖 Bot-Ready	Perfect for chatbots, automation, CRM integrations
⚡ REST API	Clean HTTP interface, easy integration
🐳 Docker Support	Production-ready containerization
📊 Structured Logging	JSON-based logging for monitoring & debugging

⚠️ Important Considerations

Limitations:

• ⚠️ Unofficial - Relies on reverse-engineered WhatsApp Web protocols
• 🚫 Rate Limited - Subject to WhatsApp's sending limits (typically 60 msg/min)
• 🔒 No Official Support - Community-maintained, no guarantees
• 📵 Ban Risk - Heavy automated usage may trigger WhatsApp account bans
• 🔐 No Auth (v2) - Currently requires manual authentication setup

Recommended Use Cases:

• ✅ Development and testing environments
• ✅ Bot automation for personal/small business use
• ✅ Webhook-based workflows (n8n, Zapier, Make.com)
• ✅ Message broadcasting to opt-in contacts
• ✅ Customer support automation

Not Recommended For:

• ❌ Large-scale spam/marketing (violates WhatsApp ToS)
• ❌ Production without proper security controls
• ❌ High-volume transaction messaging (use official WhatsApp Business API)
• ❌ Public internet exposure without authentication

---

🚀 Quick Start

1️⃣ Prerequisites

• Node.js 18+ (Download)
• MongoDB 6.0+ (Local or Atlas)
• Git (optional, for cloning)

2️⃣ Installation & Setup

# Clone repository
git clone https://github.com/NotoriousArnav/wildcat.git
cd wildcat

# Install dependencies
npm ci

# Configure environment
cp .env.example .env
# Edit .env with your MongoDB URL and other settings
nano .env

# Start server
npm start
# Server runs on http://localhost:3000

3️⃣ Health Check

curl http://localhost:3000/ping
# Response: { "ok": true, "timestamp": "2025-11-08T..." }

4️⃣ Create Your First Account

# Create account via REST API
curl -X POST http://localhost:3000/accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "mybot",
    "name": "My First Bot"
  }'

# Response: QR code + WebSocket connection ready

5️⃣ Scan QR Code & Start Messaging

The QR code will be displayed in terminal. Scan with your WhatsApp phone camera, and the account will authenticate.

# Send a test message
curl -X POST http://localhost:3000/accounts/mybot/message/send \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "[email protected]",
    "message": "Hello from WILDCAT! 🐱"
  }'

# Response: { "ok": true, "messageId": "..." }

✅ Success! You're now sending WhatsApp messages via REST API.

📖 Next Steps

• Full Setup Guide - Detailed installation & configuration
• API Reference - All available endpoints
• Examples - Real-world integration examples

📚 Documentation

📄 Document	📖 Purpose	🎯 For
Setup Guide	Installation, configuration & deployment	First-time users, DevOps
API Reference	Complete REST API endpoint documentation	Frontend developers, integrators
Architecture	System design, module overview	Contributors, architects
Development	Contributing guidelines, local development	Contributors, maintainers

⚙️ CLI Tools

WILDCAT includes command-line utilities for account and message management:

# Development mode with auto-reload
npm run dev

# Production mode
npm start

# Health check
npm run ping

# Run tests
npm test
npm run test:watch
npm run test:coverage

For advanced CLI usage, see the Development Guide.

🐳 Docker Deployment

WILDCAT is Docker-ready with ffmpeg pre-installed for audio conversion.

🔨 Build Image

docker build -t wildcat:latest .

🚀 Run Standalone

docker run --name wildcat \
  -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e MONGO_URL="mongodb://host.docker.internal:27017" \
  -e DB_NAME=wildcat \
  -e AUTO_CONNECT_ON_START=true \
  wildcat:latest

🤝 Docker Compose (Recommended)

Create docker-compose.yml:

version: '3.8'
services:
  mongodb:
    image: mongo:7
    container_name: wildcat-mongo
    ports:
      - "27017:27017"
    volumes:
      - mongo-data:/data/db
    environment:
      MONGO_INITDB_DATABASE: wildcat

  wildcat:
    build: .
    container_name: wildcat-api
    depends_on:
      - mongodb
    ports:
      - "3000:3000"
    environment:
      HOST: 0.0.0.0
      PORT: 3000
      MONGO_URL: "mongodb://mongodb:27017"
      DB_NAME: wildcat
      AUTO_CONNECT_ON_START: "true"
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

volumes:
  mongo-data:

Run with:

docker-compose up -d

📋 Environment Variables

Variable	Default	Description
HOST	0.0.0.0	Server listen address
PORT	3000	Server port
MONGO_URL	Required	MongoDB connection string
DB_NAME	wildcat	MongoDB database name
ADMIN_NUMBER	Optional	WhatsApp JID ([email protected]) to receive startup ping
AUTO_CONNECT_ON_START	false	Auto-reconnect saved accounts on startup

🏥 Health Check

curl http://localhost:3000/ping
# {
#   "ok": true,
#   "timestamp": "2025-11-08T12:34:56.789Z"
# }

🔀 Integration Examples

n8n Workflow Integration

WILDCAT integrates seamlessly with n8n for visual workflow automation.

Workflow Flow:

Webhook Trigger (n8n)
        ↓
   Process/Transform
        ↓
HTTP Request → WILDCAT API
        ↓
WhatsApp Message Sent

Setup Steps:

1. Create n8n HTTP Trigger node

   • Note the webhook URL

2. Register with WILDCAT

   curl -X POST http://localhost:3000/webhooks \
     -H 'Content-Type: application/json' \
     -d '{"url": "https://your-n8n-host/webhook/<webhook-id>"}'

3. Create HTTP Request node in n8n

   • Method: POST
   • URL: http://wildcat-host:3000/accounts/<accountId>/message/send
   • Headers: Content-Type: application/json
   • Body:

     {
       "to": "{{ $json.from }}",
       "message": "{{ $json.message }}"
     }

4. Deploy workflow

   • Messages received by WILDCAT will trigger n8n
   • n8n processes and sends WhatsApp responses

Note: Server logs redact webhook URLs for security (credentials removed).

Other Integration Platforms

WILDCAT works with any HTTP-based automation platform:

• Zapier - Trigger webhooks and send messages
• Make.com (formerly Integromat) - Complex workflows
• IFTTT - Simple if-this-then-that automation
• Custom Applications - Direct REST API calls

See API Reference for complete endpoint documentation.

🚨 Security & Stability Notice

⚠️ CRITICAL: v2 Security Gaps

Current Security Status: ❌ NOT PRODUCTION READY

Issue	Risk	Status
No Authentication	🔴 CRITICAL	Will be fixed in v3.0
No Rate Limiting	🟠 HIGH	Subject to abuse
SSRF in Webhooks	🟠 HIGH	Planned security audit
Minimal Input Validation	🟠 HIGH	Validation layer coming
CommonJS Only	🟡 MEDIUM	Migration to ESM planned

⚠️ WARNING: Anyone with access to your server can send WhatsApp messages. DO NOT expose to public internet without authentication layer (nginx, Caddy, etc.).

🚧 Roadmap: v3.0

Current Focus: Code Quality & Security Modernization

Phase 1: Modernization (Q4 2024 - Q1 2025)

• Migrate to ES Modules (ESM)
• TypeScript migration
• Replace console.log with structured logging
• Comprehensive JSDoc/TS types
• Test coverage (Jest automation)

Phase 2: Security (Q1 2025 - Q2 2025)

• HTTP Authentication (API keys, JWT)
• Rate Limiting (per account, per IP)
• Input Validation (Zod/Joi schemas)
• SSRF Prevention (webhook URL validation)
• Security audit & pen testing

Phase 3: Features (Q2 2025)

• Contact enrichment in webhooks
• Group management endpoints
• Message scheduling
• Advanced media handling (batch uploads)
• Monitoring & metrics endpoints

Phase 4: Production Ready (Q2 2025)

• Comprehensive testing
• CI/CD pipeline (GitHub Actions)
• Performance optimization
• Docker/K8s best practices
• SLA documentation

📋 For Current Users

Until v3.0 is released:

✅ Recommended for:

• Development & testing environments
• Internal business automation
• Bot prototyping & experimentation

❌ NOT recommended for:

• Public internet exposure
• High-volume production use
• Sensitive business data
• Large-scale deployments

Best Practices:

# 1. Deploy behind authentication proxy
# nginx example with basic auth
location / {
  auth_basic "WILDCAT API";
  auth_basic_user_file /etc/nginx/.htpasswd;
  proxy_pass http://localhost:3000;
}

# 2. Use environment-specific URLs
# .env
MONGO_URL=mongodb://...  # Use MongoDB Atlas or encrypted
AUTO_CONNECT_ON_START=false

# 3. Monitor logs for suspicious activity
tail -f logs/app.log | grep "error\|warn"

# 4. Keep backups
mongodump --uri="mongodb://..." --out=./backups

# 5. Watch for updates
# Star/watch this repo for release announcements

Timeline: v3.0 expected Q2 2025 (tentative)

---

🤝 Contributing

WILDCAT welcomes contributions! See Development Guide for detailed guidelines.

🎯 Priority Areas for Contributors

We're actively seeking help with:

Area	Priority	Impact
🔐 Security improvements	🔴 HIGH	Authentication, rate limiting
📘 TypeScript migration	🔴 HIGH	Type safety & DX
✅ Test coverage	🟠 MEDIUM	Reliability & refactoring safety
📚 Documentation	🟠 MEDIUM	Developer experience
🐛 Bug fixes	🟡 ONGOING	Stability

🚀 Getting Started with Development

# 1. Fork & clone
git clone https://github.com/YOUR_USERNAME/wildcat.git
cd wildcat

# 2. Create feature branch
git checkout -b feature/your-feature-name

# 3. Install dependencies
npm ci

# 4. Make changes & test
npm run dev       # development mode with auto-reload
npm test          # run tests
npm run lint      # check code style (coming in v3.0)

# 5. Commit & push
git add .
git commit -m "feat: add your feature"
git push origin feature/your-feature-name

# 6. Create Pull Request
# Open PR on GitHub with clear description

📝 Contribution Guidelines

• Follow the code style (2-space indent, CommonJS)
• Add tests for new features
• Update documentation
• Keep commits atomic and well-described
• No breaking changes without discussion

See Development Guide for more details.

🙏 Acknowledgments

This project builds on excellent open-source work. See ACKNOWLEDGMENTS.md for complete credits.

Key Dependencies:

• @whiskeysockets/baileys - WhatsApp Web API
• mongo-baileys - MongoDB session storage
• Express.js - Web framework
• MongoDB - Database
• Socket.io - Real-time communication

---

📄 License

GPL-3.0-only — See LICENSE

This project includes adapted code from MIT-licensed dependencies. All original copyright notices are preserved in respective files and in ACKNOWLEDGMENTS.md.

Disclaimer: WILDCAT is an unofficial tool for educational purposes. Ensure compliance with WhatsApp's Terms of Service and applicable laws before use.

---

📊 Project Links

Link	Purpose
🔗 GitHub	Source code & issues
📖 Setup Guide	Installation instructions
🔌 API Reference	Endpoint documentation
🏗️ Architecture	System design
👨‍💻 Development	Contributing guide

---

🆘 Support

Need help?

• 📖 Check the documentation
• 🐛 Search existing issues
• 💬 Open a new issue
• 🤖 See CodeRabbit Setup for code reviews

📡 Stay Updated

⭐ Star this repository to be notified of releases and updates.

🔔 Watch for important announcements and breaking changes.

---

Made with ❤️ by the WILDCAT community

⬆ back to top