How to connect OpenClaw to WhatsApp

OpenClaw WhatsApp setup runs through Meta’s official WhatsApp Business API and requires a verified phone number and a Meta developer account. This article covers every step from account creation to first message, with paste-in prompts for verification and testing.

What you need before starting

The openclaw whatsapp setup requires three things from Meta before you touch OpenClaw’s config. None of them are optional. If you try to configure the OpenClaw side without having all three, the plugin will fail to authenticate. This is worth stating clearly because the Meta setup steps take 20 to 40 minutes and involve navigating several different Meta dashboards (developers.facebook.com, business.facebook.com, and the Meta app dashboard). Having a clear picture of what each step produces, and what downstream step needs it, prevents backtracking.

• A Meta developer account: This is a free account at developers.facebook.com. If you already have a Facebook account, you use the same login. The developer account is what gives you access to the WhatsApp Business API.
• A Meta app with WhatsApp product added: Inside your developer account, you create an app and add “WhatsApp” as a product. This app is the bridge between Meta’s infrastructure and your OpenClaw instance. It produces the API token and phone number ID that OpenClaw uses to send and receive messages.
• A phone number not registered on WhatsApp: Meta requires a phone number to register your WhatsApp Business sender identity. This number cannot already be registered to a personal WhatsApp account. It can be a landline, a VoIP number, or a mobile number that has never been used for WhatsApp. If you want to use a number currently on personal WhatsApp, you must deregister it from personal WhatsApp first, which deletes your chat history on that number.

Step 1: Create a Meta developer app

A Meta app is a container in Meta’s developer system that holds your API credentials and permissions. You create one per integration. This app will hold your WhatsApp Business API access token and your phone number configuration.

I am starting the OpenClaw WhatsApp setup process. I need to create a Meta developer app. Walk me through what a Meta developer app is, why I need one for WhatsApp integration, and confirm the current URL where I create it. Tell me which app type to choose at setup (Business is the correct type for WhatsApp Business API access as of March 2026) and what the app will be used for once created.

When creating the app, choose Business as the app type. The “Consumer” and “None” types do not support WhatsApp Business API. During creation, you will be asked to associate a Meta Business Account. If you do not have one, Meta will prompt you to create one during the app creation flow. This is a free, two-minute process.

Once the app is created:

1. From the app dashboard, click Add Product
2. Find WhatsApp and click Set up
3. Meta will prompt you to connect a WhatsApp Business Account. Follow the flow to create or connect one.

Step 2: Add and verify your phone number

Adding a phone number to your WhatsApp Business API account registers it as your sender identity. Anyone who messages your agent will see this number. When they save it, it appears in their contacts like any other WhatsApp number.

I need to add a phone number to my WhatsApp Business API account for my OpenClaw WhatsApp integration. Tell me: what are the exact requirements for the phone number (not already registered on personal WhatsApp, must be reachable for verification), what the verification process looks like (SMS code or voice call), and what information I will need once the number is verified (phone number ID and the business account ID, both of which I will need for the OpenClaw config).

Verification is a code delivered by SMS or voice call to the number you are adding. The number must be able to receive this code at the time of verification. If you are using a VoIP number that does not support SMS, choose the voice call option. Meta will call the number and read out a 6-digit code. If neither SMS nor voice call works for your number, Meta also supports verifying a number that is already in use on the WhatsApp Business App (the standalone mobile app), which uses a different flow that does not require a code. Once verified, Meta gives you two identifiers you will need for the OpenClaw config:

• Phone Number ID: A numeric identifier for the specific phone number, not the phone number itself. It looks like a 15 to 18 digit number. This is the value you put in your OpenClaw config to tell the plugin which number to send from.
• WhatsApp Business Account ID (WABA ID): The identifier for your WhatsApp Business Account. Some versions of the OpenClaw WhatsApp plugin require this in addition to the Phone Number ID.

