WhatsApp Cloud API - Phone Number Setup Guide

team uncategorized v1

WhatsApp Cloud API - Phone Number Setup Guide

Guide for registering a new WhatsApp Business phone number with Cloud API.

Overview

PhaseWhoWhat
1. PrerequisitesHuman/CometMeta Business verification, app setup
2. Add NumberHumanAdd phone number in Meta console
3. Get CredentialsHuman/CometCopy IDs and generate token
4. RegisterAI (CLI)API call with certificate
5. Webhook SetupHuman/Comet + AIConfigure webhook and subscribe WABA

AI Agent Notes (Comet / browser agents):

  • Do NOT read tokens, secrets, or IDs from screenshots. You WILL get them wrong.
  • Instead, tell the human exactly what button to click to copy-paste the value.
  • Tokens are ~200 characters. If yours is shorter, it’s truncated.
  • The App must be in the SAME business portfolio as the phone number’s WABA. If the number is in Business A but your app is in Business B, system users in Business A won’t see your app when generating tokens. Create the app under Business A instead.

Phase 1: Prerequisites (Human/Comet)

1.1 Meta Business Account

1.2 Meta App with WhatsApp

1.3 Business Portfolio Check

Before proceeding, verify:

Phase 2: Add Phone Number (Human)

2.1 Add the Number

  1. Go to WhatsApp Manager
  2. Click Add Phone Number
  3. Enter phone number (must NOT be linked to any WhatsApp account)
  4. Choose verification method: SMS or Voice call
  5. Enter the verification code

2.2 Set Display Name

  1. Enter your business display name
  2. Wait for approval (usually instant for compliant names)

2.3 Download Certificate

After display name is approved:

  1. Go to your phone number settings in WhatsApp Manager
  2. Find the Certificate section
  3. Copy the base64-encoded certificate string

It looks like this:

CmUKIQik06fWvoL2AhIGZW50OndhIghCaWxpbyBBSVD7/7nLBhpA...

Phase 3: Get Credentials (Human/Comet)

Comet note: For each value below, tell the human exactly which button to click to copy. Do NOT attempt to OCR values from screenshots.

3.1 Get Phone Number ID

  1. Go to Meta for Developers → your app
  2. WhatsApp → API Setup
  3. In the “From” dropdown, select the target phone number
  4. Copy the Phone Number ID shown below the dropdown

3.2 Get App Secret

  1. Go to your app’s Settings → Basic
  2. Find “App secret”, click “Show” (will ask for Facebook password)
  3. Copy the App Secret (32 hex characters)

3.3 Generate Permanent Access Token

  1. Go to Business Settings > System Users
  2. Create a new System User (or use existing):
    • Name: descriptive (e.g., “Notaria Bot”)
    • Role: Admin
  3. Add Assets to the System User:
    • Apps → select your app → Full Control
    • WhatsApp Accounts → select the WABA → Full Control
  4. Click Generate New Token:
    • Select your app
    • Token expiration: Never
    • Enable permissions:
      • whatsapp_business_messaging
      • whatsapp_business_management
  5. Copy the token (starts with EAA..., ~200 characters)

Comet note: The token is LONG (~200 chars). If you read it from a screenshot you WILL truncate it. Tell the human to click the copy button or manually select-all and copy from the text field.

3.4 Get WABA ID

  1. Go to WhatsApp Manager
  2. Look at the URL: ?asset_id=XXXXXXXXXX ← this is your WABA ID
  3. Or find it in Account tools → Phone numbers

3.5 Output Format

Collect all values in this format:

WHATSAPP_APP_ID=your_app_id
WHATSAPP_APP_SECRET=your_app_secret
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_ACCESS_TOKEN=your_permanent_token
WHATSAPP_VERIFY_TOKEN=your_custom_verify_token
WABA_ID=your_waba_id

Phase 4: Register via API (AI - CLI agent)

Once you have all credentials, tell the AI:

“Register my WhatsApp number. Certificate: [paste certificate]“

What the AI does:

Step 1: Verify token works

