Connect your Home Assistant instance directly to WhatsApp using the "Linked Devices" (Web) protocol. No Business API required. 🚀

Requires the Home Assistant App to function. This integration communicates with the App to send and receive messages.

Component	Version	Status
App (Stable)		engine
App (Edge)		engine-dev
Integration (Stable)		interface
Integration (Beta)		testing
Activity

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.

This project is and will always remain 100% free. There are no "Premium Upgrades", paid features, or subscriptions. Every feature is available to everyone.

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. 💪

1. Click the button above or add this repository as a custom repository in HACS:
   • Go to HACS → Integrations → ⋮ (menu) → Custom repositories
   • Add: https://github.com/FaserF/ha-whatsapp (Category: Integration)
2. Install "Home Assistant WhatsApp" from HACS.
3. Restart Home Assistant.
4. Add the integration via Settings → Devices & Services → Add Integration → WhatsApp.

1. Download the latest release from GitHub Releases.
2. Extract and copy the whatsapp folder to config/custom_components/.
3. Restart Home Assistant.

• 📲 Local & Private: Acts as a "Linked Device" (like WhatsApp Web). No cloud bridge, no external servers.
• 💬 Rich Messaging: Send Text, Images, Videos, Audio (PTT), Documents, and Locations.
• 📊 Interactive Content: Send Polls, Buttons, and List Menus to interact with users.
• 🔄 Two-Way Communication: React to incoming messages, button clicks, and poll votes.
• 🛡️ Modern Standards: Fully compatible with the Home Assistant notify standard (ADR-0010).
• 📝 Message Management: Edit or Revoke (delete) messages after sending.
• 🕵️ Discovery Tools: Built-in service to find Group IDs without checking logs.
• 🤖 Automation Triggers: Real-time events for everything happening on WhatsApp.
• 🛡️ Native Control: Built-in commands (ha-app-*) to check status, restart, or run diagnostics directly via WhatsApp.
• 🔔 Admin Alerts: Proactive system notifications for WhatsApp loss/restore and HA Core/Integration updates.
• 🌍 Localization: Full native support for English and German (DE/EN).

The most up-to-date and detailed documentation is available at our Official Documentation Site.

The integration provides a binary sensor (e.g., binary_sensor.whatsapp).

• State: Indicates if the integration is successfully connected to the App.
• Attributes:
  • messages_sent: Total number of messages sent since restart.
  • last_message_content: Content of the last sent message.
  • last_message_target: Phone number of the last recipient.

If the sensor is disabled, check your Home Assistant "Entities" settings and enable it. It tracks the connection health to the WhatsApp Home Assistant App.

Use these for the most robust experience in YAML.

service: whatsapp.send_message data: target: '+491234567890' message: 'Hello from HA!'

Great for sending to multiple numbers at once or for simple alerts.

service: notify.whatsapp data: message: 'Washing machine is done! 🧺' target: - '+491234567890' - '123456789@g.us'

action: notify.send_message target: entity_id: notify.whatsapp data: message: 'Hello World!'

Gather feedback or make decisions with family/groups.

service: whatsapp.send_poll data: target: '+491234567890' question: 'What should we have for dinner? 🍕' options: - 'Pizza' - 'Sushi' - 'Cooking myself'

Ensure privacy by setting an expiration time (matching chat settings).

service: whatsapp.send_message data: target: '+491234567890' message: 'This message will disappear according to chat rules.' expiration: 86400 # 24 hours

We've provided examples for Personal (Direct) chats and Group chats.

• Direct ID: +491234567890 (Phone number with country code)
• Group ID: 123456789-123456@g.us (Find this via Events, see below)

service: whatsapp.send_message data: target: '+491234567890' message: 'Hello!'

service: whatsapp.send_message data: target: '123456789-123456@g.us' message: 'Hello Everyone! 👋'

service: whatsapp.send_poll data: target: '+491234567890' question: 'Lunch?' options: ['Pizza', 'Sushi']

service: whatsapp.send_poll data: target: '123456789-123456@g.us' question: 'Team Building Activity?' options: - 'Bowling 🎳' - 'Cinema 🍿' - 'Hiking 🥾'

service: whatsapp.send_image data: target: '+491234567890' url: 'https://www.home-assistant.io/images/favicon.jpg' caption: 'Check this out!'

service: whatsapp.send_image data: target: '123456789-123456@g.us' url: 'https://www.home-assistant.io/images/favicon.jpg' caption: 'New Logo Proposal'

service: whatsapp.send_location data: target: '+491234567890' latitude: 52.5200 longitude: 13.4050 name: 'Meeting Point'

