Skip to main content

🏠 Whinself on Home Assistant

This guide will help you install and configure the Whinself add-on in Home Assistant, allowing you to send and receive WhatsApp messages easily and self-hosted.

Prerequisites​

Before you begin, make sure you have:

  • Home Assistant (Supervisor) installed and running
  • Access to the Home Assistant Supervisor panel
  • An active WhatsApp account
  • Internet connection

Step 1: Add the add-on repository​

  1. Go to the Supervisor panel in Home Assistant.
  2. Click on Add-on Store.
  3. Click the three dots (top right) and select Repositories.
  4. Add the following repository: 
    https://github.com/inUtil-info/whinself-HA.git
  5. Save and close the dialog.

Step 2: Install the Whinself add-on​

  1. Search for "Whinself" in the add-on store.
  2. Click on the add-on and select Install.
  3. Wait for the installation to finish.

Step 3: Configure the add-on​

You can customize the add-on configuration as needed. All parameters are optional and correspond to Whinself environment variables:

  • slotid: Unique instance identifier (default: slot1)
  • nrurl: URL for incoming messages (webhook)
  • portin: Port for the service to listen on (default: 8888)
  • devicename: Device name (default: WhatsApp Bot)
  • debuglevel: Log level (0-4)
  • logstdout: Enable stdout logging (true/false)
  • logsse: Enable SSE logging (true/false)
  • qrurl: URL for QR code generation (optional)

Important: If you change the portin value, make sure to expose that port in the ports section of the add-on configuration.

Example ports section:

ports:
  8888/tcp: 8888
  9999/tcp: 9999

Step 4: Start the add-on and access the panel​

  1. Click Start to launch the add-on.
  2. Once running, open your browser and go to: 
    http://[YOUR_HA_IP]:[PORT]
    By default, the port is 8888. You can also use the Open Web UI button in the add-on panel.

Step 5: Create an account and connect WhatsApp​

  1. Register a new account (or log in if you already have one).
  2. Click Subscribe to activate your free trial (no payment info required).
  3. A new category will appear in the web interface with the QR code.
  4. Scan the QR code with WhatsApp:
    • Open WhatsApp > Settings > Linked Devices > Link a Device
    • Scan the QR code from the Whinself dashboard

When you see the status Connected to WhatsApp and your number in the Service Status section, the integration is ready.

Step 6: Test sending messages​

You can test sending messages with curl:

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

Replace 1234567890 with the recipient's phone number (including country code).

Step 7: Receive WhatsApp messages in Home Assistant and forward to a webhook​

  1. Create an automation in Home Assistant:

    • Go to Settings > Automations & Scenes > Automations
    • Add a new automation with trigger type Webhook (ID: whinself_incoming)
    • As action, use the service rest_command.forward_whatsapp_message (see next step)

  2. Set the endpoint in Whinself:

    • In the add-on configuration, set nrurl to: 
      http://homeassistant.local:8123/api/webhook/whinself_incoming
      Or use your Home Assistant's local IP if needed.

  3. (Optional) Add in your configuration.yaml:

    rest_command:
      forward_whatsapp_message:
        url: "https://your-external-webhook.com/endpoint"
        method: POST
        headers:
          Content-Type: "application/json"
        payload: "{{ trigger.json | tojson }}"

Step 8: Add Whinself to the Home Assistant sidebar​

  1. Go to Settings > Dashboards.
  2. Click Add panel and select Webpage.
  3. Set the URL to: 
    http://homeassistant.local:8888
    Or use your Home Assistant IP and the selected port.
  4. Choose a title and icon (e.g., mdi:whatsapp).

Troubleshooting​

  • If the add-on does not start, check the Supervisor logs.
  • Make sure the configured port is not in use by another service.
  • If messages are not received, check the webhook URL and your network/firewall settings.

More Information​

Note: Whinself is an unofficial third-party tool and is not affiliated with WhatsApp or Meta Platforms, Inc. Use this add-on at your own risk and always comply with WhatsApp's Terms of Service.