WhatsApp Business API Setup

Complete step-by-step guide to set up WhatsApp Business API and integrate it with your Team Inbox.

TL;DR - Quick Setup

Create Meta Business Account

business.facebook.com → Create account → Verify email

Create WhatsApp App

Add App → Business type → Add WhatsApp product → Add phone number

Get Credentials

Copy: Access Token (System Users), Phone Number ID, Business Account ID

Setup Webhook

Configuration → Webhook → Add your API URL + verify token → Subscribe to messages

Total time: ~30 minutes | Cost: Free (test mode) / Pay per conversation (production) Credentials needed: Access Token, Phone Number ID, Business Account ID, Webhook Verify Token

Overview

To use WhatsApp Team Inbox, you need:

Meta Business Account

Free to create at business.facebook.com

WhatsApp Business App

Created within Meta Business Suite

Phone Number

Dedicated number for your business

API Access

Cloud API access (free tier available)

Prerequisites

Before starting, ensure you have:

A Meta (Facebook) account

A phone number not currently registered with WhatsApp (can be landline)

Business verification documents (for production use)

Admin access to create a Meta Business Account

Step 1: Create Meta Business Account

Go to Meta Business Suite

Visit business.facebook.com and log in with your Facebook account.

Create Business Portfolio

Click Create Account and follow the prompts:

Enter your business name
Provide business details
Add a business email

Verify Your Business Email

Check your email and click the verification link sent by Meta.

Step 2: Create WhatsApp Business App

Access App Creation

In Meta Business Suite, go to Business Settings
Click Accounts → Apps
Click Add → Create a New App

Select App Type

Choose Business as your app type and click Next.

Configure App Details

App Name: WhatsApp Team Inbox (or your preferred name)
App Contact Email: Your support email
Business Portfolio: Select your business account

Click Create App.

Add WhatsApp Product

In your app dashboard, find WhatsApp product
Click Set Up to add WhatsApp to your app

Step 3: Configure WhatsApp Business Profile

Access WhatsApp Settings

Navigate to WhatsApp → Getting Started in your app dashboard.

Add Phone Number

Click Add Phone Number
Enter your business phone number
Choose SMS or voice call for verification
Enter the verification code you receive

This phone number cannot be used with regular WhatsApp or WhatsApp Business app.

Set Up Business Profile

Configure your business profile:

Business Name: Your company name
Category: Select appropriate business category
Description: Brief about your business
Profile Photo: Upload your logo (640x640px recommended)
Address: Business address (optional)
Website: Your website URL

Step 4: Get API Credentials

Phone Number ID

Navigate to API Setup

Go to WhatsApp → API Setup in the left sidebar.

Copy Phone Number ID

Find the Phone Number ID field and copy it.

# Example format:
123456789012345

Save this as WHATSAPP_PHONE_NUMBER_ID in your .env file.

Access Token

Create System User

Go to Business Settings → Users → System Users
Click Add and create a new system user:
- Name: WhatsApp Team Inbox API
- Role: Admin

Assign Assets

Click on your system user
Click Add Assets
Select your WhatsApp app
Enable Full Control
Click Save Changes

Generate Access Token

Click Generate New Token
Select your WhatsApp app
Set token expiration to Never
Select permissions:
- whatsapp_business_messaging
- whatsapp_business_management
Click Generate Token
Copy and save the token immediately (it won’t be shown again)

Save this as WHATSAPP_ACCESS_TOKEN in your .env file.

Store this token securely. Never commit it to version control or expose it publicly.

Business Account ID

Find Business Account ID

Go to Business Settings → WhatsApp Accounts
Copy the WhatsApp Business Account ID

Save this as WHATSAPP_BUSINESS_ACCOUNT_ID in your .env file.

Step 5: Configure Webhook

Webhooks allow WhatsApp to send incoming messages to your Team Inbox.

Generate Verify Token

First, create a random verification token:

openssl rand -hex 16

Save this as WHATSAPP_WEBHOOK_VERIFY_TOKEN in your .env file.

