Skip to content

troubleshooting.md

Latest commit

 

History

History
83 lines (55 loc) · 4.02 KB

troubleshooting.md

File metadata and controls

83 lines (55 loc) · 4.02 KB

🛠️ 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

  1. Go to Settings → Devices & Services → WhatsApp.
  2. Click on the 1 device link.
  3. In the Entities list, find the entity called WhatsApp Diagnostic Test (it is disabled by default).
  4. Enable the entity and wait 30 seconds for HA to activate it.
  5. 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.

📞 Support & Logs

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

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

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

  2. Check the logs under Settings → System → Logs.

  3. Open an issue on GitHub with the results of your Diagnostic Test.