Write both of these down. They are available in your Meta app dashboard under WhatsApp > API Setup at any time, so you can retrieve them later if needed. A common confusion: the Phone Number ID is not the phone number itself. Your phone number might be +1-555-0100, but the Phone Number ID is a long number like 123456789012345. OpenClaw uses the Phone Number ID in API calls, not the formatted phone number. Using the formatted phone number instead of the ID in your config is a common cause of “invalid parameter” errors on first setup.

Step 3: Get your access token

An access token is a long string of characters that acts as a password for your Meta app. When OpenClaw sends a message through WhatsApp, it presents this token to Meta’s API to prove it has permission to use your app. Without a valid token, every API call will be rejected.

Meta provides two types of tokens. The first is a temporary test token that expires after 24 hours. The second is a permanent system user token that does not expire. For a production OpenClaw integration, you need the permanent system user token. Using the temporary token means your integration will stop working after 24 hours and you will need to update your config with a new token every day.

I am setting up OpenClaw WhatsApp integration and I need a permanent access token from Meta, not the temporary 24-hour test token. Walk me through how to create a system user in Meta Business Manager, assign it to my app with send message permissions, and generate a permanent token. Tell me where the token appears after generation and confirm I need to copy it immediately because Meta does not show it again after closing the dialog.

The steps for a permanent token (as of March 2026, verified against Meta’s current Business Manager interface) are:

1. In Meta Business Manager (business.facebook.com), go to Settings > System Users
2. Create a new system user with Admin role
3. Click Add Assets, choose Apps, find your WhatsApp app, and give it full control
4. Click Generate Token, select your app, check the whatsapp_business_messaging and whatsapp_business_management permissions
5. Copy the token immediately. Meta shows it once.
6. Optionally, set an expiration date. For a permanent token, leave expiration blank. A token with no expiration date does not expire unless you manually revoke it or the system user is deleted.

Step 4: Configure the webhook

A webhook is a URL that Meta calls whenever someone sends a message to your WhatsApp number. OpenClaw runs a webhook endpoint that receives these incoming messages and passes them to your agent. Without the webhook configured, Meta does not know where to send incoming messages and your agent cannot receive them.

OpenClaw’s gateway needs to be reachable from the internet for Meta to reach the webhook. This requires either a public IP with port 443 open, or a reverse proxy that forwards HTTPS traffic to your OpenClaw instance. Meta requires HTTPS (not HTTP) for all webhooks.

I need to configure the webhook for my OpenClaw WhatsApp integration. Tell me: what is the webhook URL format for the OpenClaw WhatsApp plugin (the path that Meta should call when a message arrives), what verify token I need to set and where it goes in both the Meta app dashboard and my OpenClaw config, and whether my current OpenClaw setup is reachable from the internet at a valid HTTPS URL. If HTTPS is not set up, tell me what I need to add.

The webhook configuration in Meta’s app dashboard requires two values:

• Callback URL: The full HTTPS URL where Meta sends incoming messages. For OpenClaw, this is typically https://yourdomain.com/webhooks/whatsapp or a similar path. Your agent can confirm the exact path for your plugin version.
• Verify token: A string you choose. Meta calls your webhook with this token to confirm the URL is valid before activating it. You set the same value in both Meta’s dashboard and your OpenClaw config. It can be any string you like; treat it as a shared secret between Meta and your OpenClaw instance.

Step 5: Configure OpenClaw with your Meta credentials

With your Phone Number ID, access token, and webhook verify token in hand, you are ready to configure the OpenClaw WhatsApp plugin. The plugin reads these values from your openclaw.json config file and uses them to connect to Meta’s API.

I am ready to configure the OpenClaw WhatsApp plugin. I have my Meta Phone Number ID, my permanent access token, and my verify token ready. Read my current openclaw.json and show me where the WhatsApp plugin config block goes. Then update the config with the following values: Phone Number ID is [YOUR_PHONE_NUMBER_ID], access token I will provide separately, verify token is [YOUR_VERIFY_TOKEN]. Set the plugin to enabled. Do not echo my access token back in your response. I will provide it in a follow-up message and you should update the config field silently.