curl -s "https://graph.facebook.com/v21.0/${PHONE_NUMBER_ID}?fields=display_phone_number,verified_name,status" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Expected: Status should be PENDING

Step 2: Register with certificate

curl -s -X POST "https://graph.facebook.com/v21.0/${PHONE_NUMBER_ID}/register" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "pin": "123456",
    "certificate": "YOUR_CERTIFICATE_HERE"
  }'

Expected: {"success": true}

Step 3: Verify registration

curl -s "https://graph.facebook.com/v21.0/${PHONE_NUMBER_ID}?fields=display_phone_number,verified_name,status,messaging_limit_tier" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Expected: Status should be CONNECTED

Phase 5: Webhook Setup (CRITICAL)

5.1 Configure Webhook URL (Human/Comet)

  1. Go to Meta for Developers → your app
  2. WhatsApp → Configuration
  3. In Webhook section, click Edit
  4. Enter:
    • Callback URL: https://your-domain.com/webhook (your public server URL)
    • Verify Token: same as WHATSAPP_VERIFY_TOKEN in .env
  5. Click Verify and Save

5.2 Subscribe to Messages Field (Human/Comet)

  1. In the same Configuration page
  2. Under Webhook fields, click Manage
  3. Enable (subscribe) the messages field
  4. Click Done

5.3 Enable Live Mode (Human/Comet)

  1. Go to App Settings → Basic
  2. Add Privacy Policy URL (required for Live mode)
  3. Toggle App Mode from “Development” to “Live”

5.4 Subscribe App to WABA (AI) - CRITICAL!

This step is often missed and causes webhooks to not arrive.

curl -s -X POST "https://graph.facebook.com/v21.0/${WABA_ID}/subscribed_apps" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Expected: {"success": true}

Verify subscription:

curl -s "https://graph.facebook.com/v21.0/${WABA_ID}/subscribed_apps" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Should show your app in the list.

5.5 Test Webhook

  1. In Meta Dashboard, go to WhatsApp → Configuration → Webhook
  2. Click Test next to the messages field
  3. Click Send to My Server
  4. Check your server logs for the incoming webhook

Quick Reference

What to give the CLI AI:

  1. Phone Number ID: from API Setup
  2. Certificate: base64 string from WhatsApp Manager
  3. WABA ID: from WhatsApp Manager URL
  4. All .env credentials confirmed

PIN

The AI will set PIN to 123456 by default. This is your WhatsApp 2-step verification PIN. Remember it or change it later in WhatsApp Manager.

Troubleshooting

Error: “Malformed access token”

Error: “Object does not exist or missing permissions”

Error: “Invalid certificate”

Status stuck on PENDING

Webhooks not arriving (Test works, real messages don’t)

This is the most common issue!

  1. Check App Mode: Must be “Live”, not “Development”
  2. Check WABA subscription: Run the subscribe API call: 
    curl -X POST "https://graph.facebook.com/v21.0/${WABA_ID}/subscribed_apps" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
  3. Check App Secret: The WHATSAPP_WEBHOOK_SECRET must match the App Secret from the correct app

Invalid webhook signature (403 error)

Business portfolio mismatch

Post-Registration

After CONNECTED status and webhook working:

  1. Test sending a message (to your own number first)
  2. Test receiving a message (reply and check logs)
  3. Create message templates for business-initiated conversations

Messaging Limits

Environment Variables Reference

# Required for WhatsApp integration
WHATSAPP_PHONE_NUMBER_ID=922407610962121      # From API Setup
WHATSAPP_ACCESS_TOKEN=EAA...                   # Permanent token from System User
WHATSAPP_VERIFY_TOKEN=YourCustomToken          # For webhook verification
WHATSAPP_APP_SECRET=abc123...                  # From App Settings > Basic
WHATSAPP_APP_ID=1587604912547962               # From App Settings > Basic
WHATSAPP_WEBHOOK_SECRET=abc123...              # Same as APP_SECRET
WABA_ID=370807332792746                        # From WhatsApp Manager URL