WhatsApp Integration for Home Assistant (Marketplace integration)

Installs: Not shown: shared domain whatsapp
GitHub stars: 53
Connection: Works locally
Upkeep: Updated in the last 6 months
Version: v2.1.6, October 27, 2026
Category: Messaging and notifications, Chat apps
Kind: Marketplace integration
Brand: WhatsApp
Needs: Needs the Marketplace (HACS on 2026.10 and older)
Domain: whatsapp
Source: github.com/FaserF/ha-whatsapp
Issues: Report an issue

Independent directory, made by the developer of Vulpo. Not affiliated with Home Assistant or the Open Home Foundation.

About

WhatsApp Integration connects Home Assistant to WhatsApp as a linked device, the same way WhatsApp Web does. It works locally and relies on a separate gateway, either the Home Assistant app or a standalone Docker container, to send and receive messages. Actions cover sending text, documents, video, audio, contacts, list messages, buttons, reactions and group events, plus editing or revoking sent messages. Incoming messages, button clicks and poll votes can trigger automations. It also offers group moderation with captchas, warnings and an anti-raid shield, and a bridge that mirrors messages to Telegram. Sensors track sent, received and failed messages, switches toggle moderation, the bridge and auto responder, and repair notices flag connection or session problems. Setup happens in the UI.

Automatic summary of the README and code of FaserF/ha-whatsapp. Something wrong, or are you the maintainer and want your own text here? Get in touch

Supports

Works locally Talks to your devices on your own network. No vendor cloud in between.
Found by itself Home Assistant spots it on the network and offers to add it.
From the Marketplace Installed through the Marketplace, formerly HACS.
Actively maintained Its author released or pushed a change in the last six months.

Provides

Switches
Sensors

Setting it up

Install it from the Marketplace and restart Home Assistant, then add it under Settings, Devices and services.

Connect WhatsApp Integration

Addon Host URL
API Token (from Addon UI)

Install official Add-on

Add-on Version

Scan QR Code

Request new QR Code
Pair with Phone Number instead

Pair with Phone Number

Phone Number (with country code, e.g. 49151...)

WhatsApp Passkey Required

Try Option 2: Approve passkey on phone (experimental)

Existing Session Found

How would you like to proceed?

After setup

Debug Payloads (Log incoming events)
Polling Interval (Seconds)
Mask Sensitive Data in Logs
Mark messages as read (send blue ticks)
API Key
Retry Attempts (on failure)
Whitelisted Users/Groups (Comma-separated phone numbers or Group IDs. Leave empty for no whitelist)
Process messages from self (Legacy fallback; message_sent event is recommended)
Emulate Buttons via Polls (Converts send_buttons to native Polls & fires button events on vote)
Reset Session (Logout & Clear Data)
Recipient Aliases (YAML dict mapping names to numbers/JIDs)

Texts from the code of FaserF/ha-whatsapp.

Entities

Binary sensorsConnection, WhatsApp Moderation Engine, Telegram Bridge Status
ButtonsDiagnostic Test, Restart WhatsApp Session
NotifiersWhatsApp Integration
SensorsMessages Sent, Messages Received, Messages Failed, WhatsApp Version, Phone Number, Chats, Active Moderation Warnings, Anti-Raid Shield Status, Pending Captcha Verifications
SwitchesModeration Engine, Telegram Bridge, Auto Responder

Actions

Send MessageSends a text message to a WhatsApp number.Fields: Message, Target Number, Account, Quote Message ID, Reply To Message ID, Expiration (Seconds)
Send DocumentSends a document (PDF, Zip, Doc, etc.) to a WhatsApp number.Fields: Target Number, URL, File Name, Caption
Send VideoSends a video file to a WhatsApp number.Fields: Target Number, URL, Caption
Send AudioSends an audio file or voice note.Fields: Target Number, URL, Voice Note (PTT), Account
Revoke MessageDeletes a sent message for everyone.Fields: Target Number, Message ID
Edit MessageEdits the text of a sent message.Fields: Target Number, Message ID, New Text
Send List MessageSends an interactive list (action menu).Fields: Target Number, Title, Body Text, Button Label, Sections (JSON)
Send ContactSends a contact card (VCard).Fields: Target Number, Display Name, Contact Number
Configure WebhookSets the webhook URL for the Addon to push events to.Fields: Webhook URL, Enabled, Token
Send ReactionReacts to a message with an emoji.Fields: Reaction, Target Number, Message ID
Update PresenceUpdates your presence status (e.g. typing).Fields: Presence, Target Number
Send ButtonsSends a message with interactive buttons.Fields: Target Number, Message, Buttons, Footer
Send EventSends an interactive WhatsApp Group Event message.Fields: Account, Target Number / Group ID, Event Name, Description, Date & Time, Location, Join Link, Is Canceled, Expiration (Seconds)

Troubleshooting

DiagnosticsDownloads a diagnostics file to attach to a bug report.
Repair noticesNotices it can show in Settings, Repairs:Connection to WhatsApp Addon failed, WhatsApp session expired, WhatsApp connection interrupted, WhatsApp Passkey Required — Action Needed

From the README

Connect your Home Assistant instance directly to WhatsApp using the "Linked Devices" (Web) protocol. No Business API required. 🚀
Requires the Home Assistant App OR the Standalone Docker Gateway (whatsapp-gw) to function. This integration communicates with the Gateway (App or Standalone Container) to send and receive messages.
📲 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.
🛡️ Group Moderation & Defender: Comprehensive group defender, welcome/goodbye messages with departure reasons, captchas (Group & Private DM resolution with Web UI status dashboard), configurable…

From the README of FaserF/ha-whatsapp, MIT License. Shortened.