Set Up WhatsApp in Chatwoot: Quick vs Manual Setup

Connect your WhatsApp Business account to Chatwoot using Quick Setup (simplest, built-in), Manual Setup (for self-hosted), or Twilio (if already using it). Each takes 10-20 minutes after you gather your Meta Business Account credentials. Quick Setup supports phone app coexistence; Manual doesn't. Choose based on whether you want to keep using the WhatsApp app on your phone.

Three Ways to Connect WhatsApp to Chatwoot

Chatwoot offers three connection methods, each with tradeoffs in speed, control, and phone app compatibility. Quick Setup is Meta's embedded flow within Chatwoot--fastest, recommended for most teams. Manual Setup requires you to generate a system user token in Meta Business Manager and paste it into Chatwoot, giving you explicit control but demanding more steps. Twilio works if your team is already paying Twilio for SMS or voice, though per-message costs are higher than Meta's native API. WAHA is a free, open-source alternative for teams wanting complete self-hosting and decentralized control.

Here's how they compare:

Coexistence means you can keep using the WhatsApp Business app on your phone while Chatwoot receives API messages--useful for teams that want some channels automated and others manual. Quick Setup enables this. Manual Setup does not: once you connect your number via API, the WhatsApp Business app won't work from that number. Meta prevents two simultaneous connections to the same business number.

Before You Start: Prerequisites and Requirements

You'll need four things ready before attempting any connection method. First, create a Meta Business Account at business.facebook.com (free). Verify your business name and confirm an email address. Second, ensure you have admin access to your Chatwoot workspace. Third, have an eligible phone number: it must be a business number (not a personal SIM), not currently registered to any WhatsApp account (personal or business), and must accept SMS or voice verification from Meta. If your number is already on WhatsApp, deregister it first by uninstalling the app and waiting 30 days.

For Quick Setup, you need admin permissions in both Meta Business Manager and your Chatwoot workspace. For Manual Setup, you need webhook URL capability: your Chatwoot instance must be publicly accessible so Meta can reach your webhook endpoint. If you're on Chatwoot Cloud, this is handled. If self-hosting, ensure you have a valid SSL certificate using HTTPS rather than HTTP. Let's Encrypt offers free certificates. Test your certificate with openssl s_client -connect your-chatwoot.com:443 before attempting the integration.

Option 1: Quick Setup with Meta (Recommended)

Quick Setup is the fastest path for most teams and works on Chatwoot Cloud and self-hosted instances.

Step 1: Log in to Chatwoot and navigate to Settings (gear icon, bottom left) > Integrations > WhatsApp. Click the blue "Setup with Meta" button.

Step 2: A new browser tab opens Meta's login page. Sign in with the account attached to your Meta Business Account owner or admin email.

Step 3: Follow Meta's embedded signup flow. Meta will ask you to create or connect an existing WhatsApp Business Account, register your phone number, and authorize Chatwoot to manage it. You'll receive an SMS or voice call to verify your number. Have your phone nearby.

Step 4: Once Meta finishes verification, you're redirected back to Chatwoot. The integration shows "Connected" status. Incoming messages now land in your Chatwoot inbox within seconds.

Why Quick Setup works well: Meta handles verification, token refresh, and security updates. You don't store or manually refresh tokens. Chatwoot updates automatically if Meta changes APIs. You keep using the WhatsApp app on your phone for personal messages; the API inbox in Chatwoot is separate. The trade-off is flexibility. You have fewer configuration options than Manual Setup. You're tied to Chatwoot's integration; if Chatwoot deprecates WhatsApp support, you'd need to reconnect elsewhere. For 90% of teams, this trade-off is worth it.

Quick Setup typically works within 5 minutes if your phone number is already deregistered. If Meta requests additional business documentation, verification may take 24-48 hours.

Option 2: Manual Setup for Self-Hosted or Existing Accounts

Manual Setup gives you explicit control over every token and webhook. It's necessary if you're running self-hosted Chatwoot without a Cloud integration, or if you already have a WhatsApp Business account and want to connect it without re-registering.

Step 1: Create a system user in Meta Business Manager. Go to business.facebook.com > Settings > Users > System Users. Click "Create System User." Name it something like "Chatwoot_Integration." Choose "Admin" role. Add the "Manage WhatsApp business accounts" permission (whatsapp_business_management).

