Overview

WhatsApp Business API Authentication connects your Cloud-PBX to WhatsApp's messaging platform using Meta (Facebook) Business credentials.

Requirements:

• Facebook Business Manager account
• Verified business
• WhatsApp Business API access
• Dedicated phone number
• Webhook endpoint

---

Configuration Steps

---

Webhook Configuration

Cloud-PBX Webhook URL:

https://your-pbx-domain.com/api/messaging/whatsapp/webhook

Webhook Events:

• messages: Incoming text, media, location, contact
• message_status: sent, delivered, read, failed
• message_template_status_update: approved, rejected

Webhook Payload Example:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "15551234567",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "messages": [{
          "from": "15559876543",
          "id": "wamid.XXX",
          "timestamp": "1634567890",
          "type": "text",
          "text": {
            "body": "Hello, I need help with my order"
          }
        }]
      }
    }]
  }]
}

---

Security Best Practices

Access Token Security:

• Use permanent system user tokens (not temporary)
• Store securely (encrypted)
• Never commit to version control
• Rotate tokens every 90 days
• Limit token permissions to minimum required
• Use separate tokens for dev/staging/production

Webhook Security:

• Validate webhook signatures (SHA-256)
• Use HTTPS only
• Verify requests from WhatsApp IPs only
• Implement rate limiting
• Log all webhook activity
• Monitor for suspicious patterns

Phone Number Security:

• Don't share phone number publicly initially
• Monitor for spam/abuse
• Enable two-factor authentication
• Restrict admin access
• Review usage regularly

---

Troubleshooting

Business Verification Rejected:

• Provide clearer business documents
• Ensure business name matches documents
• Verify business address and phone
• Check website/social media presence
• Resubmit with corrections

Phone Number Verification Fails:

• Number not on personal WhatsApp
• Number can receive SMS/calls
• Correct country code format (+1...)
• Not previously banned
• Try different verification method (SMS vs voice)

Webhook Not Receiving Messages:

• Verify URL publicly accessible (HTTPS)
• Check SSL certificate valid
• Review firewall rules (allow WhatsApp IPs)
• Test webhook with curl/Postman
• Verify webhook subscribed to "messages" event
• Check verify token matches

API Connection Fails:

• Verify all credentials correct
• Check access token permissions
• Confirm WhatsApp Business Account ID accurate
• Ensure API access approved
• Review Meta Business Manager status

---

Migration Notes

From WhatsApp Business App:

• API uses different phone number
• Can't migrate app number directly without losing history
• Export contacts manually
• Notify customers of new number
• Gradually transition

Provider Migration (e.g., from Twilio to Meta directly):

• Set up new Meta Business Manager
• Register new phone number
• Update authentication in Cloud-PBX
• Test thoroughly before switching
• Update templates with new number
• Notify customers if number changes

---

Next Steps

1. Configure Settings: Set up business profile, templates in WhatsApp Settings
2. Create Templates: Build message templates for notifications
3. Configure Routing: Route WhatsApp messages to queues in Message Queues
4. Train Team: Familiarize agents with WhatsApp features
5. Launch: Start customer conversations