Configuration Guide: WhatsApp Business API

Step-by-step guide to integrate WhatsApp Business API with Odoo

Prepared by Agilezip for its clients

Who performs each step:

CLIENT

AGILEZIP

BOTH

Scenario:

Both scenarios

Migration only

New number only

Prerequisites and Preparation

Verify all requirements are met before starting

Fundamental principle of this guide: All Meta configuration (Phases 1-3) is done before releasing the WhatsApp number. This way, if the verification or approval process takes days, the business continues operating normally with its current WhatsApp. The actual migration (Phase 4) is only executed when everything is approved and ready.

CLIENTStep 0.1Both scenarios

Verify the phone number is active

Important fact: The number does NOT need to be a mobile number. Any verifiable number works: landline, digital line, VoIP, PBX. The only requirement is being able to receive a phone call or an SMS on that number for the verification process.

Before doing anything else, confirm the number is active and functional with these 3 tests:

Inbound call: Call the number from another phone — verify it rings and can be answered. If PBX, verify it can be answered without dialing an extension (Meta does not support extensions)
Outbound call: Make a call from the number — confirm it can make calls. If not, the line may be suspended or deactivated
Top-up / balance: If it is a prepaid number, verify you can add balance. If the carrier no longer allows top-ups, the number may have been recycled or permanently deactivated

Real risk: If the number has been unused or without balance for a long time, the carrier may have deactivated it. It is essential to confirm the number is active with the 3 tests above. Discovering the number is inactive after deleting WhatsApp Business results in total loss of communication through that channel.

Screenshot: Example of successful verification with landline

CLIENTStep 0.2Both scenarios

Verify prerequisites

Before continuing, make sure you have:

Access to the email associated with the Meta / Facebook Business account
Administrator access to Meta Business Suite
Access to Meta for Developers with the same account
The phone number confirmed as active (Step 0.1)
A credit card to register as payment method on Meta
Company documents for business verification (business registration, articles of incorporation, or similar)

CLIENTStep 0.3Migration only

Back up WhatsApp Business App conversations

If the number currently has WhatsApp Business App, back up conversations. Do not delete the account yet — that will be done in Phase 4 when everything is approved.

Open WhatsApp Business on the phone
Go to Settings > Chats > Chat backup
Link Google Drive account if not linked
Disable Include videos (to reduce size)
Tap Back up

The backup is preventive. The business continues using WhatsApp normally during Phases 1 to 3 while everything is prepared on Meta.

CLIENTStep 0.4Migration only

Verify the backup

Confirm in Google Drive that the backup file was generated correctly. Go to Google Drive > WhatsApp Business and verify the backup date matches today.

Configure Meta Developer Portal

Create the App and link WhatsApp — without affecting current operations

This phase can be done without affecting the company's current WhatsApp. If the number already has WhatsApp Business App, the business continues operating normally while Meta is configured.

CLIENTStep 1.1

Create an App in Meta for Developers

Go to Meta for Developers - Apps
Click Create App
In "What do you want your app to do?", select Other
Select app type: Business
Enter app name (e.g., "MyCompany WhatsApp")
Select the company's Business Portfolio
Click Create App

Screenshot: App creation screen in Meta for Developers

CLIENTStep 1.2

Get App ID and App Secret

Go to App Settings > Basic
Note the App ID (shown in the top bar)
Click Show next to App Secret and note it

Note these values: They will be needed at the end to configure Odoo.

Screenshot: App Settings showing App ID and App Secret

CLIENTStep 1.3

Add WhatsApp product to the App

In the App Dashboard, go to Add products to your app
Find WhatsApp and click Set up
The WhatsApp section will open with the Quick Start screen

CLIENTStep 1.4

Identify the WhatsApp Business Account (WABA) ID

In the section WhatsApp > API Setup, locate the WABA ID
Note the WhatsApp Business Account ID

The WABA ID can also be found at Meta Business Suite > Settings > WhatsApp Accounts

Verification, Payment and Approval

Complete Meta requirements before migrating — the business continues operating normally

