Connecting WhatsApp via Meta

Lucy talks to WhatsApp directly through Meta's WhatsApp Cloud API: no Twilio, no third-party broker. The setup is one time but has several moving parts. Follow these eight steps in order.

Before you start

A Meta Business Account.
A phone number to register with WhatsApp Business (or use the free test number Meta provides).
For production: Lucy must be reachable on a public HTTPS URL. For local dev, cloudflared or ngrok works.

Step 1: Create a Meta App with the WhatsApp product

Open Meta for Developers, My Apps and click Create App.

Pick use case: Other, then Next.
App type: Business, then Next.
Give it a name, attach your Business Portfolio, then Create app.
On the new app's dashboard, find WhatsApp in the products list and click Set up.

The WhatsApp product is what enables the API Setup page where the next three values live.

Step 2: Get Phone Number ID and WABA ID

Go to WhatsApp → API Setup in your app's left sidebar. You'll see two options:

Use the test number: free, instant. The number is shared with all Meta dev apps, fine for testing.
Register your own number: required for production. Use a number not currently active on regular WhatsApp.

Once a number is showing, copy these two values straight from the page:

Phone Number ID: directly below the number itself.
WhatsApp Business Account ID (WABA ID): under the same section, often labeled "WhatsApp Business Account".

Each number has its OWN Phone Number ID and WABA ID. If you switch numbers later, update Lucy with the new pair.

Step 3: Generate a permanent Access Token

The token shown on the API Setup page expires in 24 hours. For production you need a permanent System User token.

Open Business Settings → System Users.
Click Add, name it, role Admin, then Create.
Click Assign Assets. Add your App (toggle Develop app) and your WhatsApp Account (toggle Full control). Save each.
Click Generate token, select your app, Expiration: Never, check whatsapp_business_messaging and whatsapp_business_management, then Generate.
Copy the token immediately. You will only see it once.

Treat this token like a password. Anyone with it can send messages from your business number.

Step 4: Get the App Secret

The App Secret lets Lucy verify that incoming webhooks really come from Meta (via HMAC signature).

In your Meta App dashboard, go to App settings → Basic.
Find the App Secret field near the top.
Click Show, re-enter your Facebook password.
Copy the 32-character hex string.

Step 5: Paste credentials into Lucy

In Lucy: open the chatbot, go to the Launch tab, and scroll to the WhatsApp card. Fill in the four fields you collected:

Field	Where it comes from
Access Token	From step 3
Phone Number ID	From step 2
WhatsApp Business Account ID	From step 2
App Secret	From step 4

Click Verify & Connect. Lucy will call Meta to confirm the credentials, then show you a Callback URL and Verify Token for the next step.

Use the copy buttons next to the URL and token, don't retype them. Characters like l/I, 0/O, 5/S are easy to confuse.

Step 6: Configure the webhook in Meta

In your Meta App: WhatsApp → Configuration → Webhooks. Click Edit next to Callback URL.

Paste the Callback URL from Lucy. If you're running locally, replace http://localhost:5000 with your tunnel domain (e.g. https://….trycloudflare.com).
Paste the Verify Token from Lucy.
Click Verify and save. Meta sends a GET request to your URL with the token; Lucy echoes back the challenge to confirm.

If verification fails: tunnel might be down, the URL might have a typo, or the verify token may not match what's in Lucy's DB (re-copy from the dashboard, don't transcribe).

Webhook verified is not the same as webhook receiving data. You must also subscribe to the events you care about.

On the same Webhooks page, scroll to the Webhook fields list.
Find the messages row and toggle Subscribe ON (it turns blue).
Scroll up to Register your WhatsApp phone number. Next to your number, toggle Subscribe webhooks ON.

Without both toggles ON, Meta verifies your URL but never delivers messages to it.

Step 8: Publish your app

While your app is in Development mode, Meta does not deliver real WhatsApp messages to your webhook, only test payloads from the dashboard.

To accept real inbound messages, go to your app dashboard and click Publish your app (yellow banner at the top of the Webhooks page). For basic WhatsApp messaging with a registered number, this is a single click that needs:

A Privacy Policy URL (any URL works for development).
An optional app icon.

You don't need App Review for basic messaging. App Review is only required for advanced permissions or public-facing apps with non-whitelisted users.

Publishing flips Development to Live. It does NOT push your app to any store or make it publicly discoverable.

You're done

Send a WhatsApp message to your registered number from a phone. Lucy logs the inbound payload, the chatbot engine produces a reply, and Meta delivers it back via the Graph API.

Troubleshooting

The four issues that account for almost every failed setup.

Issue	Likely cause	Fix
Verify and save fails in Meta	Tunnel is down, URL has a typo, or verify token doesn't match the one stored in Lucy.	Hit the tunnel URL in a browser, it should respond. Re-copy URL and verify token from Lucy using the copy buttons. Try again.
Verification works but no logs when sending messages	Either the messages field / phone-number-webhooks toggle is OFF, or the app is in Development mode.	Confirm both toggles are ON. Then click Publish your app.
Inbound logs appear but no reply on WhatsApp	Outbound Graph API call is failing, usually an expired or scope-less access token.	Check backend logs for "Meta API returned 4XX". Regenerate a permanent System User token (step 3).
Errors mention "cannot send to unregistered number"	Recipient is not in the test list AND the app is unpublished.	Add the recipient phone in WhatsApp → API Setup → Manage phone number list, OR publish the app.

Need to switch a chatbot to a different WhatsApp number? Repeat steps 5 to 7 with the new Phone Number ID and WABA ID.

PreviousWebsites NextTelegram