whatshooked/WHATSAPP_BUSINESS.md

WhatsApp Business API Setup Guide

This guide will help you set up WhatsApp Business API credentials for use with WhatsHooked.

Common Error: "Object does not exist or missing permissions"

If you see this error:

Failed to connect client account_id=test error="API returned status 400:
{\"error\":{\"message\":\"Unsupported get request. Object with ID 'XXXXXXXXX' does not exist,
cannot be loaded due to missing permissions, or does not support this operation...\",
\"type\":\"GraphMethodException\",\"code\":100,\"error_subcode\":33...}}"

This means your access token lacks the required WhatsApp Business API permissions.

Prerequisites

Before you begin, ensure you have:

1. A Meta Business Account
2. WhatsApp Business API access (approved by Meta)
3. A verified WhatsApp Business phone number
4. Admin access to your Meta Business Manager

Step 1: Access Meta Business Manager

1. Go to Meta Business Manager
2. Select your business account
3. Navigate to Business Settings (gear icon)

Step 2: Create a System User (Recommended for Production)

System Users provide permanent access tokens that don't expire with user sessions.

1. In Business Settings, go to Users → System Users
2. Click Add to create a new system user
3. Enter a name (e.g., "WhatsHooked API Access")
4. Select Admin role
5. Click Create System User

Step 3: Assign the System User to WhatsApp

1. In the System User details, scroll to Assign Assets
2. Click Add Assets
3. Select Apps
4. Choose your WhatsApp Business app
5. Grant Full Control
6. Click Add People
7. Select WhatsApp Accounts
8. Choose your WhatsApp Business Account
9. Grant Full Control
10. Click Save Changes

Step 4: Generate Access Token with Required Permissions

1. In the System User details, click Generate New Token
2. Select your app from the dropdown
3. IMPORTANT: Check these permissions:
   • ✅ whatsapp_business_management
   • ✅ whatsapp_business_messaging
4. Set token expiration (choose "Never" for permanent tokens)
5. Click Generate Token
6. CRITICAL: Copy the token immediately - you won't see it again!

Verify Token Permissions

You can verify your token has the correct permissions:

# Replace YOUR_TOKEN with your actual access token
curl -X GET 'https://graph.facebook.com/v21.0/debug_token?input_token=YOUR_TOKEN' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Look for "scopes" in the response - it should include:

{
  "data": {
    "scopes": [
      "whatsapp_business_management",
      "whatsapp_business_messaging",
      ...
    ]
  }
}

Step 5: Get Your Phone Number ID

The Phone Number ID is NOT your actual phone number - it's a unique identifier from Meta.

Method 1: Via WhatsApp Manager (Easiest)

1. Go to WhatsApp Manager
2. Select your WhatsApp Business Account
3. Click API Setup in the left sidebar
4. Copy the Phone Number ID (looks like: 123456789012345)

Method 2: Via API

# Replace YOUR_TOKEN and YOUR_BUSINESS_ACCOUNT_ID
curl -X GET 'https://graph.facebook.com/v21.0/YOUR_BUSINESS_ACCOUNT_ID/phone_numbers' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response:

{
  "data": [
    {
      "verified_name": "Your Business Name",
      "display_phone_number": "+1 234-567-8900",
      "id": "123456789012345",  // <- This is your Phone Number ID
      "quality_rating": "GREEN"
    }
  ]
}

Step 6: Get Your Business Account ID (Optional)

# Get all WhatsApp Business Accounts you have access to
curl -X GET 'https://graph.facebook.com/v21.0/me/businesses' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Or find it in WhatsApp Manager:

1. Go to WhatsApp Manager
2. Click on Settings (gear icon)
3. The Business Account ID is shown in the URL: https://business.facebook.com/wa/manage/home/?waba_id=XXXXXXXXX

Step 7: Test Your Credentials

Before configuring WhatsHooked, test your credentials:

# Replace PHONE_NUMBER_ID and YOUR_TOKEN
curl -X GET 'https://graph.facebook.com/v21.0/PHONE_NUMBER_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'

If successful, you'll get a response like:

{
  "verified_name": "Your Business Name",
  "display_phone_number": "+1 234-567-8900",
  "id": "123456789012345",
  "quality_rating": "GREEN"
}

If you get an error like "error_subcode":33, your token lacks permissions - go back to Step 4.

Step 8: Configure WhatsHooked

Update your config.json with the Business API configuration:

{
  "whatsapp": [
    {
      "id": "business",
      "type": "business-api",
      "phone_number": "+1234567890",
      "business_api": {
        "phone_number_id": "123456789012345",
        "access_token": "EAAxxxxxxxxxxxx_your_permanent_token_here",
        "business_account_id": "987654321098765",
        "api_version": "v21.0"
      }
    }
  ]
}

Configuration Fields

Field	Required	Description
id	Yes	Unique identifier for this account in WhatsHooked
type	Yes	Must be "business-api"
phone_number	Yes	Your WhatsApp Business phone number (E.164 format)
phone_number_id	Yes	Phone Number ID from Meta (from Step 5)
access_token	Yes	Permanent access token (from Step 4)
business_account_id	No	WhatsApp Business Account ID (optional, for reference)
api_version	No	Graph API version (defaults to "v21.0")

Step 9: Start WhatsHooked

./bin/whatshook-server -config config.json

You should see:

INFO Business API client connected account_id=business phone=+1234567890

If you see Failed to connect client, check the error message and verify:

1. Phone Number ID is correct
2. Access token has required permissions
3. Access token hasn't expired
4. Business Account has WhatsApp API access enabled

Troubleshooting

Error: "Object with ID does not exist" (error_subcode: 33)

Cause: One of the following:

• Incorrect Phone Number ID
• Access token lacks permissions
• Access token expired

Fix:

1. Verify token permissions (see Step 4)
2. Double-check Phone Number ID (see Step 5)
3. Generate a new token if needed

Error: "Invalid OAuth access token"

Cause: Token is invalid or expired

Fix: Generate a new access token (Step 4)

Error: "Application does not have permission"

Cause: App not added to WhatsApp Business Account

Fix: Complete Step 3 to assign System User to WhatsApp

Token Expires Too Quickly

Issue: Using a User Access Token instead of System User token

Fix:

• Use a System User (Step 2) for permanent tokens
• User Access Tokens expire in 60 days
• System User tokens can be set to "Never expire"

Security Best Practices

1. Never commit tokens to version control

   • Add config.json to .gitignore
   • Use environment variables for sensitive data

2. Rotate tokens regularly

   • Even "permanent" tokens should be rotated periodically
   • Revoke old tokens when generating new ones

3. Use System Users for production

   • Don't use personal User Access Tokens
   • System Users provide better security and permanence

4. Limit token permissions

   • Only grant the minimum required permissions
   • For WhatsHooked, you only need:
     • whatsapp_business_management
     • whatsapp_business_messaging

5. Monitor token usage

   • Check token status regularly via debug_token endpoint
   • Watch for unexpected API calls

Additional Resources

• WhatsApp Business Platform Documentation
• Graph API Reference
• System Users Guide
• WhatsApp Business API Getting Started

Support

If you continue to have issues:

1. Verify your Meta Business Account has WhatsApp API access
2. Check that your phone number is verified in WhatsApp Manager
3. Ensure you're using Graph API v21.0 or later
4. Review the WhatsApp Business API changelog for updates