WhatsApp Business API Setup

Purpose

Use this guide when setting up a new WhatsApp Business Platform account for a customer, connecting a production phone number, creating the Meta app, completing business verification, and preparing the account for ERPNext, CRM, chatbot, or notification integration.

This guide assumes the direct Meta Cloud API setup. If the customer uses a BSP or solution partner, the same concepts apply, but the partner portal may handle some of the Meta steps.

Video Walkthrough

Watch this walkthrough first if you are new to WhatsApp Business API setup. It shows the actual flow inside Meta for Developers, including login, selecting the app, opening WhatsApp setup, adding payment details, and starting business verification.

Walkthrough Notes

This section captures the practical conversation from the walkthrough, cleaned up into steps.

Log in with Facebook using the Facebook account that has access to the Meta Developer app and business account.
If Meta sends a login approval notification, approve it from the connected device such as iPad or phone.
Open Meta for Developers and go to My Apps from the top-right menu.
Select the customer app. In this walkthrough, the app selected was Agastya.
Understand the difference between the app and the business profile:
- The app is the technical asset where WhatsApp API, webhooks, app ID, and app secret are configured.
- The business profile or Business Portfolio is connected with the Facebook page, marketing activities, business verification, payment methods, and WhatsApp Business Account.
In the app menu, click WhatsApp.
Open API Setup. If the screen first shows Quick Start, move to API Setup from the WhatsApp section.
Click Add Payment when Meta asks for payment setup.
Fill the business, currency, and timezone details. For Indian businesses, choose INR as the currency.
Optional fields can be skipped if Meta marks them optional.
Click Update Payment Method.
Add a debit or credit card. Meta may temporarily charge and reverse a small amount, usually within 24 hours.
After the card is added, close the payment popup and confirm the payment method.
Start business verification. This unlocks additional business features and supports the verified/official business setup.
Click Start Verification and select the country, for example India.
Meta will ask for business details and documents. Keep the following ready:
- Legal business name
- GST number or Udyam Aadhaar number, if applicable
- Business registration document
- Address proof
- Business phone number
- Website or other proof that matches the business name
Take time to fill business verification carefully. Incorrect name, address, or document mismatch can cause rejection.
Completing verification helps prove that the WhatsApp account belongs to the official business. This is also part of the path toward stronger trust signals such as official business display and verification features, subject to Meta approval.

Quick Checklist

Before starting, confirm these items:

Meta login with admin access to the customer's Business Portfolio.
Legal business name, address, website, phone number, tax/registration document, and address proof.
A public website or business page that clearly matches the brand/display name.
A phone number that can receive SMS or voice OTP. Avoid IVR unless calls can reach a real person.
The number must not already be active on WhatsApp Messenger or the WhatsApp Business App, unless using an approved coexistence or migration flow.
A production webhook URL with HTTPS.
A privacy policy URL and app contact email for the Meta app.
A payment method in Meta Business settings before production messaging.
An internal owner for permanent token storage and rotation.

Accounts And Assets Involved

There are four main assets:

Meta Business Portfolio: owns the business, users, WABAs, system users, payment settings, and verification.
Meta Developer App: contains the WhatsApp product, app ID, app secret, webhook configuration, and permissions.
WhatsApp Business Account: also called WABA. This holds phone numbers, templates, profile, quality rating, and messaging limits.
WhatsApp Business Phone Number: the actual number used for API messaging. The most important IDs are Phone Number ID and WABA ID.

Step 1: Create Or Confirm The Meta Business Portfolio

Open Meta Business Settings:
- https://business.facebook.com/settings
Select the correct Business Portfolio.
Go to Business Info and confirm:
- Legal business name
- Address
- Website
- Business phone
- Primary page, if applicable
Add required users under People and assign admin access only to the implementation owner.
Enable two-factor authentication for admins where required.

Step 2: Complete Business Verification

Business verification confirms that Meta can trust the business identity. It may not be required for every initial test, but it is strongly recommended before production rollout because it affects trust, limits, and review paths.

In Business Settings, open Security Center or Business Info.
Start business verification if the option is available.
Submit documents that match the legal business name and address.
Use documents such as:
- Certificate of incorporation or GST/company registration certificate
- Utility bill, bank statement, tax document, or other address proof
- Website that clearly shows the same business or brand
Watch for Meta notifications. If rejected, correct mismatch issues before resubmitting.

Common rejection reasons:

Legal name on document does not match the Business Portfolio.
Address on document does not match the submitted business address.
Website does not show the brand/business clearly.
Uploaded document is cropped, expired, unreadable, or not official.
The display name looks like a product/client brand that is not clearly tied to the verified company.

Step 3: Create The Meta Developer App

Open Meta for Developers:
- https://developers.facebook.com/apps
Create a new app.
Select a business/business-related app type or use case.
Link the app to the correct Business Portfolio.
Add the WhatsApp product to the app.
In App Settings, complete:
- App name
- App contact email
- Privacy policy URL
- App domain
- Business portfolio link

Keep the app in development mode while testing. Move to live mode only after webhook, token, and production number setup are ready.

Step 4: Test With The Meta Test Number

In the app dashboard, open WhatsApp > API Setup.

Meta normally provides:

Temporary access token
Test phone number
Phone Number ID
WhatsApp Business Account ID
Test recipient setup

Add a recipient phone number for testing. Meta sends a verification code to that number. After it is verified, send a test message from the API Setup screen or with curl:

curl -X POST "https://graph.facebook.com/v22.0//messages" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": { "code": "en_US" }
    }
  }'

If this works, the app and Graph API access are basically functional.

Step 5: Add The Production Phone Number

