⚙️ Installation Guide

Setting up the WhatsApp integration is a two-step process: installing the App (the engine) and then the Integration (the interface).

---

1️⃣ App Installation

The App handles the heavy lifting of connecting to WhatsApp.

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.

Tip Host Network Mode: If you want the integration to be automatically discovered (“New devices found”), enable the “Use Host Network” toggle in the App configuration.

Note The QR Code might not appear immediately in the App Web UI if you are not observing it. Do not scan anything yet. The scanning happens in the Integration setup.

---

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. Auto-Discovery: If your network supports mDNS (and Host Network is enabled in the App), you will see a notification in Home Assistant. 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.
4. Scan the QR code shown in the Integration Dialog.
5. 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.