diff --git a/README.md b/README.md index ff87da0..31a49be 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,112 @@ -# WhatsApp Bridge Integration for Home Assistant ๐Ÿš€ +# WhatsApp Bridge for Home Assistant -This is the custom integration for the **Bahmcloud WhatsApp Bridge**. It allows you to manage multiple WhatsApp accounts as Home Assistant services, making it incredibly easy to send automated messages via YAML or Node-RED. +A professional, seamless integration to send WhatsApp messages through the **Bahmcloud Bridge**. This integration supports multiple profiles, dynamic entity-based selection, and broadcast capabilities with native Home Assistant support. ---- +## ๐Ÿš€ Installation -## ๐Ÿ› ๏ธ Installation - -### 1. Prerequisite: The Add-on -Before installing this integration, ensure that the **WhatsApp Bridge Add-on** is installed and running. -* [Link to your Add-on Repository] -* Open the Add-on Web UI and scan the QR code to link your WhatsApp account. +### 1. Install the Add-on +The **Bahmcloud WhatsApp Bridge Add-on** must be running for the integration to work: +1. Navigate to **Settings** -> **Add-ons**. +2. Click **Add-on Store** -> Three dots (top right) -> **Repositories**. +3. Add your Bahmcloud Repository URL. +4. Search for "WhatsApp Bridge", click **Install**, and **Start**. ### 2. Install the Integration -1. Copy the folder `whatsapp_bridge_integration` into your Home Assistant `config/custom_components/` directory. -2. Restart Home Assistant. -3. Go to **Settings** -> **Devices & Services**. -4. Click **Add Integration** and search for "WhatsApp Bridge Integration". +You can install the integration component via three methods: + +* **HACS (Recommended):** Add this repository as a "Custom Repository" in HACS and click Install. +* **BCS (Bahmcloud Store):** Search for "WhatsApp Bridge" in the BCS interface. +* **Manual:** Copy the `custom_components/whatsapp_bridge_integration` folder into your `/config/custom_components/` directory and restart Home Assistant. --- -## ๐Ÿ“– How to use +## ๐Ÿ‘ฅ Configuration & Profiles -Once installed, the integration provides a new service (action) that you can use in any automation. +Add your WhatsApp accounts via the Home Assistant UI: +1. Go to **Settings** -> **Devices & Services**. +2. Click **Add Integration** and search for **WhatsApp Bridge**. +3. Follow the setup to add an **Account Name** (e.g., "Work") and your **Phone Number**. +4. **Repeat** this process for as many accounts as you need. -### Send a Message via YAML -You can call the service directly in your automations: +### Resulting Entities +The integration automatically creates sensors for your UI: +* `sensor.whatsapp_account_name`: An entity for each individual account. +* `sensor.whatsapp_broadcast_all`: A global entity to message all accounts at once. +--- + +## ๐Ÿ›  Usage + +### Action: `send_message` +This integration registers a service/action to send messages. + +**Fields:** +* **Recipient:** Select an account from the dropdown, choose the "Broadcast" entity, or manually type a phone number. +* **Message:** The text content you wish to send. + +#### YAML Example: ```yaml action: whatsapp_bridge_integration.send_message data: - number: "491701234567" - message: "The washing machine is finished! ๐Ÿงบ" + recipient: "sensor.whatsapp_rene" + message: "The garage door is still open!" ``` -### Use in Node-RED -Add a Call Service (or Action) node. - -Domain: whatsapp_bridge_integration - -Service: send_message - -Data: - -```JSON -{ - "number": "491701234567", - "message": "{{payload}}" -} -``` - -## ๐Ÿ‘ฅ Multi-Account Support (Coming Soon) -We are currently working on a UI-based configuration flow so you can save "Account Aliases" (like "Dad", "Work", "Security") and select them from a dropdown menu without typing the phone number every time. - -##โš ๏ธ Important Notes +## โš ๏ธ Important Notes Phone Numbers: Always use the international format without + or 00 (e.g., 49... for Germany). Local Network: The integration communicates locally with the Add-on on port 3000. Developed by Bahmcloud ---- \ No newline at end of file +--- + +## ๐Ÿค– Node-RED Integration +The integration is fully compatible with Node-RED. Since it uses native entities, you can use the standard *Action (Call Service)* node. + +### Example: Smart Window Warning +Notify yourself if a window or door has been left open for 15 minutes. + + 1. *Trigger*: Use a `State Trigger` or `Device` node. + + 2. *Logic (Change Node)*: Use JSONata to create a dynamic message: + + - *Set*: msg.payload + + - *Value (JSONata)*: `payload.to_state.attributes.friendly_name & " has been open for 15 minutes!"` + + 3. WhatsApp Node (Action Node): + + - *Action*: `whatsapp_bridge_integration.send_message` + + - *Data (JSON)*: + +```JSON +{ + "recipient": "sensor.whatsapp_broadcast_all", + "message": "{{payload}}" +} +``` + +### Manual Tool Calling +To send a message to a number not saved as a profile, simply pass the raw phone number to the recipient field in your Node-RED JSON: + +```JSON +{ + "recipient": "491701234567", + "message": "Direct alert to external number." +} +``` + +--- + +# โœจ Features + - *Dynamic UI*: Accounts are automatically added to the recipient dropdown. + + - *One-Click Broadcast*: Special entity to reach all configured profiles instantly. + + - *Manual Fallback*: Clean UI remains flexible; type any number to bypass profiles. + + - *Developer Friendly*: Designed for easy integration with Node-RED and HA Automations. +--- +Maintained by Bahmcloud \ No newline at end of file