{"id":42287502,"url":"https://github.com/faserf/ha-whatsapp","last_synced_at":"2026-03-14T15:52:29.544Z","repository":{"id":331638886,"uuid":"1121936240","full_name":"FaserF/ha-whatsapp","owner":"FaserF","description":"Homeassistant Integration to interact with WhatsApp","archived":false,"fork":false,"pushed_at":"2026-01-27T17:15:05.000Z","size":686,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-27T20:28:51.247Z","etag":null,"topics":["baileys-bot","hacs-integration","homeassistant"],"latest_commit_sha":null,"homepage":"https://faserf.github.io/ha-whatsapp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FaserF.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-23T20:11:42.000Z","updated_at":"2026-01-27T17:15:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/FaserF/ha-whatsapp","commit_stats":null,"previous_names":["faserf/ha-whatsapp"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/FaserF/ha-whatsapp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-whatsapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-whatsapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-whatsapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-whatsapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FaserF","download_url":"https://codeload.github.com/FaserF/ha-whatsapp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-whatsapp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28928671,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T02:59:34.861Z","status":"ssl_error","status_checked_at":"2026-01-31T02:59:05.369Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["baileys-bot","hacs-integration","homeassistant"],"created_at":"2026-01-27T09:22:38.569Z","updated_at":"2026-03-14T15:52:29.533Z","avatar_url":"https://github.com/FaserF.png","language":"Python","funding_links":["https://github.com/sponsors/FaserF)","https://paypal.me/FaserF"],"categories":[],"sub_categories":[],"readme":"# 💬 HA WhatsApp Integration\n\n\u003cimg src=\"https://upload.wikimedia.org/wikipedia/commons/6/6b/WhatsApp.svg\" width=\"100\" alt=\"WhatsApp Logo\"\u003e\n\n[![HACS Custom](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/hacs/integration)\n[![GitHub Release](https://img.shields.io/github/release/FaserF/ha-whatsapp.svg)](https://github.com/FaserF/ha-whatsapp/releases)\n\n\u003e Connect your Home Assistant instance directly to WhatsApp using the \"Linked Devices\" (Web) protocol. No Business API required. 🚀\n\u003e\n\u003e **Requires the [Home Assistant App](https://github.com/FaserF/hassio-addons) to function.** This integration communicates with the App to send and receive messages.\n\n---\n\n| Component                | Version                                                                                                                                                                                                                                                                               | Status     |\n| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------- |\n| **App (Stable)**         | [![App Version](https://img.shields.io/github/v/release/FaserF/hassio-addons?filter=whatsapp\u0026label=App\u0026style=flat-square)](https://github.com/FaserF/hassio-addons/tree/master/whatsapp)                                                                                              | engine     |\n| **App (Edge)**           | [![App Edge](https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2FFaserF%2Fhassio-addons%2Fedge%2Fwhatsapp%2Fconfig.yaml\u0026query=%24.version\u0026label=Edge\u0026style=flat-square\u0026color=orange)](https://github.com/FaserF/hassio-addons/tree/edge/whatsapp) | engine-dev |\n| **Integration (Stable)** | [![Integration Stable](https://img.shields.io/github/v/release/FaserF/ha-whatsapp?style=flat-square\u0026label=Stable)](https://github.com/FaserF/ha-whatsapp/releases)                                                                                                                    | interface  |\n| **Integration (Beta)**   | [![Integration Beta](https://img.shields.io/github/v/release/FaserF/ha-whatsapp?include_prereleases\u0026style=flat-square\u0026label=Beta\u0026color=orange)](https://github.com/FaserF/ha-whatsapp/releases)                                                                                       | testing    |\n| **Activity**             | [![Last Commit](https://img.shields.io/github/last-commit/FaserF/ha-whatsapp?style=flat-square\u0026label=Last%20Update)](https://github.com/FaserF/ha-whatsapp/commits/master)                                                                                                                  |            |\n\n\n---\n\n## ❤️ Support This Project\n\n\u003e I maintain this integration in my **free time alongside my regular job** — bug hunting, new features, testing on real devices. Test hardware costs money, and every donation helps me stay independent and dedicate more time to open-source work.\n\u003e\n\u003e **This project is and will always remain 100% free.** There are no \"Premium Upgrades\", paid features, or subscriptions. Every feature is available to everyone.\n\u003e\n\u003e Donations are completely voluntary — but the more support I receive, the less I depend on other income sources and the more time I can realistically invest into these projects. 💪\n\n\u003cdiv align=\"center\"\u003e\n\n[![GitHub Sponsors](https://img.shields.io/badge/Sponsor%20on-GitHub-%23EA4AAA?style=for-the-badge\u0026logo=github-sponsors\u0026logoColor=white)](https://github.com/sponsors/FaserF)\u0026nbsp;\u0026nbsp;\n[![PayPal](https://img.shields.io/badge/Donate%20via-PayPal-%2300457C?style=for-the-badge\u0026logo=paypal\u0026logoColor=white)](https://paypal.me/FaserF)\n\n\u003c/div\u003e\n\n---\n\n\u003e [!CAUTION]\n\u003e **Legal Disclaimer / Haftungsausschluss**\n\u003e\n\u003e Using this integration may violate WhatsApp's **[Terms of Service](https://www.whatsapp.com/legal/terms-of-service/)**. WhatsApp explicitly prohibits unauthorized automated or bulk messaging.\n\u003e\n\u003e **The developers of this project assume no liability for any banned or blocked accounts.** Use at your own risk. For more information, please read the official **[Terms of Service](https://www.whatsapp.com/legal/terms-of-service/)**.\n\n---\n\n## 📥 Installation\n\n### HACS (Recommended)\n\n[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository?owner=FaserF\u0026repository=ha-whatsapp\u0026category=integration)\n\n1. Click the button above or add this repository as a **custom repository** in HACS:\n   - Go to HACS → Integrations → ⋮ (menu) → Custom repositories\n   - Add: `https://github.com/FaserF/ha-whatsapp` (Category: Integration)\n2. Install \"Home Assistant WhatsApp\" from HACS.\n3. Restart Home Assistant.\n4. Add the integration via Settings → Devices \u0026 Services → Add Integration → WhatsApp.\n\n### Manual Installation\n\n1. Download the latest release from [GitHub Releases](https://github.com/FaserF/ha-whatsapp/releases).\n2. Extract and copy the `whatsapp` folder to `config/custom_components/`.\n3. Restart Home Assistant.\n\n---\n\n## 🌟 Features\n\n- **📲 Local \u0026 Private**: Acts as a \"Linked Device\" (like WhatsApp Web). No cloud bridge, no external servers.\n- **💬 Rich Messaging**: Send Text, Images, Videos, Audio (PTT), Documents, and Locations.\n- **📊 Interactive Content**: Send Polls, Buttons, and List Menus to interact with users.\n- **🔄 Two-Way Communication**: React to incoming messages, button clicks, and poll votes.\n- **🛡️ Modern Standards**: Fully compatible with the Home Assistant `notify` standard (ADR-0010).\n- **📝 Message Management**: Edit or Revoke (delete) messages after sending.\n- **🕵️ Discovery Tools**: Built-in service to find Group IDs without checking logs.\n- **🤖 Automation Triggers**: Real-time events for everything happening on WhatsApp.\n- **🛡️ Native Control**: Built-in commands (`ha-app-*`) to check status, restart, or run diagnostics directly via WhatsApp.\n- **🔔 Admin Alerts**: Proactive system notifications for WhatsApp loss/restore and HA Core/Integration updates.\n- **🌍 Localization**: Full native support for English and German (DE/EN).\n\n---\n\n## 📚 Documentation\n\nThe most up-to-date and detailed documentation is available at our **[Official Documentation Site](https://faserf.github.io/ha-whatsapp/)**.\n\n| Guide                                                      | Description                                               |\n| :--------------------------------------------------------- | :-------------------------------------------------------- |\n| **[🚀 Full Guide](https://faserf.github.io/ha-whatsapp/)** | Installation, Services, Automations, and Pro-Tips.        |\n| **[📚 Whitelist Guide](docs/configuration.md#security-whitelist-feature)** | Restrict interaction to specific users/groups.            |\n| **[🔘 Buttons Guide](docs/buttons.md)**                     | Deep dive into interactive buttons and limitations.       |\n| **[📖 Local Examples](EXAMPLES.md)**                       | Quick reference for YAML snippets inside this repository. |\n| **[🛠️ Troubleshooting](docs/troubleshooting.md)**          | Diagnostic tools and fixing common connection issues.     |\n\n---\n\n## 💡 How to use\n\n### The WhatsApp Sensor\n\nThe integration provides a binary sensor (e.g., `binary_sensor.whatsapp`).\n\n- **State**: Indicates if the integration is successfully connected to the App.\n- **Attributes**:\n  - `messages_sent`: Total number of messages sent since restart.\n  - `last_message_content`: Content of the last sent message.\n  - `last_message_target`: Phone number of the last recipient.\n\nIf the sensor is `disabled`, check your Home Assistant \"Entities\" settings and enable it. It tracks the connection health to the WhatsApp Home Assistant App.\n\n### Services\n\n#### 1. Native WhatsApp Services (Recommended)\n\nUse these for the most robust experience in YAML.\n\n```yaml\nservice: whatsapp.send_message\ndata:\n  target: '+491234567890'\n  message: 'Hello from HA!'\n```\n\n#### 2. Legacy Notify (`notify.whatsapp`)\n\nGreat for sending to multiple numbers at once or for simple alerts.\n\n```yaml\nservice: notify.whatsapp\ndata:\n  message: 'Washing machine is done! 🧺'\n  target:\n    - '+491234567890'\n    - '123456789@g.us'\n```\n\n#### 3. Modern Notify Action (`notify.send_message`)\n\n\u003e [!WARNING]\n\u003e Only use this in the **Visual Editor (UI)**. In YAML, it often fails with `extra keys not allowed`.\n\n```yaml\naction: notify.send_message\ntarget:\n  entity_id: notify.whatsapp\ndata:\n  message: 'Hello World!'\n```\n\n#### 4. Interactive Polls 📊\n\nGather feedback or make decisions with family/groups.\n\n```yaml\nservice: whatsapp.send_poll\ndata:\n  target: '+491234567890'\n  question: 'What should we have for dinner? 🍕'\n  options:\n    - 'Pizza'\n    - 'Sushi'\n    - 'Cooking myself'\n```\n\n#### 5. Disappearing Messages ⏳\n\nEnsure privacy by setting an expiration time (matching chat settings).\n\n```yaml\nservice: whatsapp.send_message\ndata:\n  target: '+491234567890'\n  message: 'This message will disappear according to chat rules.'\n  expiration: 86400 # 24 hours\n```\n\n### Service Examples\n\nWe've provided examples for **Personal (Direct)** chats and **Group** chats.\n\n- **Direct ID**: `+491234567890` (Phone number with country code)\n- **Group ID**: `123456789-123456@g.us` (Find this via Events, see below)\n\n#### 1. Send Text Message 📝\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to show YAML examples\u003c/summary\u003e\n\n**Direct Chat:**\n\n```yaml\nservice: whatsapp.send_message\ndata:\n  target: '+491234567890'\n  message: 'Hello!'\n```\n\n**Group Chat:**\n\n```yaml\nservice: whatsapp.send_message\ndata:\n  target: '123456789-123456@g.us'\n  message: 'Hello Everyone! 👋'\n```\n\n\u003c/details\u003e\n\n#### 2. Send Polls 📊\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to show YAML examples\u003c/summary\u003e\n\n**Direct Chat:**\n\n```yaml\nservice: whatsapp.send_poll\ndata:\n  target: '+491234567890'\n  question: 'Lunch?'\n  options: ['Pizza', 'Sushi']\n```\n\n**Group Chat:**\n\n```yaml\nservice: whatsapp.send_poll\ndata:\n  target: '123456789-123456@g.us'\n  question: 'Team Building Activity?'\n  options:\n    - 'Bowling 🎳'\n    - 'Cinema 🍿'\n    - 'Hiking 🥾'\n```\n\n\u003c/details\u003e\n\n#### 3. Send Image 🖼️\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to show YAML examples\u003c/summary\u003e\n\n**Direct Chat:**\n\n```yaml\nservice: whatsapp.send_image\ndata:\n  target: '+491234567890'\n  url: 'https://www.home-assistant.io/images/favicon.jpg'\n  caption: 'Check this out!'\n```\n\n**Group Chat:**\n\n```yaml\nservice: whatsapp.send_image\ndata:\n  target: '123456789-123456@g.us'\n  url: 'https://www.home-assistant.io/images/favicon.jpg'\n  caption: 'New Logo Proposal'\n```\n\n\u003c/details\u003e\n\n#### 4. Send Location 📍\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to show YAML examples\u003c/summary\u003e\n\n**Direct Chat:**\n\n```yaml\nservice: whatsapp.send_location\ndata:\n  target: '+491234567890'\n  latitude: 52.5200\n  longitude: 13.4050\n  name: 'Meeting Point'\n```\n\n**Group Chat:**\n\n```yaml\nservice: whatsapp.send_location\ndata:\n  target: '123456789-123456@g.us'\n  latitude: 48.8566\n  longitude: 2.3522\n  name: 'Holiday Home'\n  address: 'Paris, France'\n```\n\n\u003c/details\u003e\n\n#### 5. Send Buttons 🔘\n\n_Note: Button support varies by WhatsApp version._\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to show YAML examples\u003c/summary\u003e\n\n**Direct Chat:**\n\n```yaml\nservice: whatsapp.send_buttons\ndata:\n  target: '+491234567890'\n  message: 'Arm Alarm System?'\n  footer: 'Security Automation'\n  buttons:\n    - id: 'arm_home'\n      displayText: 'Arm Home 🏠'\n    - id: 'arm_away'\n      displayText: 'Arm Away 🛡️'\n```\n\n**Group Chat:**\n\n```yaml\nservice: whatsapp.send_buttons\ndata:\n  target: '123456789-123456@g.us'\n  message: 'Who is coming?'\n  buttons:\n    - id: 'yes'\n      displayText: \"I'm in!\"\n    - id: 'no'\n      displayText: \"Can't make it\"\n```\n\n\u003c/details\u003e\n\n#### 6. Reactions \u0026 Presence\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to show YAML examples\u003c/summary\u003e\n\n**React to a message** (Direct or Group):\n\n```yaml\nservice: whatsapp.send_reaction\ndata:\n  target: '123456789-123456@g.us'\n  message_id: 'BAE5F...' # ID from event\n  reaction: '❤️'\n```\n\n**Set Presence** (Direct or Group):\n\n```yaml\nservice: whatsapp.update_presence\ndata:\n  target: '+491234567890'\n  presence: 'composing' # status: typing...\n```\n\n\u003c/details\u003e\n\n### 🤖 Automating Replies\n\nYou can use Home Assistant automations to react to **incoming messages**, **button clicks**, and **poll votes**.\n\n#### 1. React to a Button Click\n\nWhen a user clicks a button, a `whatsapp_message_received` event is fired with `type: button_reply` (depending on App version).\nThe most important field is `buttonId` or `selectedId`.\n\n```yaml\nalias: Handle Alarm Button\ntrigger:\n  - platform: event\n    event_type: whatsapp_message_received\n    event_data:\n      type: 'button_reply' # Check your event listener for exact type\n      buttonId: 'arm_away' # Matches the ID you sent\naction:\n  - service: alarm_control_panel.alarm_arm_away\n    target:\n      entity_id: alarm_control_panel.home_alarm\n  - service: whatsapp.send_message\n    data:\n      target: '{{ trigger.event.data.from }}'\n      message: 'Alarm Armed! 🛡️'\n```\n\n#### 2. React to a Poll Vote\n\nPolls fire updates when votes change.\n\n```yaml\nalias: Pizza Poll Handler\ntrigger:\n  - platform: event\n    event_type: whatsapp_message_received\n    event_data:\n      type: 'poll_update'\ncondition:\n  - condition: template\n    value_template: \"{{ 'Pizza' in trigger.event.data.vote }}\"\naction:\n  - service: whatsapp.send_message\n    data:\n      target: '{{ trigger.event.data.from }}'\n      message: 'Great choice! 🍕'\n```\n\n#### 3. General Message Handler\n\n```yaml\nalias: WhatsApp Auto-Reply\ntrigger:\n  - platform: event\n    event_type: whatsapp_message_received\n    event_data:\n      content: 'Status'\ncondition: []\naction:\n  - service: whatsapp.send_message\n    data:\n      target: '{{ trigger.event.data.from }}'\n      message: \"System is Online! 🟢\\nBattery: {{ states('sensor.phone_battery_level') }}%\"\n```\n\n---\n\n---\n\n## 🗝️ Native Control \u0026 Notifications\n\nThis integration works in tandem with the [WhatsApp App](https://github.com/FaserF/hassio-addons/tree/master/whatsapp), which provides several built-in features that don't require any YAML configuration:\n\n### 🎮 Control Commands\nIf you are configured as an **Admin**, you can control the addon directly via WhatsApp by sending:\n- `ha-app-status`: Full health check (Versions, Uptime, Memory).\n- `ha-app-help`: List all available control commands.\n- `ha-app-logs`: View the latest connection events.\n- `ha-app-diagnose`: Run a full diagnostic of all message types.\n- `ha-app-restart`: Trigger a reconnect of the WhatsApp session.\n\n### 🔔 System Status Notifications\nThe app can automatically notify administrators about critical events:\n- **✅ Update Success**: Reports when HA Core, the Addon, or this Integration has been successfully updated.\n- **🔄 HA Restart**: Notifies you when HA Core is back online after a restart/reboot.\n- **🌐 Connectivity**: Alerts if the connection to WhatsApp or HA Core is lost/restored, including downtime duration.\n\n### 👋 Welcome Message\nThe bot automatically sends a role-aware greeting to new users on their first direct contact, ensuring they know how to interact with the system.\n\n---\n\n## 🆔 Finding Chat IDs \u0026 Group IDs\n\nTo send messages, you need a `target` ID. The integration makes finding these very easy.\n\n### 1. Private Chats (Phone Numbers)\nUse the phone number in international format. The integration automatically adds the required suffix.\n- **Example**: `+491234567890` or `491234567890`\n\n### 2. Group IDs (The Easy Way) 🏆\nGroup IDs look like `120363012345678901@g.us`. Instead of searching through logs or listening to events, use the built-in **Search Service**:\n\n1. Go to **Developer Tools** → **Services**.\n2. Select `whatsapp.search_groups`.\n3. (Optional) Enter a `name_filter`.\n4. Click **Call Service**.\n5. **Check your Notifications (Bell icon 🔔 in the sidebar)!** A table with all your groups and their IDs will appear instantly.\n\n### 3. Listening to Events (Advanced)\nIf you need the ID of a specific incoming message or a dynamic sender:\n1. Go to **Developer Tools** → **Events**.\n2. Listen to `whatsapp_message_received`.\n3. Send a message to the bot. The ID is in the `from` field.\n\n---\n\n## 🛠️ Requirements \u0026 App\n\n\u003e [!IMPORTANT]\n\u003e **This integration DOES NOT work alone.**\n\u003e It is strictly a bridge to the **[HA WhatsApp Home Assistant App](https://github.com/FaserF/hassio-addons/tree/master/whatsapp)**.\n\n### Why?\n\nWhatsApp Web protocols are complex and require a headless browser to maintain encryption and session state.\n\n- **The App**: Runs the browser (Puppeteer/Playwright), handles QR scanning, and encryption.\n- **The Integration**: Connects to the App API to expose services and sensors to Home Assistant.\n\nYou **Must** install the App from the repo above for this to work.\n\n---\n\n## 🏷️ Versioning \u0026 Releases\n\nWe use a structured release cycle to ensure stability while providing new features:\n\n- **Stable (v1.x.x)**: Recommended for all users. Tested and verified for production use.\n- **Beta (v1.x.xbX)**: Public testing of new features. Recommended if you want the latest tech and can provide feedback. Available via HACS \"Redownload\" -\u003e \"Show beta versions\".\n- **Edge/Dev (v1.x.x-dev)**: Bleeding edge from the master branch. May be unstable. Only for developers.\n\nReleases are automatically created when the version in `manifest.json` is updated.\n\n---\n\n## 📜 License\n\nMIT License. Open Source \u0026 Free. ❤️\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaserf%2Fha-whatsapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaserf%2Fha-whatsapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaserf%2Fha-whatsapp/lists"}