Set Up Webhook in Meta

Access Webhook Configuration

Go to WhatsApp → Configuration → Webhook.

Enter Webhook Details

Callback URL: Your API endpoint for receiving webhooks

https://api.your-domain.com/api/webhook

Verify Token: The token you generated aboveClick Verify and Save.

For local development, use a tunneling service like ngrok:

ngrok http 4000
# Use the HTTPS URL: https://abc123.ngrok.io/api/webhook

Subscribe to Webhook Fields

Enable these webhook fields:

✅ messages - Receive incoming messages
✅ message_status - Receive message delivery status (sent, delivered, read)

Click Save.

Test Webhook Connection

Send a test message to your WhatsApp number to verify the webhook is working.Check your backend logs:

docker-compose logs -f backend

You should see incoming webhook events.

Step 6: Test Configuration

Send Test Message

Use the API Test tool in Meta Business Suite:

Access API Test Tool

Go to WhatsApp → API Setup → Send and receive messages.

Send Test Message

Select a recipient phone number (can be your own number)
Choose a message type (text message recommended for testing)
Enter message content
Click Send Message

Verify Receipt

Check that:

Message appears in WhatsApp on recipient’s phone
Your Team Inbox receives the message via webhook
Backend logs show successful webhook processing

Verify Environment Variables

Ensure all required variables are set in your .env file:

# WhatsApp Business API
WHATSAPP_API_URL=https://graph.facebook.com/v21.0
WHATSAPP_ACCESS_TOKEN=EAAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_BUSINESS_ACCOUNT_ID=123456789012345
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your_random_token_here

API Limits & Pricing

Free Tier (Cloud API)

Test Mode

5 conversations per day
Message template testing
Webhook configuration
Perfect for development

Business Verification Required

For production use
Higher conversation limits
Access to all features

Conversation-Based Pricing

WhatsApp charges per conversation (24-hour window):

Type	Description	Price
Business-initiated	You message user first	~$0.005-0.10 per conversation*
User-initiated	User messages you first	Free for 24 hours after first message
Service conversations	Utility/authentication	Lower rates

*Pricing varies by country. Check WhatsApp Pricing for details.

Conversation Window: Once a conversation starts, you have 24 hours to send messages freely without additional charges.

Message Templates

For business-initiated conversations, you must use approved templates.

Create Message Template

Access Templates

Go to WhatsApp → Message Templates.

Create New Template

Click Create Template and configure:

Template Name: greeting_new_user (lowercase, underscores only)
Category: Marketing, Utility, or Authentication
Languages: Select languages you’ll use
Template Content: Your message with optional variables

Example:

Hello {{1}}, welcome to our service!
How can we help you today?

Submit for Approval

Submit your template for Meta review. Approval typically takes 1-24 hours.

Use Approved Templates

Once approved, use templates in your application:

const response = await sendWhatsAppTemplate({
  to: phoneNumber,
  template: 'greeting_new_user',
  variables: ['John']
});

Production Checklist

Before going live with WhatsApp API:

WhatsApp Business Account verified by Meta

Business display name approved

Permanent access token generated

Webhook configured and tested

Message templates created and approved

Phone number verified and tested

Webhook URL is HTTPS and publicly accessible

Environment variables configured correctly

Rate limits and pricing understood

Business Verification

For production use and higher limits:

Start Verification

Go to Business Settings → Security Center
Click Start Verification

Provide Business Information

Required documents:

Business registration certificate
Business address proof
Tax documents (varies by country)
Website or social media presence

Wait for Review

Meta typically reviews within 1-3 business days.You’ll receive email updates on verification status.

Common Issues & Solutions

Webhook verification failed

Causes:

Verify token mismatch
Webhook URL not accessible
SSL certificate issues

Solutions:

Ensure WHATSAPP_WEBHOOK_VERIFY_TOKEN matches in both places
Test webhook URL accessibility: curl https://your-domain.com/api/webhook
Verify SSL certificate is valid