This phase may take 1 to 5 business days depending on Meta's review speed. During this time, the business continues using WhatsApp Business App normally. No rush.

CLIENTStep 2.1

Business verification

Meta requires verifying the business identity before approving the WhatsApp Business API account:

Go to Meta Business Suite > Settings > Business security and integrity
In the Business verification section, click Start verification
In the selector "Select your verification use case", choose:
"The app requires access to permissions in Meta for Developers"
Follow the process: upload company documents (business registration, articles of incorporation, proof of address, etc.)
Submit and wait for Meta review (approximately 2 business days)

Watch out with the selector: The dropdown shows 3 options. The third option ("How to create a WhatsApp Business account") is confusingly worded — do not select it. The correct option is the first one: "The app requires access to permissions in Meta for Developers".

Screenshot: Use case selector with the correct option highlighted

CLIENTStep 2.2

Add payment method

Meta requires an active payment method for the WhatsApp Business API account:

Go to Meta Business Suite > Billing and payments
Add a credit card as payment method
Verify the card is associated with the WhatsApp Business account

WhatsApp Business API costs depend on message volume and type. The first 1,000 service conversations per month are free.

Screenshot: Payment method configured successfully

CLIENTStep 2.3

Confirm approval — Green light

Before proceeding to the next phase, verify that all lights are green:

Go to Meta Business Suite > Settings > WhatsApp Accounts
Select the WhatsApp Business account
In the Overview tab, confirm:

Checklist — All must be green to continue

Business verification: Verified

Account status: Approved

Payment method: Card registered

Phone number: Active and verified (Step 0.1)

Do not continue if any is missing. If status shows "Under review", wait for Meta to approve. If verification failed, correct documents and retry. Continuing without approval may result in unnecessary communication loss.

Screenshot: Account summary showing all indicators in green

Permanent Access Token

Generate a non-expiring token for Odoo integration

The temporary token shown in "API Setup" expires in 24 hours. For production, a permanent token is needed via System User.

CLIENTStep 3.1

Create a System User in Meta Business Suite

Go to Meta Business Suite > Settings > System Users
Click Add
Name: something descriptive (e.g., "Odoo Integration")
Role: Admin
Click Create system user

Screenshot: System User creation screen

CLIENTStep 3.2

Assign assets to System User

Select the newly created System User
Click Add assets
In the Apps section, select the App created in Phase 1 and assign Full control
In the WhatsApp Accounts section, select the WABA and assign Full control

CLIENTStep 3.3

Generate permanent token

With the System User selected, click Generate token
Select the App created in Phase 1
Select permissions:
- whatsapp_business_management
- whatsapp_business_messaging
Click Generate token
Copy and save the token — it will only be shown once

Security: The token is like a password. Store it securely and never share it through insecure channels.

Screenshot: Token generation dialog with permissions selected

Release the number (if applicable) and register it as WhatsApp API

At this point everything is approved and ready. The following steps are completed in minutes. The business will have WhatsApp API operating the same day.

CLIENTStep 4.1Migration only

Delete the WhatsApp Business account

Point of no return: Deleting the account means losing access to conversation history. Verify the backup from Step 0.3 is complete.

Open WhatsApp Business on the phone
Go to Settings > Account > Delete account
Enter the phone number and confirm deletion
Wait 5 to 10 minutes for Meta to process the release

CLIENTStep 4.2

Add phone number in Meta Developer Portal

In the Meta App, go to WhatsApp > API Setup
Click Add phone number
Enter profile data:
- Display name (name clients will see)
- Business category
Enter the phone number with country code (+52 for Mexico)
Select verification method: SMS or Phone call

Landlines and PBX: Select "Phone call". Meta will make an automated call with a code. Someone must answer directly (no extensions).

Screenshot: Dialog for adding number with verification method selection

CLIENTStep 4.3

Verify the number and enter the code

Receive the verification code via SMS or call
Enter it in the Meta portal
Wait for successful verification confirmation

Once verified, the number is registered as WhatsApp Business API.

CLIENTStep 4.4

