# Botpress WhatsApp Chatbot: Setup, Verification and Templates

> How to connect a Botpress bot to WhatsApp on any plan, Free included: the Studio steps, Meta verification, Playground tests, templates and button limits.

_Source: https://professionalstoolkit.com/articles/botpress-whatsapp-chatbot — The Professional's Toolkit · updated November 2026_

---

A Botpress WhatsApp chatbot is a bot you build in Botpress Studio and connect through the WhatsApp integration, and the channel is included on every plan, Free among them.[1] The connection itself takes five steps in Studio: open Communication Channels, install the WhatsApp integration, authorize it with a Facebook account, save and publish. The wait sits elsewhere. **Until Meta verifies your business, the bot cannot send a single message**, and Botpress cannot speed that review up. Plan around that gap. Use the WhatsApp Playground to test while you wait, prepare approved templates if the bot must ever write first, and keep button labels short, because WhatsApp sets the rendering rules.


**1-3** — Choices that WhatsApp shows as reply buttons; 4 to 10 become one dropdown



- **Every plan** — WhatsApp channel included, Free plan too
- **19 characters** — Longest WhatsApp button title before shortening
- **May 2026** — Native WhatsApp carousels and cards added


## What you need ready before you click Install

Three things gate the connection. The first is a published bot: channel integrations such as WhatsApp start working only once they are configured and the bot is published, so the build comes first. If you have not built one yet, our [Botpress chatbot builder guide](/articles/botpress-chatbot-builder) walks through Studio from template to publish. The second is a Facebook account. While authorizing, you create or select a Facebook business page and a WhatsApp Business account, and that account sits inside a Meta Business Portfolio.

The third is a phone number. The number you register must not already be linked to a WhatsApp account; otherwise WhatsApp can assign you a new one. Check this first. A line already active in the WhatsApp app on a staff phone is the usual snag, so decide early which number customers will see. On the Botpress side, the channel adds nothing to your plan. Each WhatsApp chat is billed like any other Botpress conversation, meaning an exchange with at least two messages from the customer in the billing month.

The Free plan covers 100 conversations with no packs, top-ups or overages, which is enough to pilot a WhatsApp bot but not to run a busy line. Plus costs $150 a month billed annually or $189 a month billed monthly and includes 250 conversations a month. At 95% of that quota, a pack is added automatically: $65 per pack of 100 extra conversations, billed each month the pack stays on.

This auto-recharge cannot be turned off. A pack keeps billing until you remove it in billing settings, and unused pack conversations expire at month end. By our arithmetic, 500 conversations in a month on that tier billed monthly come to $384, which is the $189 base plus three packs, and by the FAQ's 95% rule the real bill can be one pack higher.


> 💡 **Test in the WhatsApp Playground:** While Meta reviews your business, the WhatsApp Playground lets you see how the bot's buttons, dropdowns and cards render on a real phone.


## Connecting WhatsApp in Botpress Studio

The guided path runs inside Studio and needs no Meta developer work. Botpress documents it as a short sequence, and the only part that takes thought is the Meta screens in the middle, where you choose the business page, the portfolio and the number. Everything before and after is a click, and the whole sequence starts from the bot you already published:

1. Open the bot's Home tab and go to Communication Channels.
2. Select WhatsApp, then click Install Integration.
3. Click Authorize WhatsApp, connect your Meta Business Portfolio and create the WhatsApp Business profile.
4. Click Save Configuration.
5. Publish the bot.

Publishing matters twice here. The bot must already be live before you connect, and you publish again after saving so the new configuration reaches customers. Every publish also creates a Version automatically, which gives you a point to return to. Be careful with that safety net, though. Reverting overwrites the current bot, and Versions that get lost cannot be restored. Publish once the WhatsApp setup is saved, not halfway through it.

### When to bring your own Meta app

Advanced teams can skip the guided authorization and use Manual Configuration with their own Meta developer app. That route asks for a verify token, an access token, a client secret, the phone number ID and the WhatsApp Business Account ID, plus a webhook subscribed to the message and template fields. It suits a team that already runs a Meta app and wants the number to stay under it. For everyone else, the guided button is shorter and leaves less to misconfigure. One bot can also serve several numbers: event tags expose the bot phone number ID next to the customer's number with country code.

## The verification gap, and how to test through it

After setup, Meta reviews the business. Until it verifies you, the bot cannot send messages to WhatsApp users, and Botpress cannot shorten that review.[2] Nothing in your plan changes this. So do not announce the number to customers on setup day. Treat the review as a scheduling fact instead: finish the content in Studio, connect the channel early, and spend the waiting time on testing rather than on a launch post that the bot cannot yet answer.

The WhatsApp Playground exists for exactly that window. It lets you test the bot on WhatsApp before the real setup or while verification is pending, so you can see how buttons, dropdowns and cards land on an actual phone. Testing has a billing side, though. Botpress's pricing FAQ counts emulator conversations toward your quota the same as live ones, and the AI operations in those tests draw on your AI usage. On Free, a long round of test chats eats into a 100-conversation pilot. A Vonage sandbox offers one more way to test WhatsApp, through the Vonage integration.


> ⚠ **Silent bot? Check Meta billing:** If a Botpress WhatsApp bot receives messages but never replies, Botpress points to the payment method on the WhatsApp Business account in Meta's billing hub.


One failure looks like a bot bug but is not. If the bot receives WhatsApp messages and never replies, Botpress points to the payment method on the WhatsApp Business account in Meta's billing hub. That is Meta's billing, separate from your Botpress plan, and a missing payment method there can silence a bot that behaves perfectly in Studio. Look there before you open the logs. The Conversations tab helps with everything else: it lists conversations across channels, filters to WhatsApp only, and shows per-message JSON when you need to see exactly what the bot sent.