Update the WhatsApp plugin config in my openclaw.json to set the access token to [YOUR_TOKEN]. Do not show the token in your response. After saving the config, restart the gateway so the plugin loads with the new credentials. Confirm the gateway restarted cleanly and the WhatsApp plugin initialized without errors.

Step 6: Subscribe to webhook message fields

After your webhook URL is verified by Meta, you must explicitly tell Meta which types of events to deliver to that URL. This is the webhook subscription step. Without subscribing to the correct fields, Meta verifies the webhook URL but never actually sends incoming messages to it.

I have configured the webhook URL in Meta’s app dashboard and my OpenClaw plugin is running. I need to make sure I am subscribed to the correct webhook fields so incoming WhatsApp messages are delivered to my agent. Tell me which fields to subscribe to in the Meta app webhook configuration (specifically “messages” under the WhatsApp product), how to verify the subscription is active, and how to test that an incoming message reaches my OpenClaw agent.

The field you must subscribe to is messages under the WhatsApp Business Account section of your app’s webhook config. Without this subscription, your webhook URL receives Meta’s verification calls but not actual messages. This is the most common cause of a setup that appears configured but where the agent never receives anything. One way to confirm the subscription is active: after subscribing, send a test WhatsApp message to your number from a phone that is in your verified test recipient list (during development). Watch the gateway logs in real time. If a POST request appears in the logs within a few seconds of sending the message, the subscription is delivering. If nothing appears, the subscription is not active.

Step 7: Test the complete integration

Testing covers two directions: outbound (your agent sending a message to WhatsApp) and inbound (a WhatsApp message reaching your agent). Both need to work for the integration to be usable.

Test my OpenClaw WhatsApp integration in both directions. First, send an outbound test message via the WhatsApp API to my own phone number and confirm it was delivered successfully. Then check the gateway logs to confirm the webhook endpoint is accessible and that no errors appeared during the test. Tell me what I should see in my WhatsApp app when the test message arrives.

For the inbound test, send a WhatsApp message from your personal phone to the number registered in your Meta app. Your OpenClaw agent should receive it and respond. Check the gateway logs after sending to confirm the message arrived and was processed. A successful first inbound test confirms the entire chain: Meta received your message, called your webhook URL, OpenClaw received it, processed it, and sent a reply through the Meta API. Save a record of this first successful test in your workspace so you have a baseline. If the integration stops working in the future, you can compare the current config against the config that was working to identify what changed. Ask your agent to write a brief integration status note with the current config values (excluding the access token) and the date of the first successful test.

Understanding WhatsApp Business API pricing

As of March 2026, Meta uses a conversation-based pricing model for the WhatsApp Business API. A conversation is a 24-hour window that opens when a message is exchanged between your business number and a contact. Within that 24-hour window, all messages in both directions are part of one conversation and counted as one billable unit.

The pricing tiers (as of March 2026, subject to change; check Meta’s official pricing page for current rates by country):

• First 1,000 user-initiated conversations per month: Free. A user-initiated conversation is one where the person messages you first. This resets on the first of each month. For most personal OpenClaw setups, you will never exceed this. Note: business-initiated conversations (where your agent messages first using a template) are not included in the free tier and are billed from the first message.
• Beyond 1,000: Rates vary by country and conversation type (user-initiated vs business-initiated). User-initiated conversations (where someone messages you first) are cheaper than business-initiated conversations (where your agent messages first).

Check my WhatsApp Business API usage for the current month. Tell me how many conversations have been logged against my account, how close I am to the free tier limit, and what my current message volume suggests about likely monthly costs if usage continues at this rate.

FAQ

Not while keeping it active on personal WhatsApp. A phone number can only be registered to one WhatsApp account type at a time. If you register it with the WhatsApp Business API, it is deregistered from personal WhatsApp and your personal chat history on that number is deleted from Meta’s servers. You can still access chat history backed up to Google Drive or iCloud, but the active account moves. Most operators use a separate number for their OpenClaw integration. A VoIP number from a service like Twilio or Google Voice works for registration if it can receive SMS or voice calls for verification.

