WhatsApp for Home Assistant

New in 2.0: decrypt incoming media. Receive ready-to-use local files and authenticated links for photos, voice notes, documents, videos, and stickers. Use them in Home Assistant OCR, transcription, and other processing automations, with automatic retention and unique files for every attachment.

Send WhatsApp messages from Home Assistant automations and receive message, call, and presence events through the companion add-on.

Examples

Topic	Examples
Messages and media	Text, stickers, documents, videos, polls, voice messages, locations, reactions, edits, deletion, and quoted follow-ups.
Recipients and number lookup	Phone JIDs, LIDs, group ID discovery, and registration checks.
Presence	Subscriptions, online notifications, typing indicators, and a bounded typing loop.
Automations	Calls, logging, replies, read markers, arrival messages, sensor alerts, and webhooks.
Reusable scripts	Return send responses, quote notifications, save message keys, and send files prepared by helpers.
Incoming messages and agents	Filter chats, extract text, reply with a conversation agent, and recognize incoming media.
AI-written notifications	Rephrase routine notifications with a fallback to the original text.
Conversation history	Keep recent exchanges in a file and use them in replies to one chat.
Sensor charts	Log readings to Google Sheets and send a published chart with a sensor alert.

Reference

• Actions: the Home Assistant actions exposed by the integration.
• Events: message, call, presence, send-result, and health events.

The examples use fictional phone numbers and synthetic identifiers. Replace clientId, recipients, and entity IDs with the values from your installation.

Examples that need another integration or a custom helper list that dependency.

Setup and support

• Installation and configuration
• Add-on options and web UI
• Troubleshooting
• Support
• Changelog

Important limitation

This project uses WhatsApp Web through an unofficial client library. WhatsApp does not officially support bots or unofficial clients, so account restrictions or blocking are possible. Use a dedicated account if that risk matters to you.

Privacy

WhatsApp message and call events and Home Assistant automation traces can contain phone JIDs, LIDs, call and message keys, quoted-message data, and message bodies. The add-on does not log raw identifiers or message bodies, but Home Assistant may retain event and action data. Redact these fields, QR codes, session data, and api_token before sharing diagnostics, logs, screenshots, or traces.