## How Studio content looks on a customer's phone

WhatsApp is stricter than a website widget about what one message can hold, so the integration translates Botpress elements into formats WhatsApp accepts. You build once in Studio and never design a separate WhatsApp version; the trade-off is that a few elements change shape or get cut on the way. The mapping is predictable once you know the numbers:

| What you build in Studio | What the customer sees on WhatsApp |
|---|---|
| 1 to 3 choices | Reply buttons |
| 4 to 10 choices | One dropdown |
| 11 or more choices | Several dropdowns of up to 10 each |
| Button title | Up to 19 characters; longer titles are shortened |
| Dropdown choice title | Up to 23 characters; shortened automatically |
| Card | One link and 3 reply buttons; extras split into more Cards |
| Carousel | Native WhatsApp carousel (since May 2026) |
| Image sent as a sticker | Only WebP, exactly 512 x 512, under 512 KB |

Write button labels for 19 characters from the start, because the shortening is automatic and you do not choose the cut. *Book a visit* survives intact. A long phrase loses its ending. The sticker rule is the harshest: an image that misses the WebP, size or weight condition is not sent at all. The changelog added native Carousels and Cards in May 2026,[3] so product carousels now reach the customer as one carousel. That matters most for stores, which our [Botpress for e-commerce guide](/articles/botpress-for-ecommerce) covers in depth.

Traffic in the other direction works too. Media that customers send is uploaded to the Botpress Files API by default, with an adjustable expiry for downloaded files, and you can switch the download off if you would rather not keep customer images. Since November 2026, bots can also send audio as native WhatsApp voice notes by setting `voice: true`. That is audio inside a chat, not the voice channel, which the pricing page lists only on Enterprise. The same bot can run on your website at the same time: logic and knowledge base stay shared while each channel adapts the interface.


> 💡 **Set the template language:** The Start Conversation Card defaults to en_US; leave the language blank on a non-English template and the send fails with an error.


## Writing to customers first, and handing them to people

WhatsApp lets a business open a conversation only with an approved message template, created in the WhatsApp Manager dashboard.[4] In Botpress, the Start Conversation Card sends it: you give it the customer's phone number and the template name. Watch the language field. It defaults to en_US, and leaving it blank causes an error when the template is not in US English, so a Spanish template needs its language set every time. Templates are the gate for reminders, order updates and any follow-up the customer did not start.

The trigger does not have to live in Botpress. An external system, such as your backend or CRM, can start a WhatsApp conversation by sending a POST to the Webhook integration's URL, which fires the Start Conversation Card; a template is still required. That is how an order system can ask the bot to confirm a delivery slot without anyone opening Studio. Meta's 24-hour messaging window shapes the bot's behavior as well. Since August 2026, Botpress skips CSAT prompts on WhatsApp when a conversation falls outside that window, so satisfaction questions go out only inside it.

When the bot should step aside, new workspaces hand off to Botpress Desk, which lists WhatsApp among its channels and is included on every plan; routing and assignment start on Team. Since October 2026, replies a staff member sends from the WhatsApp Business phone app through Coexistence also appear in the matching Desk ticket, so the record stays whole. Older workspaces and external helpdesks follow different routes, and our [Botpress human handoff guide](/articles/botpress-human-handoff) keeps the three apart with what each one needs.


## FAQ

**Can I connect WhatsApp to a bot built in Botpress Viber?**

Yes. Botpress Viber lists WhatsApp among its publishing channels, alongside Webchat, Telegram, Instagram, Messenger, Slack and Twilio.

**How are WhatsApp conversations counted for billing?**

The same way as any Botpress conversation: an exchange with at least two messages from the customer in the billing month. A conversation that spans two billing months counts in both.

**Can I move an existing WhatsApp chatbot from another platform into Botpress?**

Not automatically. Botpress has no import tool for existing chatbots, so the flows and content are rebuilt by hand in Studio before you connect the channel.

**What support comes with a Free-plan WhatsApp bot?**

Free relies on community support through Discord, the docs, Botpress Academy and YouTube. Live chat with Botpress support engineers starts on the Plus plan.


## Is a Free-plan WhatsApp bot enough to start?

For a pilot, yes. WhatsApp sits on the Free plan with the same integration the paid plans get, so the real limits at the start are Meta's verification, your template approvals and 100 conversations with no top-ups. Build and test inside those limits, count how many conversations an ordinary week produces, then price Plus against that measured number instead of a guess. If the line grows past roughly 1,350 conversations a month billed monthly, or past roughly 1,150 a month at the annual rates, Team's base plan works out cheaper than Plus with packs by our arithmetic. Near that line, by the FAQ's 95% rule, the real bill can be one pack higher, so the count you collect during the pilot also tells you which paid plan to move to.



## Sources

[1] Botpress pricing — https://botpress.com/pricing (2026-11)
[2] AI Customer Support Platform with WhatsApp Integration — https://botpress.com/integrations/whatsapp (2026-11)
[3] Botpress documentation: Changelog — https://botpress.com/docs/changelog (2026-11)
[4] Botpress documentation: Start a WhatsApp conversation proactively — https://botpress.com/docs/integrations/integration-guides/whatsapp/whatsapp-start-proactively (2026-11)
[5] Botpress Refund Policy — https://botpress.com/legal/refund-policy
[6] G2: Botpress reviews — https://ai.g2.com/product/botpress