💡 Pro-Tips, Tricks & Troubleshooting

Manage your integration like a pro and resolve common issues.

Tip: 🛡️ Whitelist Guide: Secure your integration by restricting interaction to specific numbers and groups.

🆔 How to find Group Chat IDs?

Home Assistant doesn’t list WhatsApp Group IDs in the UI. To find them:

Open Developer Tools -> Events.
In “Listen to events”, type: whatsapp_message_received.
Click Start Listening.
Send a message into the WhatsApp group you want to identify.
Check the event output. The target (or raw.key.remoteJid) will look like 123456789@g.us.
Use this ID (the suffix @g.us is optional in service calls) as your target.

🧪 Testing your Services

Use the Developer Tools -> Services tab to verify your configuration before building automations.

Select whatsapp.send_message (or notify.whatsapp).
Switch to YAML Mode.
Paste one of the examples from the Service Docs (Ensure you use the correct recipient number).
Click Call Service.

🛠️ Troubleshooting

Message not sending?

Check Logs: Go to the WhatsApp Home Assistant App logs. Search for “Connection closed” or “Unauthorized”.
External URL: If sending images, ensure the URL is correct and the App can download the file.
Pairing: Does the App Web UI show Connected? If not, re-scan the QR code.

“Reset Session” - When to use it?

If you have persistent connection issues or want to pair with a different phone number:

Go to the App Configuration.
Set reset_session to true.
Save and Restart the App.
The App will delete all old session data and present a fresh QR code.
The reset_session flag will automatically be set back to false once used.

Unauthorized API Access

If you see 401 errors in the App logs:

Check the api_token.txt in your HA /data folder (internal to App).
Integration and App must use the same token. Usually, the integration handles this automatically via the Config Flow, but a re-installation of the integration might be needed if things are out of sync.

🔒 Privacy & Security

Local Processing: All message processing happens on your own hardware.
No Cloud Storage: This integration does not store your messages on any cloud server except for the official WhatsApp servers.
Tokens: The API token is stored locally in your Home Assistant configuration. Never share your /data folder or the token with anyone.

❓ FAQ

Q: Can I use multiple WhatsApp accounts? A: Yes! You can add the WhatsApp integration multiple times. Each instance manages its own session on the App. Use the account parameter in service calls to specify which bot should send the message.

Q: Do buttons work on all devices? A: Native buttons are part of the latest WhatsApp MD (Multi-Device) protocol. While most modern mobile apps support them, some older versions or the WhatsApp Desktop app might show them as text links.