Messages not being received

Causes:

Webhook not subscribed to correct fields
Firewall blocking Meta’s IP ranges
Backend not processing webhook events

Solutions:

Check webhook subscriptions include messages field
Whitelist Meta’s webhook IPs
Check backend logs: docker-compose logs backend

Access token expired

Causes:

Token was set to expire
Token was revoked

Solutions:

Generate new token with Never expiration
Update WHATSAPP_ACCESS_TOKEN in environment
Restart backend: docker-compose restart backend

Cannot send template messages

Causes:

Template not approved
Template name incorrect
Variables not matching template

Solutions:

Verify template status in Meta Business Suite
Check template name matches exactly (case-sensitive)
Ensure variable count matches template placeholders

Security Best Practices

Critical Security Measures:

Never expose access tokens
- Don’t commit to version control
- Use environment variables only
- Rotate tokens periodically
Verify webhook signatures
- Validate X-Hub-Signature-256 header
- Reject unsigned requests
Use HTTPS only
- Never use HTTP in production
- Ensure valid SSL certificates
Monitor API usage
- Set up alerts for unusual activity
- Review access logs regularly
Limit access token permissions
- Use minimum required scopes
- Create separate tokens for different services

API Rate Limits

Be aware of WhatsApp API rate limits:

Tier	Messages/Second	Criteria
Tier 1	80	Default for new businesses
Tier 2	400	After 7 days of good messaging
Tier 3	1,600	After 14 days of good messaging
Tier 4	6,400	After 21 days of good messaging

Quality rating and user feedback affect tier progression. Maintain high message quality to increase limits.

Monitoring & Analytics

Track your WhatsApp API usage:

Access Analytics

Go to WhatsApp → Analytics in Meta Business Suite.

Monitor Key Metrics

Message volume (sent/received)
Conversation costs
Template performance
Delivery rates
Quality rating

Set Up Alerts

Configure alerts for:

High message volumes
Quality rating drops
Failed deliveries
Cost thresholds

Next Steps

Environment Variables

Configure all required environment variables

Quick Start

Deploy your Team Inbox

Message Templates

Create and manage message templates

Going Live

Production deployment checklist

Deployment Guide

Platform Deployments

​WhatsApp Business API Setup

​TL;DR - Quick Setup

​Overview

Meta Business Account

WhatsApp Business App

Phone Number

API Access

​Prerequisites

​Step 1: Create Meta Business Account

​Step 2: Create WhatsApp Business App

​Step 3: Configure WhatsApp Business Profile

​Step 4: Get API Credentials

​Phone Number ID

​Access Token

​Business Account ID

​Step 5: Configure Webhook

​Generate Verify Token

​Set Up Webhook in Meta

​Step 6: Test Configuration

​Send Test Message

​Verify Environment Variables

​API Limits & Pricing

​Free Tier (Cloud API)

Test Mode

Business Verification Required

​Conversation-Based Pricing

​Message Templates

​Create Message Template

​Production Checklist

​Business Verification

​Common Issues & Solutions

​Security Best Practices

​API Rate Limits

​Monitoring & Analytics

​Next Steps

Environment Variables

Quick Start

Message Templates

Going Live

​Additional Resources

WhatsApp Business API Setup

TL;DR - Quick Setup

Overview

Prerequisites

Step 1: Create Meta Business Account

Step 2: Create WhatsApp Business App

Step 3: Configure WhatsApp Business Profile

Step 4: Get API Credentials

Phone Number ID

Access Token

Business Account ID

Step 5: Configure Webhook

Generate Verify Token

Set Up Webhook in Meta

Step 6: Test Configuration

Send Test Message

Verify Environment Variables

API Limits & Pricing

Free Tier (Cloud API)

Conversation-Based Pricing

Message Templates

Create Message Template

Production Checklist

Business Verification

Common Issues & Solutions

Security Best Practices

API Rate Limits

Monitoring & Analytics

Next Steps

Additional Resources