Step 2: Generate a long-lived token. In the System Users list, click your new user. Under "User Token," click "Generate." Select the app you created for Chatwoot (or create a new one in Meta Developers). The token expires in 60 days. Copy it--you won't see it again. Store it securely.

Step 3: Register your phone number to a WhatsApp Business Account. Go to business.facebook.com > WhatsApp Accounts. Click "Create Account." Enter your phone number and complete Meta's verification via SMS or voice. Write down the WABA ID (WhatsApp Business Account ID) and Phone Number ID. You'll need both for Chatwoot.

Step 4: Configure the webhook in Chatwoot. Go to Settings > Integrations > WhatsApp. Choose "Manual Setup." Paste your system user token, WABA ID, and Phone Number ID into the fields. Chatwoot generates a "Webhook URL" in the format your-domain.com/webhooks/whatsapp/. Copy this URL.

Step 5: Verify the webhook with Meta. Go to Meta Business Manager > WhatsApp > Configuration. Paste your Chatwoot webhook URL into the "Webhook URL" field. Meta sends a verification challenge to that URL. Chatwoot responds automatically. If successful, you'll see "Verified." If not, see the Common Webhook Errors section below.

Step 6: Test. Send a message to your WhatsApp Business number from your phone. It should appear in Chatwoot's inbox within seconds.

Why Manual Setup is useful: you control every credential. Tokens expire every 60 days, but you refresh them on your schedule. If you later switch to a different helpdesk, you already have your tokens and can reuse them. For self-hosted teams, this is the only option.

The downside is coexistence. Once you connect via API, the WhatsApp Business app won't work for that number. Manual Setup typically succeeds within 15 minutes, though webhook verification failures (see below) can add time.

Option 3: Twilio and Alternative Gateways

If your team is already using Twilio, Chatwoot has native Twilio support. Twilio acts as a middleman between you and Meta. You use Twilio's API instead of connecting directly.

Why use Twilio? If you're already paying Twilio for SMS, voice, or Programmable Messaging, adding WhatsApp simplifies billing and webhook configuration. Twilio handles Meta API complexity.

Why not use Twilio? Twilio's WhatsApp charges per message ($0.005-0.015 USD depending on message type and region). Meta's native API charges per conversation, which is cheaper for inbound-heavy scenarios. Twilio adds a middleman; direct integration is faster.

Alternative gateways: WAHA is an open-source HTTP API that functions like Twilio but runs on your server. It supports coexistence, full self-hosting, and no recurring fees beyond infrastructure costs. WAHA requires Docker expertise. 360dialog was popular but is no longer offered for new inboxes.

Common Webhook Errors & Fixes

Webhook errors occur when Meta tries to send messages to Chatwoot but fails. Here's a quick guide:

"Webhook verification failed" -- Chatwoot not responding, SSL cert invalid, or wrong URL pasted. Verify Chatwoot is running and publicly accessible. Check your SSL cert with openssl s_client -connect your-chatwoot.com:443. Confirm the webhook URL in Meta and Chatwoot match exactly (trailing slash, protocol).

"Missing whatsapp_business_management" or template access errors -- System user token lacks permission. In Meta Business Manager, go to System Users > your user > Assigned Apps > WhatsApp app. Verify the permission is granted. Regenerate the token.

"Unauthorized" or "invalid token" -- Token expired or revoked. Tokens expire every 60 days. In Meta Business Manager, regenerate a new token and paste it into Chatwoot.

"Phone number not registered" or "invalid WABA" -- Phone Number ID or WABA ID mismatched. Double-check in Meta Business Manager > WhatsApp > Phone Numbers. Verify the number's status is "Verified" and copy the exact IDs.

"404 Not Found" on webhook endpoint -- Webhook URL malformed or firewall blocks external traffic. For self-hosted: ensure your server is publicly accessible. Test connectivity from an external device. For Cloud: contact Opsily support.

The most common issue is SSL certificates. If self-hosting, use Let's Encrypt and set up auto-renewal with certbot. Expired certs cause all webhooks to fail.

Templates, Costs, and the 24-Hour Window