Note the Phone Number ID

Select the newly registered number in the API Setup dropdown
Note the Phone Number ID below the selector

Note: The Phone Number ID is an internal Meta identifier (numeric like 123456789012345), not the phone number itself.

Two-Step Verification (PIN)

Agilezip generates and configures the security PIN via Graph API

AGILEZIPStep 5.1

Activate two-step verification

Once the phone number is registered and the API is active (Phase 4), Agilezip activates two-step verification via the Meta Graph API. The client does not need to configure this manually.

Agilezip generates a secure 6-digit PIN, registers it via Graph API, and provides it back to the client for safekeeping.

Graph API call:

                POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}

                Content-Type: application/json

                Authorization: Bearer {ACCESS_TOKEN}

                { "pin": "XXXXXX" }

What the client receives: Agilezip will provide the configured PIN. Store it securely — it is needed for any future re-registration of the number.

PIN rules: Must be exactly 6 numeric digits. Meta will reject PINs with letters, symbols, or other lengths.

Data Handoff to Agilezip

Send the following data securely to Agilezip to configure Odoo:

Data	Where obtained
App ID	Phase 1, Step 1.2
App Secret	Phase 1, Step 1.2
WABA ID	Phase 1, Step 1.4
Phone Number ID	Phase 4, Step 4.4
Access Token (permanent)	Phase 3, Step 3.3

Recommendation: Send this data through a secure channel (not regular email). Share during a call or through an encrypted channel.

Configure Webhooks

Connect Meta with Odoo to receive incoming messages

Agilezip handles the full webhook configuration. The client does not need to access the Meta Developer Portal for this phase — only the System User credentials from Phase 3 are needed.

AGILEZIPStep 6.1

Get Webhook data from Odoo

After creating the WhatsApp Business Account in Odoo (Phase 7), obtain:

Data	Description	Example
Callback URL	URL where Meta will send events	`https://odoo.mycompany.com/whatsapp/webhook/`
Verify Token	Random token generated by Odoo	`(auto-generated)`

AGILEZIPStep 6.2

Configure Webhook in Meta Developer Portal

Using the client's System User credentials, configure the webhook in the Meta App:

In the Meta App, go to WhatsApp > Configuration
Enter the Callback URL from Odoo
Enter the Verify Token from Odoo
Click Verify and save

Alternative — Graph API: This can also be done via API (see Technical Reference below) using POST /{APP_ID}/subscriptions, which is useful for automation.

AGILEZIPStep 6.3

Subscribe to Webhook events

Activate subscription to the following fields:

Field	Description
`messages`	Incoming messages from clients
`account_update`	Account status updates
`message_template_status_update`	Template approval status changes
`message_template_quality_update`	Template quality changes
`message_template_components_update`	Template component changes

Activate the toggle next to each field in the Webhook fields list.

Configure in Odoo

Agilezip registers the WhatsApp Business API account in the system

AGILEZIPStep 7.1

Register phone number via Graph API

Before configuring Odoo, the phone number must be formally registered with the WhatsApp Cloud API. This step activates message sending/receiving via the API.

Graph API call:

                POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/register

                Content-Type: application/json

                Authorization: Bearer {ACCESS_TOKEN}

                {

                  "messaging_product": "whatsapp",

                  "pin": "XXXXXX"

                }

Note: The PIN used here must match the one set in Phase 5. This call both registers the number for Cloud API use and links the two-step verification PIN.

AGILEZIPStep 7.2

Create WhatsApp Business account in Odoo

Go to WhatsApp > Configuration > WhatsApp Business Accounts
Click New

AGILEZIPStep 7.3

Enter integration data

Odoo Field	Value	Obtained in
Name	Descriptive name	-
App ID `app_uid`	Meta App ID	Phase 1, Step 1.2
App Secret `app_secret`	App Secret	Phase 1, Step 1.2
Account ID `account_uid`	WABA ID	Phase 1, Step 1.4
Phone Number ID `phone_uid`	Registered number ID	Phase 4, Step 4.4
Access Token `token`	Permanent token	Phase 3, Step 3.3

