Skip to main content

🍓 Whinself on Raspberry Pi

This step-by-step guide will walk you through the process of installing and configuring Whinself on a Raspberry Pi, creating a cost-effective, low-power WhatsApp API server.

Prerequisites​

Before you begin, ensure you have:

  • A Raspberry Pi (3B, 3B+, 4, or newer recommended)
  • Raspberry Pi OS installed (Raspbian Lite is sufficient)
  • Internet connection
  • Basic knowledge of terminal commands
  • A WhatsApp account

Step 1: Update Your Raspberry Pi​

First, ensure your Raspberry Pi is up to date:

sudo apt update
sudo apt upgrade -y

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

Note: This step is only necessary if Docker is not already installed on your Raspberry Pi. If Docker is already running on your system, you can verify with docker --version and skip to Step 3.

Whinself runs in a Docker container, so we need to install Docker first:

# Install required packages
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/raspbian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up the repository
echo "deb [arch=armhf signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/raspbian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update package database with Docker packages
sudo apt update

# Install Docker Engine
sudo apt install -y docker-ce docker-ce-cli containerd.io

# Add your user to the docker group (to run docker without sudo)
sudo usermod -aG docker $USER

# Enable Docker to start on boot
sudo systemctl enable docker

After installing, log out and log back in for the group changes to take effect, or run:

newgrp docker

Verify Docker is installed correctly:

docker --version

Step 3: Create the Whinself Configuration File​

Create a directory for your Whinself configuration:

mkdir -p ~/whinself
cd ~/whinself

Create the config.json file:

nano config.json

Add the following configuration (modify as needed):

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

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

Notes on configuration:

  • Replace https://your-webhook-endpoint.com/api/messages with your actual webhook URL where you want to receive incoming messages
  • You can use a service like webhook.site for testing
  • You may choose any available port for portin (9001 is just an example)

Step 4: Run the Whinself Docker Container​

Now run the Whinself container with your configuration:

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:

  • Uses the multi-architecture Docker image inutil/whingo:latest (works on ARM/Raspberry Pi)
  • Maps port 9001 on your Raspberry Pi to port 9001 in the container
  • Mounts your config.json file into the container
  • Sets the container to restart automatically unless manually stopped

Check if the container is running:

docker ps

You should see your whatsapp-bot container in the list.

Step 5: Access the Whinself Dashboard​

  1. Find your Raspberry Pi's IP address:
hostname -I
  1. Open a web browser from any device on the same network and navigate to:
http://YOUR_PI_IP:9001

Replace YOUR_PI_IP with the IP address from the previous step, and 9001 with your configured port.

Step 6: Register an Account​

When accessing the Whinself dashboard for the first time, you'll need to create an account:

Note: If you already have a Whinself account, you can skip the registration process and simply log in with your existing credentials.

  1. On the welcome screen, click the "Sign Up" button
  2. Enter your email address and create a password
  3. Submit the registration form
  4. Check your email inbox for a verification email from Whinself
  5. Click the verification link in the email to activate your account
  6. Return to the Whinself dashboard and log in with your newly created credentials

This account will allow you to manage your Whinself instance and access all its features.

Step 7: Connect WhatsApp​

After logging in to your Whinself account:

  1. If you've just created a new account, you'll need to click the "Subscribe" button to activate your free trial

    Note: The free trial doesn't require any credit card information or payment details. It allows you to test Whinself functionality for a few days without any commitment.

  2. Once subscribed, you should see a QR code on the dashboard

  3. Open WhatsApp on your smartphone

  4. Go to Settings > Linked Devices > Link a Device

  5. Scan the QR code displayed on the Whinself dashboard

  6. Wait for the connection to be established

Once connected, you should see the status indicators on the dashboard turn green, indicating that Whinself is connected to WhatsApp. The dashboard will also display the phone number of the WhatsApp account you've connected.

Note: You can connect multiple WhatsApp accounts to your Whinself installation, but only one can be active at a time. To switch accounts, you'll need to disconnect the current one and connect another by scanning a new QR code.

Step 8: Test Sending a Message​

You can test sending a message using curl from your Raspberry Pi:

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

Replace 1234567890 with an actual phone number (including country code) you want to message.

Step 9: Set Up Permanent Access (Optional)​

For easier access to your Whinself server from outside your network, you can:

Option A: Set Up Port Forwarding​

Configure your router to forward the port (e.g., 9001) to your Raspberry Pi's IP address.

Option B: Use a Reverse Proxy with SSL​

For a more secure setup, install Nginx as a reverse proxy with Let's Encrypt SSL:

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

Configure Nginx (basic setup - customize as needed):

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

Add:

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;
    }
}

Enable the site and get 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​

Check logs for errors:

docker logs whatsapp-bot

Cannot access the web interface​

Verify the port is open:

sudo netstat -tulpn | grep 9001

WhatsApp connection issues​

  1. Check container logs
  2. Ensure your Raspberry Pi has stable internet
  3. Verify your phone has a stable connection
  4. Try reconnecting 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​

docker logs -f whatsapp-bot

Auto-start on Boot​

The --restart unless-stopped flag ensures your container starts automatically when your Raspberry Pi boots up.

Conclusion​

You now have a functional WhatsApp API server running on your Raspberry Pi! You can integrate this with your home automation systems, chatbots, or any other project that would benefit from WhatsApp messaging capabilities.

Remember that Whinself is an unofficial third-party tool that connects to the WhatsApp network using your personal WhatsApp account. It is not affiliated with, authorized, maintained, sponsored, or endorsed by WhatsApp or Meta Platforms, Inc. Always ensure your usage complies with WhatsApp's Terms of Service.