Four things to check in order. First, confirm your OpenClaw gateway is running and the WhatsApp plugin initialized without errors in the startup logs. Second, confirm the URL you entered in Meta’s dashboard is the exact URL your server responds to, including the correct path. Test it by pasting the URL into a browser. If it returns a connection error or 404, Meta cannot reach it either. Third, confirm port 443 is open on your server’s firewall. A running gateway with a closed port produces the same “unreachable” result as one that is not running. Fourth, confirm you are using HTTPS and that your certificate is valid. Meta rejects HTTP webhook URLs and webhook URLs with expired or self-signed certificates. Ask your agent to run a TLS check on your webhook URL and confirm the certificate is valid and not expired.

This means the webhook is working (Meta is delivering messages to your agent) but the response is failing somewhere in the outbound chain. Check the gateway logs for errors after the message arrives. The most common causes are: an expired or revoked access token (check your Meta app dashboard for any token alerts), a missing or incorrect phone number ID in the config (the outbound API call requires the correct ID to route the message), or a rate limit hit if you have been sending many messages in a short window. Ask your agent to attempt a manual outbound message using the WhatsApp API directly and report the API response code.

The most common cause is a 24-hour temporary access token expiring. If you used the test token from Meta’s app dashboard instead of a permanent system user token, it expired after 24 hours. Replace it with a permanent token (follow Step 3 above). The second cause is Meta revoking app permissions after a period of low activity or policy review. Check your Meta app dashboard for any warning or policy notices. The third cause is a gateway.bind change that made your webhook URL unreachable from Meta’s servers. If someone changed gateway.bind to 127.0.0.1 for security reasons after setup, the webhook URL is no longer reachable from outside the server.

A WhatsApp Business Account (WABA) is required for the WhatsApp Business API. A WABA is a free account type distinct from both personal WhatsApp and the WhatsApp Business App (the standalone mobile app for small businesses). The WABA is created during the Meta developer app setup flow and is associated with your Meta Business Manager account. You do not need the WhatsApp Business App installed on any phone. The API connects directly to Meta’s servers through OpenClaw, with no phone required after the initial number verification.

No. Each phone number can only have one active webhook endpoint in Meta’s system. If you register the same number with two OpenClaw instances, the second registration overwrites the first and only the second instance receives messages. To run multiple agents on WhatsApp, each agent needs its own phone number and its own WhatsApp Business API configuration. If you want to route messages between agents based on content or user, do that within a single OpenClaw instance using the agent routing capabilities, not by splitting across numbers.

Three checks confirm a live integration. First, send a WhatsApp message to your registered number from a personal phone and confirm your agent replies. If it does, the full chain is working. Second, ask your agent to show you the WhatsApp plugin status and the last successful inbound message timestamp. Third, check the Meta app dashboard’s webhook delivery log for your app. This shows the last few webhook deliveries, their HTTP status codes (200 means your OpenClaw accepted them successfully), and any delivery failures. A pattern of 200 responses with recent timestamps confirms Meta is delivering and your OpenClaw is accepting.

Troubleshooting common openclaw whatsapp setup failures

The openclaw whatsapp setup fails at one of four points for most operators: webhook verification, token authentication, outbound message delivery, or inbound message routing. The failure at each point produces a specific symptom. Matching the symptom to the cause is faster than working through all steps again from the beginning.

Webhook not verifying

If Meta shows “Webhook verification failed” when you try to save the callback URL, the issue is one of three things: the URL is not reachable from Meta’s servers, the webhook endpoint is not returning the correct challenge response, or the verify token in your OpenClaw config does not match what you entered in Meta’s dashboard.

My WhatsApp webhook is failing Meta’s verification check. Check the following: is my OpenClaw gateway running and is the WhatsApp plugin initialized in the startup logs? What is the exact webhook URL the plugin is listening on? Is that URL reachable from the internet (check gateway.bind and confirm port 443 is open)? What verify token is currently set in my WhatsApp plugin config? Show me the relevant config section without the access token.