The production number can be added from WhatsApp Manager, Meta Business Suite, or the app dashboard depending on the current Meta UI.

Open WhatsApp Manager:
- https://business.facebook.com/wa/manage
Select the correct WABA.
Add phone number.
Enter:
- Display name
- Business category
- Business description
- Country and phone number
Choose OTP method: SMS or voice call.
Enter the verification code.

Phone number rules:

The number must be reachable for OTP.
It cannot already be active on WhatsApp Messenger or WhatsApp Business App unless using Meta's supported migration/coexistence path.
If the number is behind IVR, disable IVR temporarily or route the OTP call to a real person.
The display name should match the business, brand, or website clearly.

After setup, capture:

Phone Number ID
WABA ID
Display name status
Messaging limit
Quality rating

Step 6: Create A Permanent System User Token

The temporary token is only for testing. For production, create a System User token from Business Settings.

Open Business Settings.
Go to Users > System Users.
Create or select a system user.
Assign the app to the system user.
Assign WhatsApp assets:
- WhatsApp Business Account
- Phone number, where visible
Generate a token with the required permissions:
- whatsappbusinessmessaging
- whatsappbusinessmanagement
Store the token only in the server-side secret manager or environment variables.

Do not store tokens in frontend code, wiki pages, screenshots, Git repos, or shared chat.

Step 7: Configure Webhooks

A webhook is required to receive incoming messages and delivery/read status updates.

In Meta Developer App, go to WhatsApp > Configuration.
Add Callback URL:
- Example: https://example.com/api/whatsapp/webhook
Add Verify Token:
- This is a random secret string generated by the implementation team.
Verify and save.
Subscribe to webhook fields:
- messages
- messagetemplatestatusupdate, if template review status is needed
- accountupdate and businesscapabilityupdate, if operational alerts are needed

The webhook endpoint must handle:

GET verification challenge from Meta.
POST incoming message payloads.
POST delivery, sent, read, and failed statuses.
Signature verification using the app secret, if implemented.
Fast response to Meta, ideally HTTP 200 within a few seconds.

Step 8: Complete Business Profile

In WhatsApp Manager, complete the phone number's business profile:

Profile photo/logo
Display name
About text
Business description
Website
Email
Address
Category

This improves user trust and reduces review friction.

Step 9: Create And Approve Message Templates

Business-initiated messages outside the customer service window must use approved templates.

Open WhatsApp Manager.
Go to Message Templates.
Create templates for:
- OTP or verification
- Order or delivery updates
- Appointment reminders
- Payment reminders
- Support follow-ups
Choose the right template category.
Avoid promotional wording in utility/authentication templates.
Add variables with clear sample values.
Submit for approval.

Template quality matters. Rejected or low-quality templates can affect messaging performance.

Step 10: Add Payment Method And Check Limits

Before production rollout:

Add or confirm payment method in Meta Business settings.
Check messaging limit for the business portfolio/phone number.
Check quality rating.
Keep initial campaign volume low until quality stabilizes.
Use opt-in records before sending outbound messages.

New accounts may start with lower messaging limits. Limits can increase as the business verifies, sends high-quality messages, and maintains a good quality rating.

Step 11: Production Integration Checklist

For ERPNext, CRM, chatbot, or notification integration, save these values in server-side settings:

Meta app ID
Meta app secret
WABA ID
Phone Number ID
Permanent system user access token
Webhook verify token
Graph API version
Webhook callback URL
Business display name
Template names and language codes

Run these tests:

Send test template to an internal number.
Reply from WhatsApp and confirm inbound message reaches webhook.
Confirm status updates for sent/delivered/read/failed.
Confirm template variable rendering.
Confirm failed message logging.
Confirm opt-out handling.
Confirm token is not exposed in browser/network logs.

Troubleshooting

WhatsApp product not visible in the app

Check app type/use case, Business Portfolio link, and account permissions. Try creating a fresh business app if the product is unavailable.

Phone number verification fails

Confirm the number can receive SMS or international voice calls. Disable IVR temporarily. Ensure the number is not already active on WhatsApp Messenger or WhatsApp Business App unless using a supported migration flow.

Display name stuck or rejected

Make the display name match the verified business, website, or brand. Add brand proof on the website if the display name differs from the legal company name.

Business verification rejected

Use clearer official documents. Ensure legal name, address, and website match exactly across Business Portfolio, documents, and public website.

Webhook verification fails

Check that the GET endpoint returns Meta's challenge exactly, the verify token matches, and the URL is HTTPS with a valid certificate.

Messages send from test number but not production number

Check permanent token permissions, asset assignment, Phone Number ID, payment method, display name status, phone number status, and messaging limits.

Templates are rejected

Use the correct category, remove promotional language from utility/authentication templates, and include realistic examples for every variable.

Handover Notes

At the end of setup, hand over:

WABA ID
Phone Number ID
Business Portfolio name/ID
Meta app name/ID
Webhook URL
Template list
Phone number status
Display name status
Business verification status
Messaging limit/quality rating
Token storage location, without exposing the token itself

Official References

WhatsApp Cloud API Get Started: https://developers.facebook.com/docs/whatsapp/cloud-api/get-started
WhatsApp Cloud API overview: https://developers.facebook.com/docs/whatsapp/cloud-api/overview
Webhooks setup: https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks
Business phone numbers: https://developers.facebook.com/docs/whatsapp/business-phone-numbers
Message templates: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates
Meta app dashboard: https://developers.facebook.com/apps
Meta Business Settings: https://business.facebook.com/settings
WhatsApp Manager: https://business.facebook.com/wa/manage

Industries