Meta's 24-hour rule is the biggest gotcha. Once a customer sends you a message, you have 24 hours to reply without restrictions. After 24 hours, you can only send messages using an approved template. Templates are pre-written message flows (like "Hi, your order shipped") that Meta approves in advance. This prevents spam.

To send outside the window, create a template in Chatwoot (Settings > Templates > WhatsApp). Write the message (up to 1,024 characters). Submit it to Meta. Approval typically takes 5 minutes to a few hours. Once approved, send it anytime.

Meta charges per conversation, not per message. A conversation is one-way or two-way messaging within a rolling 24-hour window. Customer-initiated messages are free to receive. Business-initiated messages (you start) cost money if sent outside the 24-hour window.

Regional pricing varies. Typical rates: $0.01-0.02 USD per business-initiated conversation, depending on country. Chatwoot displays the exact rate for your region in WhatsApp inbox settings. Check Meta's pricing calculator at meta.com/business/whatsapp/pricing.

CSAT surveys are included free. Monitor costs in Meta Business Manager > WhatsApp > Quality and Usage. Set up billing alerts to avoid surprises.

Next Steps: Beyond Setup

Once Chatwoot WhatsApp is live, create a template library (5-10 core templates for order confirmations, support escalations, appointment reminders). Use Chatwoot's Campaigns feature to send broadcasts. Monitor account health in Meta's Account Health dashboard; poor quality ratings restrict messaging speed. Train your team on the 24-hour window and template requirements.

For teams avoiding self-hosted infrastructure, Opsily's managed Chatwoot hosting removes setup friction. Let your team focus on customer conversations, not webhooks and certificates.

Frequently Asked Questions

How do I integrate WhatsApp with Chatwoot? Use Quick Setup (Meta's embedded flow, 5 minutes, recommended) or Manual Setup (system user token, 15 minutes, self-hosted option). Both land messages in Chatwoot's unified inbox.

Does Chatwoot support WhatsApp group chats? No. Chatwoot WhatsApp supports one-to-one conversations only. Group chats are not supported; this is a Meta API limitation.

What's the difference between Quick Setup and Manual Setup? Quick Setup is faster, uses embedded authorization, and supports coexistence (phone app works alongside API). Manual Setup requires you to generate and paste tokens, disables coexistence, but gives explicit control over credentials.

How do I set up WhatsApp templates in Chatwoot? Go to Settings > Templates > WhatsApp. Write your message (max 1,024 characters). Click Submit. Meta approves in 5 minutes to a few hours. Once approved, send it via campaigns or outside the 24-hour window.

What are WhatsApp messaging costs in Chatwoot? Meta charges per conversation (rolling 24-hour window). Typical rates: $0.01-0.02 USD per business-initiated conversation, depending on region. User-initiated (customer sends you a message) are free to receive.

How do I fix webhook verification errors? Verify your Chatwoot instance is publicly accessible with a valid HTTPS SSL certificate. Confirm the webhook URL in Meta and Chatwoot match exactly. If using a system user token, ensure it has whatsapp_business_management permission and hasn't expired (60-day limit).

Can I keep using the WhatsApp Business app while using Chatwoot? Yes, if you use Quick Setup. Quick Setup supports coexistence. Manual Setup does not; you must choose one or the other.

How do I migrate from Twilio to WhatsApp Cloud API? In Chatwoot, disconnect your Twilio integration (Settings > Integrations > Twilio > Disconnect). Create a new WhatsApp Business Account in Meta (or use existing). Connect via Quick Setup or Manual Setup. Messages switch to Chatwoot's WhatsApp inbox. Billing moves from Twilio's per-message rates to Meta's per-conversation rates.

The Bottom Line

Quick Setup is the standard: five minutes, no tokens to manage, coexistence included. Manual Setup is for self-hosted teams seeking control. Chatwoot WhatsApp supports both simultaneously, so you can upgrade later. Meta's 24-hour window and per-conversation costs are real but manageable with template planning. For teams avoiding infrastructure management, Opsily's managed Chatwoot hosting removes setup burden and gives you a team to handle webhook configuration. Start with Quick Setup, approve your templates, and watch all your channels funnel into one unified inbox.