service: whatsapp.send_location data: target: '123456789-123456@g.us' latitude: 48.8566 longitude: 2.3522 name: 'Holiday Home' address: 'Paris, France'

Note: Button support varies by WhatsApp version.

service: whatsapp.send_buttons data: target: '+491234567890' message: 'Arm Alarm System?' footer: 'Security Automation' buttons: - id: 'arm_home' displayText: 'Arm Home 🏠' - id: 'arm_away' displayText: 'Arm Away 🛡️'

service: whatsapp.send_buttons data: target: '123456789-123456@g.us' message: 'Who is coming?' buttons: - id: 'yes' displayText: "I'm in!" - id: 'no' displayText: "Can't make it"

service: whatsapp.send_reaction data: target: '123456789-123456@g.us' message_id: 'BAE5F...' # ID from event reaction: '❤️'

service: whatsapp.update_presence data: target: '+491234567890' presence: 'composing' # status: typing...

You can use Home Assistant automations to react to incoming messages, button clicks, and poll votes.

When a user clicks a button, a whatsapp_message_received event is fired with type: button_reply (depending on App version). The most important field is buttonId or selectedId.

alias: Handle Alarm Button trigger: - platform: event event_type: whatsapp_message_received event_data: type: 'button_reply' # Check your event listener for exact type buttonId: 'arm_away' # Matches the ID you sent action: - service: alarm_control_panel.alarm_arm_away target: entity_id: alarm_control_panel.home_alarm - service: whatsapp.send_message data: target: '{{ trigger.event.data.from }}' message: 'Alarm Armed! 🛡️'

Polls fire updates when votes change.

alias: Pizza Poll Handler trigger: - platform: event event_type: whatsapp_message_received event_data: type: 'poll_update' condition: - condition: template value_template: "{{ 'Pizza' in trigger.event.data.vote }}" action: - service: whatsapp.send_message data: target: '{{ trigger.event.data.from }}' message: 'Great choice! 🍕' 

alias: WhatsApp Auto-Reply trigger: - platform: event event_type: whatsapp_message_received event_data: content: 'Status' condition: [] action: - service: whatsapp.send_message data: target: '{{ trigger.event.data.from }}' message: "System is Online! 🟢\nBattery: {{ states('sensor.phone_battery_level') }}%"

This integration works in tandem with the WhatsApp App, which provides several built-in features that don't require any YAML configuration:

If you are configured as an Admin, you can control the addon directly via WhatsApp by sending:

• ha-app-status: Full health check (Versions, Uptime, Memory).
• ha-app-help: List all available control commands.
• ha-app-logs: View the latest connection events.
• ha-app-diagnose: Run a full diagnostic of all message types.
• ha-app-restart: Trigger a reconnect of the WhatsApp session.

The app can automatically notify administrators about critical events:

• ✅ Update Success: Reports when HA Core, the Addon, or this Integration has been successfully updated.
• 🔄 HA Restart: Notifies you when HA Core is back online after a restart/reboot.
• 🌐 Connectivity: Alerts if the connection to WhatsApp or HA Core is lost/restored, including downtime duration.

The bot automatically sends a role-aware greeting to new users on their first direct contact, ensuring they know how to interact with the system.

To send messages, you need a target ID. The integration makes finding these very easy.

Use the phone number in international format. The integration automatically adds the required suffix.

• Example: +491234567890 or 491234567890

Group IDs look like 120363012345678901@g.us. Instead of searching through logs or listening to events, use the built-in Search Service:

1. Go to Developer Tools → Services.
2. Select whatsapp.search_groups.
3. (Optional) Enter a name_filter.
4. Click Call Service.
5. Check your Notifications (Bell icon 🔔 in the sidebar)! A table with all your groups and their IDs will appear instantly.

If you need the ID of a specific incoming message or a dynamic sender:

1. Go to Developer Tools → Events.
2. Listen to whatsapp_message_received.
3. Send a message to the bot. The ID is in the from field.

WhatsApp Web protocols are complex and require a headless browser to maintain encryption and session state.

• The App: Runs the browser (Puppeteer/Playwright), handles QR scanning, and encryption.
• The Integration: Connects to the App API to expose services and sensors to Home Assistant.

You Must install the App from the repo above for this to work.

We use a structured release cycle to ensure stability while providing new features:

• Stable (v1.x.x): Recommended for all users. Tested and verified for production use.
• Beta (v1.x.xbX): Public testing of new features. Recommended if you want the latest tech and can provide feedback. Available via HACS "Redownload" -> "Show beta versions".
• Edge/Dev (v1.x.x-dev): Bleeding edge from the master branch. May be unstable. Only for developers.

Releases are automatically created when the version in manifest.json is updated.

MIT License. Open Source & Free. ❤️