Skip to main content

🐧 Whinself on Linux (Debian/Ubuntu)

Whinself on Linux (Debian/Ubuntu)

This step-by-step guide shows you how to install and configure Whinself on a Debian/Ubuntu Linux machine. Whinself serves as a low-cost, low-power WhatsApp API server running in a Docker container.

Prerequisites​

Before you begin, ensure you have:

  • A computer running Debian or Ubuntu
  • An Internet connection
  • Basic familiarity with terminal commands
  • A WhatsApp account

Step 1: Update Your System​

Start by updating your package lists and upgrading installed packages:

sudo apt update
sudo apt upgrade -y

Step 2: Install Docker (Skip if Already Installed)​

If Docker isn’t already installed on your system, follow these steps:

  1. Install required packages:

    sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

  2. Add Docker’s official GPG key and repository:

    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

  3. Update package database and install Docker Engine:

    sudo apt update
    sudo apt install -y docker-ce docker-ce-cli containerd.io

  4. Add your user to the Docker group (to run Docker without sudo):

    sudo usermod -aG docker $USER

  5. Enable Docker to start on boot:

    sudo systemctl enable docker

Note: After installation, log out and log back in (or run newgrp docker) to apply the group changes. Verify Docker installation with:

docker --version

Step 3: Create the Whinself Configuration File​

  1. Create a directory for your Whinself configuration:

    mkdir -p ~/whinself
    cd ~/whinself

  2. Create the config.json file:

    nano config.json

  3. Add your configuration (modify as needed):

    {
      "slotid": "my-whatsapp-bot",
      "nrurl": "https://your-webhook-endpoint.com/api/messages",
      "portin": 9001,
      "devicename": "Linux WhatsApp Bot",
      "debuglevel": 0,
      "logstdout": true,
      "logsse": true
    }

Notes:

  • Replace https://your-webhook-endpoint.com/api/messages with the URL where you want to receive messages.
  • The port (9001 in this example) can be changed if needed.

Save and exit (Ctrl+X, then Y, then Enter).

Step 4: Run the Whinself Docker Container​

Run the container using the following command:

docker run -d \
  --name whatsapp-bot \
  --restart unless-stopped \
  -p 9001:9001 \
  -v $(pwd)/config.json:/app/config/config.json \
  inutil/whingo:latest

This command:

  • Pulls and runs the Docker image inutil/whingo:latest (a multi-architecture image that supports both ARM and x86)
  • Maps port 9001 on your host to port 9001 in the container
  • Mounts your config.json into the container at the required path
  • Ensures the container restarts automatically unless manually stopped

Check that the container is running:

docker ps

Step 5: Access the Whinself Dashboard​

  1. Find your system’s IP address:

    hostname -I

  2. Open a web browser on any device within the same network and navigate to:

    http://YOUR_IP:9001

Replace YOUR_IP with your system’s IP address (and adjust the port if you changed it in your configuration).

Step 6: Register an Account​

When you access the dashboard for the first time:

  1. Click the "Sign Up" button on the welcome screen.
  2. Enter your email address and create a password.
  3. Submit the form.
  4. Check your email for a verification link.
  5. Click the link to activate your account.
  6. Log in to the dashboard with your new credentials.

This account allows you to manage your Whinself instance and use its features.

Step 7: Connect WhatsApp​

After logging in:

  1. Click "Subscribe" to activate your free trial (if applicable).
  2. A QR code should appear on the dashboard.
  3. On your smartphone, open WhatsApp, navigate to Settings > Linked Devices > Link a Device, and scan the QR code.
  4. Wait for the connection to complete.

Note: You can connect multiple WhatsApp accounts, but only one can be active at a time. To switch, disconnect the current account and scan a new QR code.

Step 8: Test Sending a Message​

Test your setup by sending a message via curl:

curl -X POST http://localhost:9001/wspout \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from my Linux Whinself server!",
    "jid": "[email protected]"
  }'

Replace 1234567890 with the actual phone number (including the country code) you wish to message.

Step 9: Set Up Permanent Access (Optional)​

For remote access, you can either:

Option A: Set Up Port Forwarding​

Configure your router to forward the chosen port (e.g., 9001) to your Linux machine’s IP address.

Option B: Use a Reverse Proxy with SSL​

For enhanced security, set up Nginx as a reverse proxy with Let's Encrypt SSL:

  1. Install Nginx and Certbot:

    sudo apt install -y nginx certbot python3-certbot-nginx

  2. Configure Nginx:

    sudo nano /etc/nginx/sites-available/whinself

    Add the following configuration (replace your-domain.com with your actual domain):

    server {
        listen 80;
        server_name your-domain.com;

        location / {
            proxy_pass http://localhost:9001;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
        }
    }

  3. Enable the site and obtain an SSL certificate:

    sudo ln -s /etc/nginx/sites-available/whinself /etc/nginx/sites-enabled/
    sudo certbot --nginx -d your-domain.com
    sudo systemctl reload nginx

Troubleshooting​

Container Not Starting​

View container logs for error details:

docker logs whatsapp-bot

Cannot Access the Web Interface​

Ensure that the port is open:

sudo netstat -tulpn | grep 9001

WhatsApp Connection Issues​

  • Check container logs for errors.
  • Confirm that your system has a stable Internet connection.
  • Verify your smartphone’s network connectivity.
  • If needed, disconnect and reconnect by generating a new QR code.

Managing Your Whinself Installation​

Updating Whinself​

To update to the latest version:

docker pull inutil/whingo:latest
docker stop whatsapp-bot
docker rm whatsapp-bot
docker run -d \
  --name whatsapp-bot \
  --restart unless-stopped \
  -p 9001:9001 \
  -v $(pwd)/config.json:/app/config/config.json \
  inutil/whingo:latest

Viewing Logs​

To follow container logs in real time:

docker logs -f whatsapp-bot

Auto-start on Boot​

The --restart unless-stopped flag ensures that your container starts automatically when your system boots.

Conclusion​

You now have a fully functional WhatsApp API server running on your Debian/Ubuntu system with Docker. You can integrate Whinself with home automation projects, chatbots, or any system that benefits from WhatsApp messaging capabilities.

Disclaimer: Whinself is an unofficial third-party tool that connects to WhatsApp using your personal account. It is not affiliated with or endorsed by WhatsApp or Meta Platforms, Inc. Always use such tools in compliance with WhatsApp's Terms of Service.