WhatsApp Cloud API Setup
What it is
The WhatsApp Cloud API channel connects BotBat to WhatsApp through Meta's hosted API infrastructure. This is the recommended integration method because Meta manages the underlying WhatsApp servers, which means you do not need to provision or maintain any WhatsApp-specific infrastructure yourself. The Cloud API supports the full range of WhatsApp Business features, including template messages, media attachments, interactive buttons, list menus, reactions, and read receipts.
Setting up the channel involves five core activities: creating a Meta Business account, obtaining a permanent API token, configuring the webhook in both BotBat and the Meta Developer portal, registering your business phone number, and validating the connection with a test message. Once connected, all WhatsApp conversations flow into the BotBat Inbox, and you can use WhatsApp as a target channel for campaigns, chatbots, and workflow automations.
The Cloud API enforces a 24-hour session window. Within that window (starting from the customer's last inbound message), you can send free-form replies. Outside the window, you must use a pre-approved message template. BotBat handles this distinction automatically by prompting agents to select a template when the session has expired.
When to use
Adding WhatsApp as a messaging channel. This is the primary setup path for any business that wants to communicate with customers on WhatsApp. Whether your goal is customer support, marketing outreach, or transactional notifications, the Cloud API channel is the starting point.
Migrating from a third-party WhatsApp provider. If you are switching to BotBat from another WhatsApp BSP (Business Solution Provider), you can transfer your existing WhatsApp number by following Meta's number migration process and then connecting it through this channel setup. The migration preserves your number's quality rating and messaging tier.
Enabling WhatsApp for campaigns and chatbots. Campaigns, chatbots, and workflows that target WhatsApp all require this channel to be connected and in a "Connected" state. If the channel is disconnected or in an error state, scheduled campaigns targeting WhatsApp will fail.
Prerequisites
Before you begin, make sure you have the following items ready.
| Requirement | Details |
|---|---|
| Meta Business account | Created at business.facebook.com with business verification completed |
| Meta Developer app | Created at developers.facebook.com with the "WhatsApp" product added |
| Permanent API token | A System User token (not the temporary 24-hour test token) generated in the Meta Business settings |
| Phone Number ID | Displayed on the API Setup page of your WhatsApp product in the Meta Developer portal |
| WhatsApp Business Account ID | Displayed alongside the Phone Number ID on the same API Setup page |
| Business phone number | A number that is not already registered on the regular WhatsApp app or another BSP |
Steps
1. Add the WhatsApp channel in BotBat
Navigate to Channels > Add Channel > WhatsApp Cloud API. The setup form asks for three values: the API token, the Phone Number ID, and the WhatsApp Business Account ID. Paste each value into the corresponding field and click "Save."
2. Configure the webhook
After saving, BotBat generates a unique webhook URL and a verification token. Both values are displayed on the channel configuration page. Click the copy button next to each value.
3. Set the webhook in Meta
Open your Meta app's WhatsApp product settings and navigate to Configuration > Webhook. Paste the BotBat webhook URL into the "Callback URL" field and the verification token into the "Verify token" field. Click "Verify and Save." Then subscribe to the following webhook fields:
| Webhook Field | Purpose |
|---|---|
messages | Delivers incoming messages, message status updates, and errors |
messaging_postbacks | Delivers button-click and quick-reply postback events |
message_template_status_update | Notifies when a template is approved, rejected, or paused |
4. Verify the connection
Meta sends a GET request to your webhook URL with a challenge parameter. If the URL and token match, the verification succeeds. Return to BotBat and confirm that the channel status shows "Connected" with a green indicator.
5. Register and verify your phone number
If you are registering a new number, Meta requires you to verify ownership through an SMS or voice call OTP sent to the business phone. Follow the prompts in the Meta Developer portal to complete this step. Numbers migrated from another BSP skip this step if the migration was completed successfully.
6. Set your business profile
In BotBat's WhatsApp channel settings, configure your business display name, profile photo, about text, and business category. These details are visible to customers when they open your WhatsApp contact information. A complete and professional profile builds trust and improves response rates.
7. Send a test message
Open WhatsApp on a personal device and send a message to your registered business number. Switch to BotBat and confirm that the message appears in the Inbox as a new conversation. This validates the entire pipeline: webhook delivery, message parsing, and Inbox routing.
WhatsApp-specific features
After setup, the following WhatsApp capabilities are available through BotBat.
| Feature | Description |
|---|---|
| Message templates | Send pre-approved template messages to initiate conversations outside the 24-hour session window. See Templates and WhatsApp Templates. |
| Media messages | Send and receive images, videos, documents, audio files, stickers, and location pins. |
| Interactive messages | Send messages with up to 3 quick-reply buttons or list menus with up to 10 sections for structured user interactions. |
| Reactions | View emoji reactions that contacts add to your messages. |
| Read receipts | Track message delivery status (sent, delivered, read) in real time. |
Common pitfalls
Using a temporary token. The Meta Developer portal provides a temporary test token that expires in 24 hours. If you use this token for your production channel, the connection will break every day. Always generate a permanent System User token in your Meta Business settings.
Webhook subscription missing fields. If you do not subscribe to the messages webhook field, BotBat will not receive any incoming messages. After verifying the webhook, double-check that all three recommended fields are subscribed and that the subscription status shows a green checkmark.
Business verification not completed. Meta restricts API access until business verification is finished. Without verification, you can only message phone numbers that are registered as test numbers in the Meta Developer portal. Complete verification before planning any customer-facing launch.
Phone number already registered elsewhere. A WhatsApp phone number can only be registered with one Business API provider at a time. If your number is currently active on the regular WhatsApp app or with another BSP, you must deregister or migrate it before connecting it to BotBat.
Rate limits on new numbers. Newly registered WhatsApp Business numbers start with a daily sending limit of 250 business-initiated conversations. This limit increases automatically as you maintain a healthy quality rating. Do not schedule a large-scale campaign on a brand-new number.
Keep your Meta app credentials (API token, Business Account ID) stored in a secure secrets manager and share them only with team members who manage channel configurations. Rotate the token periodically and update it in BotBat's channel settings immediately after rotation.
- WhatsApp Setup Form
- Webhook Configuration
- Business Profile
- Connection Status