---
title: "WhatsApp Integration"
description: "WhatsApp Integration is a Marketplace integration for Home Assistant. Its installs are not shown, because another integration uses the same domain, whatsapp. It works locally and was last updated October 27, 2026."
canonical: "https://vulpo.app/integrations/marketplace/faserf-ha-whatsapp"
url: "https://vulpo.app/integrations/marketplace/faserf-ha-whatsapp.md"
last-updated: "2026-10-27"
version: "1.4"
---

# WhatsApp Integration

> WhatsApp Integration is a Marketplace integration for Home Assistant. Its installs are not shown, because another integration uses the same domain, whatsapp. It works locally and was last updated October 27, 2026.

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](https://vulpo.app/contact)

[Open in My Home Assistant](https://my.home-assistant.io/redirect/hacs_repository/?owner=FaserF&repository=ha-whatsapp&category=integration)

On Home Assistant 2026.11 or newer? [Open it in the Marketplace](https://my.home-assistant.io/redirect/marketplace_repository/?owner=FaserF&repository=ha-whatsapp&category=integration)

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

## 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](https://github.com/FaserF/ha-whatsapp).

## Entities

- **Binary sensors**: Connection, WhatsApp Moderation Engine, Telegram Bridge Status
- **Buttons**: Diagnostic Test, Restart WhatsApp Session
- **Notifiers**: WhatsApp Integration
- **Sensors**: Messages Sent, Messages Received, Messages Failed, WhatsApp Version, Phone Number, Chats, Active Moderation Warnings, Anti-Raid Shield Status, Pending Captcha Verifications
- **Switches**: Moderation Engine, Telegram Bridge, Auto Responder

## Actions

- **Send Message**: Sends a text message to a WhatsApp number.
  Fields: Message, Target Number, Account, Quote Message ID, Reply To Message ID, Expiration (Seconds)
- **Send Document**: Sends a document (PDF, Zip, Doc, etc.) to a WhatsApp number.
  Fields: Target Number, URL, File Name, Caption
- **Send Video**: Sends a video file to a WhatsApp number.
  Fields: Target Number, URL, Caption
- **Send Audio**: Sends an audio file or voice note.
  Fields: Target Number, URL, Voice Note (PTT), Account
- **Revoke Message**: Deletes a sent message for everyone.
  Fields: Target Number, Message ID
- **Edit Message**: Edits the text of a sent message.
  Fields: Target Number, Message ID, New Text
- **Send List Message**: Sends an interactive list (action menu).
  Fields: Target Number, Title, Body Text, Button Label, Sections (JSON)
- **Send Contact**: Sends a contact card (VCard).
  Fields: Target Number, Display Name, Contact Number
- **Configure Webhook**: Sets the webhook URL for the Addon to push events to.
  Fields: Webhook URL, Enabled, Token
- **Send Reaction**: Reacts to a message with an emoji.
  Fields: Reaction, Target Number, Message ID
- **Update Presence**: Updates your presence status (e.g. typing).
  Fields: Presence, Target Number
- **Send Buttons**: Sends a message with interactive buttons.
  Fields: Target Number, Message, Buttons, Footer
- **Send Event**: Sends 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

- **Diagnostics**: Downloads a diagnostics file to attach to a bug report.
- **Repair notices**: Notices 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](https://github.com/FaserF/ha-whatsapp#readme), [MIT License](https://spdx.org/licenses/MIT.html). Shortened.

## At a glance

- Kind: Marketplace integration
- Category: [Messaging and notifications](https://vulpo.app/integrations/category/messaging-and-notifications.md), Chat apps
- Brand: [WhatsApp](https://vulpo.app/integrations/whatsapp.md)
- Number: Installs not shown: shared domain whatsapp; 53 GitHub stars
- Connection: Works locally
- Upkeep: Updated in the last 6 months
- Needs: Needs the Marketplace (HACS on 2026.10 and older)
- Latest version: v2.1.6, last updated October 27, 2026
- Domain: `whatsapp`
- Source: <https://github.com/FaserF/ha-whatsapp>
- Issues: <https://github.com/FaserF/ha-whatsapp/issues/>

In Vulpo: Quick Toggle card, Button card, Chart card, Apple Watch, Control Center

## Other ways in for WhatsApp

| Name | Kind | Installs or stars | Connection | Upkeep |
| --- | --- | --- | --- | --- |
| [WhatsApp](https://github.com/moryoav/ha-addons) | Marketplace integration | Installs not shown: shared domain whatsapp | Works locally | Updated in the last 6 months |
| [Whatsapp notifier basde on manish api wrapper for whatsapp cloud api](https://github.com/t0mer/manish-custom-notifier) | Marketplace integration | No installs sharing analytics yet | Works locally | Updated in the last 6 months |
| [Whatsapp Theme](https://github.com/robinwittebol/whatsapp-theme) | Theme | 19 GitHub stars | Connection not stated | No update in 6 to 18 months |

Independent directory, made by the developer of Vulpo. Not affiliated with Home Assistant or the Open Home Foundation. [About these numbers](https://vulpo.app/integrations/about)

Last updated 2026-10-27. Source: https://vulpo.app/integrations/marketplace/faserf-ha-whatsapp

---

- HTML version of this page: https://vulpo.app/integrations/marketplace/faserf-ha-whatsapp
- Site index for agents: https://vulpo.app/llms.txt
- Everything in one document: https://vulpo.app/llms-full.txt
- All pages: https://vulpo.app/sitemap.xml