⚙️ Installation Guide

Setting up the WhatsApp integration is a two-step process: installing the Backend Gateway (either as a Home Assistant App/Add-on or a Standalone Docker container) and then configuring the Integration in Home Assistant.

---

1️⃣ Backend Gateway Installation

The Backend Gateway handles the heavy lifting of connecting to WhatsApp, managing encryption keys, and serving the REST/WebSocket API.

Option A: Home Assistant Add-on / App (Recommended for HA OS / Supervised)

1. Add the Repository: Click the button below to add the App repository to your Home Assistant.

Add Repository

1. Install the App: Navigate to the store, search for WhatsApp, and click Install.

TIP: Using Home Assistant OS / Supervisor? You can skip manual addon installation! The integration will offer to install the official Addon (Stable or Edge) automatically during the config flow setup.

App Dashboard

1. Start & Get Token:
   • Ensure log_level is set to info in the Configuration tab.
   • Start the App.
   • Open the Web UI and look for the API Token (hidden behind “Show API Key”). Copy this token for the next step.

Option B: Standalone Docker (For Home Assistant Container/Docker-only users)

If you run Home Assistant inside a Docker container (without Supervisor), you can deploy the WhatsApp Gateway using our standalone Docker image.

Run the container using docker compose:

services:
  whatsapp-gateway:
    image: ghcr.io/faserf/whatsapp-gw:latest
    container_name: whatsapp-gateway
    restart: unless-stopped
    ports:
      - "8066:8066"
    volumes:
      - ./data:/data
      - ./media:/media
    environment:
      - PORT=8066
      - DATA_DIR=/data
      - MEDIA_FOLDER=/media
      - LOG_LEVEL=info
      # - API_TOKEN=your_secure_token_here

Or run via Docker CLI:

docker run -d \
  --name whatsapp-gateway \
  --restart unless-stopped \
  -p 8066:8066 \
  -v ./data:/data \
  -v ./media:/media \
  -e PORT=8066 \
  ghcr.io/faserf/whatsapp-gw:latest

After starting, navigate to http://YOUR_SERVER_IP:8066 on your web browser to access the Web UI and retrieve/set your API Token (under “Show API Key”). Copy this token.

---

2️⃣ Integration Installation

The Integration connects Home Assistant’s core to the App and provides the entities.

Option A: HACS (Recommended)

1. Install Repository: Add the custom repository in HACS.

Open HACS

1. Restart: Once installed via HACS, Restart Home Assistant.

Option B: Manual Installation (Fallback)

1. Go to the GitHub Release Page.
2. Download the latest ha-whatsapp.zip file.
3. Open your Home Assistant configuration directory (where configuration.yaml is located).
4. Create a folder custom_components if it doesn’t exist.
5. Extract the whatsapp folder from the zip file into custom_components.
   • Final path should be: /config/custom_components/whatsapp/__init__.py etc.
6. Restart Home Assistant.

---

3️⃣ Configuration & Linking

Now we connect the components and link your device.

1. Click the button below to start the setup:

Add Integration

1. Discovery: Home Assistant will automatically find the app and show a notification (“New devices found”). Click Configure.
2. Connection Details:
   • Host: Enter the URL of your App. (Default: http://localhost:8066).
   • API Key: Paste the API Token you copied from the App Web UI.
3. Click Submit.

📱 Pairing with WhatsApp

1. After submitting the API Key, the Integration will verify the connection.
2. The Integration Setup Dialog will now display a QR Code.
3. On your phone, open WhatsApp -> Linked Devices -> Link a Device.
   1. Option A: QR Code (Standard): Scan the QR code shown in the Integration Dialog.
   2. Option B: Phone Number (Alternative): If scanning is difficult, click the button to pair via phone number. Enter your number (with country code, e.g. 49123...) and a pairing code will be shown which you can enter in WhatsApp on your phone.
4. The integration will confirm the connection. Click Finish.

---

⚠️ Common Prerequisites

• Supervisor: This App requires a Home Assistant Supervised or Home Assistant OS installation.
• Network: Ensure the App port (8066) is not blocked by a firewall if HA and the App are on different machines.