⚙️ 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.

---

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.