🛠️ Troubleshooting & Diagnostics

If your WhatsApp integration isn’t sending messages as expected, use these tools and steps to identify the issue.

🧪 Automated Diagnostic Self-Test

The integration includes a hidden Diagnostic Test button that performs a series of end-to-end tests by sending messages to your own WhatsApp account.

How to use

Go to Settings → Devices & Services → WhatsApp.
Click on the 1 device link.
In the Entities list, find the entity called WhatsApp Diagnostic Test (it is disabled by default to avoid accidental triggers).
Enable the entity, wait a few seconds, and then you can use it.
Click Press on the button.

What it tests

The button will automatically attempt the following steps to your own number:

Text Message: Standard text delivery.
Reaction: Sending a reaction to a message.
Buttons: Interactive button message delivery.
List: Interactive list menu delivery.
Location: Dummy location (Munich) delivery.
Auto-Delete: Message revocation (deletion).

Interpreting Results

After processing, check the Attributes of the button in Home Assistant. Each step will report either OK or a specific Error: [Message].

Result	Meaning
`OK`	The addon successfully sent the command and WhatsApp confirmed receipt.
`Error: 401`	Unauthorized. Check your API Key in the integration configuration.
`Error: 404`	Not Found. The bot might not be connected to WhatsApp yet.
`Error: Whitelist`	Your own number is not in the whitelist (this should be bypassed automatically, but check if manual issues occur).

🗝️ Native App Diagnostics

Since the App handles the WhatsApp connection logic, several diagnostic tools are built directly into the WhatsApp interface. If you are an Admin, you can send these commands to the bot:

ha-app-diagnose: Performs a full self-test of all message types (Text, Reaction, Buttons, Lists, Location). This is identical to the HA Diagnostic Button but can be triggered directly from your phone.
ha-app-status: Returns the current health of the addon, versions, and connectivity status.
ha-app-logs: Sends you a text message with the last few connection events (e.g., reconnection attempts).
ha-app-ping: A simple connectivity check.

🧐 Common Issues

1. Bot is “Disconnected” (Binary Sensor is Off)

Check the QR Code: Ensure you have successfully “Linked” your device in the Addon UI.
Firewall/Network: Ensure Home Assistant can reach the Addon on the configured port (default 8066).
API Key: Verify the api_key in HA matches the one generated by the Addon.

2. Messages are not arriving

Whitelist: If you enabled the whitelist, ensure the recipient’s number (in international format, e.g. 491234567890) is included.
Self-Messaging: You can message yourself! If this fails, ensure the Addon has correctly identified your own JID (visible in the “Self-Test” button stats).

3. “Invalid Media Type” errors

This usually happens when sending Buttons or Lists to very old Android versions or if the WhatsApp session is in a degraded state. Try restarting the Addon.

4. “rate-overlimit” or Connection Drops

Frequent Restarts: If you restart Home Assistant many times in a row, WhatsApp might temporarily block group fetching. The app will automatically cool down for 15 minutes. Use the Chats sensor to check the status.
Massive Automations: If you send hundreds of messages at once, the connection might drop. Ensure the Message Send Interval is set to at least 1000ms.
Queuing: If messages arrive with a delay, this is normal behavior of the built-in queue to keep your account safe.

5. Poll Votes are empty or “Resolution failed”

This is usually a side effect of WhatsApp’s End-to-End Encryption (E2EE).

Root Cause: The bot must have the original “Poll Creation” message in its local memory to decrypt votes. If the bot was offline when the poll was sent, or if it was recently restarted and the poll is old, it can’t read the vote.
Fix: Ensure the bot stays online. If the problem persists for newly created polls, try a “Reset Session” in the Addon UI to clear potentially corrupted state.
Limitation: Votes on polls sent while the bot was disconnected can never be resolved.

📞 Support & Logs

If the Diagnostic Test shows errors and the steps above don’t help:

Set the integration log level to debug in your configuration.yaml:

logger:
  default: info
  logs:
    custom_components.whatsapp: debug

Check the logs under Settings → System → Logs.
Open an issue on GitHub with the results of your Diagnostic Test.