WhatsApp Bot is an app that allows your Homey Pro to communicate with a dedicated WhatsApp bot using the official Meta WhatsApp Cloud API. This integration enables you to control your smart home by sending and receiving messages directly within your WhatsApp chat.
TIP: By pairing this app with Gemini AI, you can unlock Natural Language control for your entire home via WhatsApp. Simply route your incoming messages to Gemini AI in your flows to experience a truly intelligent chat interface.
Interactive Messaging with Homey
The app is built around two core Flow cards that turn WhatsApp into a powerful interface for your smart home.
Send WhatsApp Message (Action)
Stay informed about your home in real-time. Whether it’s a security alert or a simple household reminder, Homey can now “text” you directly.
Security: “Presence detected in the garage while you’re away!”
Appliances: “The laundry is ready! ”
Notifications: “Energy consumption is exceeding 3kW, please turn something off.”
Message Received (Trigger)
Control your home by simply sending a text or a vocal message to your bot.
Remote Execution: Text “Lock everything” to arm your security system and turn off all lights.
Status Inquiry: Say “Is the oven on?” to get an instant reply.
Conversational Flows: Use the incoming message text as a variable to trigger complex logic or search for information.
Professional Setup (Meta Cloud API)
Unlike unofficial solutions, this app relies on the official Meta Developer Portal. This ensures your messages are delivered instantly and securely.
Direct Connection: You connect directly to Meta. No middle-man servers, no data sniffing.
Permanent Access: No more QR code scanning every few weeks. Once configured with a Permanent Access Token, it works forever.
Setup Guide Included: I know Meta’s portal can be daunting, so I’ve built a step-by-step Setup Guide directly inside the app settings to walk you through the process.
Download it now on the Homey App Store! I’d love to hear your feedback, see your flows, and help with any questions.
In the left menu, open the Users section and choose System users.
Click “Add”, choose a name (e.g., HomeyBot), select the “Admin” role, and click “Create system user”.
Click “Assign assets”, select your App, enable “Full control”, and save.
Click “Generate token”, select your App, and in the permissions list, you must check:
whatsapp_business_messaging
whatsapp_business_management
Copy the generated Token and keep it safe (it will only be shown once).
4. Configuration on Homey
Open the WhatsApp Bot app settings on Homey and enter:
Access Token: The permanent token generated in step 3.
Phone Number ID: The ID obtained in step 2.
Verify Token: A string of your choice without spaces (e.g., my_secret_token). Note: it is strictly case-sensitive (using only lowercase letters is recommended to avoid mobile auto-capitalization issues). This string will be used both to verify the Homey app within the Meta portal and for the initial bot registration (it is the secret code required by the bot).
Save the settings and take note of the Webhook URL that appears.
5. Webhook Configuration on Meta
Go back to the Meta Developer Portal, in the WhatsApp menu select “Configuration”.
Click “Edit” next to Webhook:
Callback URL: Paste the Webhook URL provided by Homey.
Verify token: Enter the string you chose on Homey in step 4.
Ciao Caesar, You must repeat step six of the guide for each new user.
Essentially, in Meta for developer you must add the number of the person you want to add to the “to” field and then send them the test message. Once that person receives the test message, he must respond with:
/register [your_token]
where [your_token] is the Verify Token chosen in step 4.
From that moment, he will be able to use the bot, and the phone number will appear in the users section of the app settings.
My meta web interface is a bit different than described:
Section is called “API Testing”
Temp token is generated as described
2. Select a ‘From’ phone number is kept as is (random US number)
3. Add a recipient phone number I added my personal number
4. Turn on webhook listening I tested with both On and Off
5. Choose a type of message to send I chose “Plain Text”
6. Send messages with the API sends me the text “Welcome to Jasper’s Market, your local grocery store providing farm-fresh produce and high-quality goods!”
I respond in the chat “/register” “/register handshake” “/register [handshake]” but all three responses don’t register in the app
In the latest version, I’ve added full support for Voice Messaging: now you can send audio messages and the bot will transcribe them using Groq’s Whisper API. You’ll find all the instructions for configuring the Groq API in the app settings.
Italian is a beautiful language and I love it - But unfortunately do not understand it
Could you pls provide an englisch version of app and app page and link to it by leaving the „/it-it“ part out of the url (= non language specific link)?
Hi Simone,
I’m having trouble getting incoming WhatsApp messages to trigger the Homey WhatsApp Bot app.
Meta Cloud API is configured and the webhook is verified successfully. The messages webhook field is subscribed, and Meta successfully sends the webhook test.
However, when I send a real WhatsApp message to the Meta test number, Homey receives nothing and the whatsapp_message_received Flow trigger is not triggered.
I also sent /register CasaHomey2026 from my WhatsApp number, but I receive no response.
did you manage to resolve this ? I had similar issues as you and have found out the repair/fix for it and I can immediately see your problem from your message you posted here
ciao @Mark_Sharples! Looking at the logs, your Homey app is working properly and can successfully send messages out. However, Homey is not receiving any incoming webhook events at all from Meta (there are zero [POST] /webhook entries logged).
When you send /register, Homey should log the incoming message immediately. Since nothing appears in the logs, Meta is not delivering incoming WhatsApp messages to your Homey.
To solve this, please check these two key steps in the Meta for Developers portal:
1. Ensure the messages Webhook Field is Subscribed (Most Common)
Even if your Webhook Callback URL is verified, Meta will not forward incoming messages unless you explicitly subscribe to them:
In your Meta App, go to Use Cases → WhatsApp → Configuration.
Scroll to the Webhook fields section and click Manage.
Find the messages row and ensure you click Subscribe. (If it’s not subscribed, Meta silently ignores all incoming WhatsApp messages).
2. If you are using Meta’s Test Phone Number (Sandbox):
In Sandbox mode, Meta has strict restrictions and will not allow you to start a chat with the test bot out of the blue:
Verify your number: Go to WhatsApp → API Setup. In Step 1 (Select phone numbers) under the “To” dropdown, make sure your personal phone number is added and verified via SMS.
Initiate the chat from Meta (Hello World): You cannot text the test number first. You must generate a temporary token in API Setup and click “Send message” (Step 2) from the portal to send the “Hello World” welcome message to your phone.
Reply to that chat: Once you receive the “Hello World” message on your WhatsApp app, reply directly in that exact chat thread with:
/register [YourVerifyToken]
(Replace [YourVerifyToken] with the exact Verify Token you saved in your Homey app settings. Do not add extra words like “Handshake”).
Once either the webhook subscription is fixed or the chat session is properly initiated from Meta, your /register command will reach Homey immediately and complete your registration
Thank you for the response , it is very much appreciated.
I did find out the issue and by looking at some of the questions in this thread others , have and are having the same problem that I did .
The error is in your wording in the instructions that you supply regarding the verify token.
You mention , no spaces and numbers when creating the verify token , which is 100% accurate however on modern devices such as phones or tablets , the first letter is normally capitalised automatically . This was my issue . The first letter of my token was a capital letter , and WhatsApp wouldn’t recognise it .
Please could you add to your instructions for other new users that Capital Letters should also not be included when creating the verify token .
Thanks again for all your hard work , the app,works beautifully now .
Actually, the token should be case-sensitive: if you save it in the Homey app using uppercase letters, then you must use those same uppercase letters when registering via /register. Was that not the case for you?
No it worked perfect fine after after changing the first letter from a capital , I tried many times , even changed the verify token completely, I double checked for white spaces etc , but never got a response back from the WhatsApp message until I changed the capital .
I tried also with my wife’s phone same issue ,
Both phones got immediate responses without the capital .
Interactive Messaging with Homey
Send WhatsApp Message (Action)
”
Message Received (Trigger)
Professional Setup (Meta Cloud API)
- But unfortunately do not understand it 