Screenshot: WhatsApp account form in Odoo

AGILEZIPStep 7.4

Sync message templates

Click Sync Templates
Verify approved templates appear in Odoo

Templates must be approved by Meta before they can be used (minutes to 24 hours).

Final Testing

Verify everything works correctly

AGILEZIPStep 8.1

Send test message from Odoo

Go to any contact in Odoo
Use the Send WhatsApp message option
Select an approved template and send

CLIENTStep 8.2

Confirm message receipt

The recipient confirms they received the WhatsApp message correctly, with the expected format and content.

BOTHStep 8.3

Test incoming messages

Send a message to the company's WhatsApp number from a phone
Verify it appears in Discuss in Odoo

Done! The WhatsApp Business API integration with Odoo is fully configured and functional.

IDs and Credentials Summary

Quick reference of all collected values:

Data	Where to get it	Obtained by	Used in
App ID	Meta App > Settings > Basic	Client	Odoo (Agilezip)
App Secret	Meta App > Settings > Basic	Client	Odoo (Agilezip)
WABA ID	Meta App > WhatsApp > API Setup	Client	Odoo (Agilezip)
Phone Number ID	Meta App > WhatsApp > API Setup	Client	Odoo (Agilezip)
PIN	Generated by Agilezip via Graph API	Agilezip	Graph API Registration + provided to Client
Access Token	Meta Business Suite > System Users	Client	Odoo (Agilezip)
Callback URL	Odoo > WhatsApp Account	Agilezip	Meta Webhook (Client)
Verify Token	Odoo > WhatsApp Account	Agilezip	Meta Webhook (Client)

Agilezip Technical Reference — Graph API Calls

Internal reference for Agilezip engineers and AI agents executing this integration. All calls use the Meta Graph API v21.0 with the permanent Access Token from Phase 3.

1. Register Phone Number

Activates the phone for WhatsApp Cloud API messaging. Must be called after the number is added and verified in the Meta Developer Portal (Phase 4).

              POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/register

              Authorization: Bearer {ACCESS_TOKEN}

              Content-Type: application/json

              {

                "messaging_product": "whatsapp",

                "pin": "XXXXXX"

              }

Expected response: { "success": true }

2. Set / Update Two-Step Verification PIN

Sets or updates the 6-digit PIN independently. Can be called after registration if the PIN needs to be changed.

              POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}

              Authorization: Bearer {ACCESS_TOKEN}

              Content-Type: application/json

              { "pin": "XXXXXX" }

Expected response: { "success": true }

3. Subscribe to Webhooks (API alternative)

Webhook subscription can be done via the Meta Developer Portal UI (Phase 6) or programmatically via Graph API. The API approach is useful for automation.

              POST https://graph.facebook.com/v21.0/{APP_ID}/subscriptions

              Authorization: Bearer {ACCESS_TOKEN}

              Content-Type: application/json

              {

                "object": "whatsapp_business_account",

                "callback_url": "https://odoo.client.com/whatsapp/webhook/",

                "verify_token": "{ODOO_VERIFY_TOKEN}",

                "fields": "messages"

              }

Expected response: { "success": true }

Note: The verify_token is the token generated by Odoo in the WhatsApp Business Account configuration. The callback_url is the Odoo instance's webhook endpoint.

4. Verify Phone Number Status

Check current registration and quality status of the phone number.

              GET https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}?fields=verified_name,quality_rating,status,display_phone_number

              Authorization: Bearer {ACCESS_TOKEN}

5. Send Test Message

Quick test to verify the API is working before configuring Odoo. Uses the default hello_world template.

              POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages

              Authorization: Bearer {ACCESS_TOKEN}

              Content-Type: application/json

              {

                "messaging_product": "whatsapp",

                "to": "521234567890",

                "type": "template",

                "template": { "name": "hello_world", "language": { "code": "en_US" } }

              }

Full API reference: All endpoints documented at https://developers.facebook.com/docs/whatsapp/cloud-api/reference