The most reliable debugging step for webhook verification failures is to simulate what Meta does: send a GET request to your webhook URL with a hub.verify_token parameter matching your configured token and a hub.challenge value. Your webhook should respond with that challenge value and a 200 status. If it does not, the plugin is not handling the verification correctly.

Simulate the Meta webhook verification request to my OpenClaw WhatsApp webhook URL. Run a curl request to my webhook URL with the parameters hub.mode=subscribe, hub.verify_token set to my configured verify token, and hub.challenge set to a test string like “testchallenge123”. Show me the response. It should return “testchallenge123” with a 200 status. If it returns anything else, tell me what the response was and what that indicates about the failure.

Messages sent to the number but agent never receives them

If messages sent to your WhatsApp number never arrive at your OpenClaw agent, but the webhook verified correctly, the issue is almost always the webhook subscription. Meta requires you to explicitly subscribe to message events after verifying the webhook URL. Without the subscription, Meta confirms the URL works but does not route messages to it.

I set up my WhatsApp webhook and it passed verification, but incoming messages are not reaching my OpenClaw agent. Check the Meta webhook subscription status for my app. Specifically, confirm whether the “messages” field is subscribed under the WhatsApp product in my app’s webhook configuration. If it is not subscribed, tell me exactly where in the Meta app dashboard to enable this subscription.

Agent responds in OpenClaw but WhatsApp messages are not sent

If your agent processes incoming messages and generates a response but the response never appears in WhatsApp, the outbound API call is failing. This is a different failure point from webhook delivery and has a different set of causes.

My OpenClaw agent is receiving WhatsApp messages but not sending replies back. Check the gateway logs for any errors after a WhatsApp message arrives. Look specifically for: HTTP error codes from the Meta API (401 means the access token is invalid, 403 means permission error, 429 means rate limit, 400 means malformed request), errors mentioning the phone number ID, or any mention of the WhatsApp send endpoint. Show me the relevant log lines.

A 401 error confirms the access token is expired or revoked. Return to Step 3 and generate a new permanent system user token. A 403 error means the token is valid but lacks the required permissions. Check that whatsapp_business_messaging is included in the token’s permissions in Meta Business Manager. A 400 error usually means the phone number ID in your config does not match the number registered in your Meta app. A 429 error means you have hit Meta’s rate limit. The WhatsApp Business API rate limits vary by account verification tier. Unverified accounts have lower per-second limits than verified businesses. If you are hitting 429 errors in normal testing volume, it usually indicates the account is not yet fully verified in Meta Business Manager.

WhatsApp vs Telegram vs Discord: choosing the right channel

Before committing to WhatsApp as your primary OpenClaw channel, it is worth understanding how it compares to Telegram and Discord in terms of setup complexity and operational characteristics.

WhatsApp has the largest user base of the three and reaches people who do not use Telegram or Discord. If your use case is personal productivity (your OpenClaw agent on your primary phone), WhatsApp is the most natural choice for most people because it is the app already open. If your use case is a bot others interact with, WhatsApp’s business-focused constraints (template requirements for outbound messages, Meta business verification for some features) add friction that Telegram does not have.

Telegram is technically simpler to set up with OpenClaw. There is no webhook verification flow, no business account requirement, no phone number tied to a business identity, and no per-conversation pricing. If your primary goal is getting your OpenClaw agent on a messaging platform quickly and cheaply, Telegram is the faster path. The OpenClaw Telegram integration article covers that setup in detail.

Discord is the right choice if you want your agent integrated into a community space, a server with multiple channels and roles, or a workspace where a group of people interact with the same agent. WhatsApp and Telegram are one-to-one or one-to-small-group. Discord supports large-scale structured environments that neither WhatsApp nor Telegram handles as well.

I am deciding between WhatsApp, Telegram, and Discord for my primary OpenClaw channel. Based on my current setup and how I have described my use case, which channel would you recommend and why? Also tell me: can I run multiple channels simultaneously so my agent is reachable on more than one, and what is the overhead of maintaining more than one active channel integration?

Keep Reading: