Sistava

Botpress WhatsApp Integration: A Step by Step Setup

How-to — — by Mahmoud Zalt

What you need before you start, OAuth versus manual configuration, the five credentials Meta asks for, and why your bot cannot send messages yet.

Connecting a bot to WhatsApp is the point where a straightforward build meets someone else's approval process. The Botpress side is short. Meta's side is where the time goes, and no amount of care in Studio speeds that part up.

So plan it as two jobs. Job one is getting the accounts and permissions Meta requires. Job two is a short configuration inside Botpress. Doing them in that order saves you from finishing the integration and then discovering the bot is not allowed to speak yet.

What do you need before connecting Botpress to WhatsApp?

Botpress lists the prerequisites directly. Have these in place before you open the integration, because each one is a separate wait if it is missing.

You will also need a phone number that is dedicated to this. A number already registered to a personal WhatsApp account is the most common thing to trip over on setup day.

Should you use OAuth or manual configuration?

Use OAuth unless you have a specific reason not to. It is the shorter path: install the integration, open its Configuration menu, select Authorize WhatsApp, and follow the connection prompts. One write-up on this setup reports the OAuth route completing in under fifteen minutes when the business is already verified.

Manual configuration is for when you need control. That mostly means rotating credentials yourself, connecting more than one phone number, or managing webhook settings directly. It is the same destination by a longer road.

How do you connect Botpress to WhatsApp with OAuth?

  1. Open Explore Hub — In Botpress Studio, select Explore Hub in the upper-right corner.
  2. Find and install the WhatsApp integration — Search for WhatsApp, then select Install Integration.
  3. Choose Authorize WhatsApp — In the integration's Configuration menu, select Authorize WhatsApp. Meta's authorisation flow opens from there.
  4. Sign in and grant permissions — Log in to your business account in the Meta window and follow the prompts to connect the account, page and number.
  5. Publish and test — Publish the bot, then message the connected number from a different device and confirm the reply arrives.

If the authorisation window closes without confirming, that is usually a business account permissions problem rather than a Botpress one. Check that the Facebook account you signed in with actually administers the business page and the WhatsApp Business Account.

What credentials does manual WhatsApp configuration need?

Five, and Botpress documents where each one lives in your Meta app. Most of them come from the WhatsApp use case section, reached in the Meta app under Use cases and then Connect with customers through WhatsApp.

CredentialWhere it comes from
Verify TokenA custom alphanumeric string you invent. It has to match on both sides.
Access TokenGenerated from the Meta app's API testing area.
Client SecretIn the Meta app under App Settings and then Basic.
Default Bot Phone Number IDFrom the section where you select a From phone number.
WABA IDYour WhatsApp Business Account ID, found in the phone number settings.
  1. Install the integration and choose Manual Configuration — Same starting point as the OAuth route, different branch.
  2. Collect the five credentials from your Meta app — Work through the table above. Copy each value exactly, including hyphens and special characters, since a truncated token fails silently rather than loudly.
  3. Enter them in Botpress and save — Paste the values into the integration's configuration and select Save Configuration.
  4. Take the webhook URL and verify token back to Meta — Botpress gives you a webhook URL and the verify token. Add both in the Configuration section of your Meta app.
  5. Subscribe to the webhook fields — Meta will not send events you have not subscribed to. Botpress lists the exact fields on its WhatsApp integration page, covering messages and the message template status events among others. Subscribe to every field listed there rather than only the obvious one.
  6. Publish the bot and send a test message — Message the number from a device that is not connected to the integration and confirm the round trip works.

Why can my Botpress bot receive WhatsApp messages but not send them?

Business verification. Botpress states it plainly: until Meta has verified your business, your bot will not be able to send messages to WhatsApp users. This is a Meta requirement and nothing in Botpress can shortcut it.

Reports from people who have been through it describe a wait of several business days and a document check, typically something like a tax ID or business licence. Start verification early, before you build the conversation, so the two waits overlap instead of stacking.

Worth being clear about the boundary here. What your bot is allowed to send, and when it may message someone who has not messaged you first, is set by Meta's messaging policy rather than by Botpress. Read Meta's current rules before you design any outbound flow.

If the credential collection felt like a lot for one channel, that is a fair reading, and it is not really Botpress's doing. Meta owns most of that friction. It is still the kind of set-up work we removed at Sistava, where the channels are connected on the platform side and you hire an AI Employee and tell it in plain English what to handle.

One last practical note. WhatsApp is a channel people read like a text from a friend, so tone matters more here than on a website widget. Test with a real conversation before you point any volume at it, and read what came back rather than only checking that something did.

FAQ

Can I use my personal WhatsApp number with Botpress?

No. Botpress lists a WhatsApp Business Account among the prerequisites, and independent guides to this integration make the same point that personal accounts will not work. You need a number dedicated to the business account rather than one already registered to personal WhatsApp.

How long does the Botpress WhatsApp setup take?

The Botpress side is short. One write-up reports the OAuth route completing in under fifteen minutes when the business is already verified. If it is not verified, that is the long pole. Reports from people who have been through Meta's verification describe several business days and a document check, so start it before you build the conversation.

What is the difference between OAuth and manual configuration in Botpress?

OAuth is the guided route: install the integration, select Authorize WhatsApp in the Configuration menu, sign in to Meta and grant permissions. Manual configuration means entering five credentials yourself, which Botpress documents for cases where you need finer control, such as rotating credentials, connecting multiple phone numbers, or managing webhook settings directly.

Which credentials does Botpress need for manual WhatsApp setup?

Five: a verify token that you invent, an access token generated from your Meta app's API testing area, the client secret from App Settings and then Basic, the default bot phone number ID from where you select a From phone number, and your WhatsApp Business Account ID. Copy each value exactly, since a truncated token tends to fail without an obvious error.

Why is my Botpress WhatsApp integration not receiving any messages?

Check the webhook first. Meta only delivers events you have explicitly subscribed to, and missed field subscriptions are a well-documented cause of an integration that looks configured but does nothing. Confirm the webhook URL and verify token from Botpress were added in your Meta app's Configuration section, and that every webhook field listed in the Botpress integration guide is subscribed.

Do I need Meta to verify my business before launching?

To send messages, yes. Botpress states that until Meta has verified your business, your bot will not be able to send messages to WhatsApp users. Verification is Meta's process, not something Botpress controls, so build the conversation while it runs rather than waiting for one before starting the other.

Sources