Overview
KAIU Natural Living integrates with WhatsApp Cloud API to provide automated customer support powered by Anthropic Claude AI. The system handles:- Automated product inquiries and recommendations
- Intelligent handover to human agents
- Session management with conversation history
- PII filtering for privacy compliance
- Real-time dashboard notifications
Architecture
Prerequisites
- Meta Business Account
- Facebook App with WhatsApp product
- Public HTTPS URL for webhook (use ngrok for development)
- Phone number verified with Meta
Setup Steps
Create Meta App
Go to Meta Developers
Navigate to Meta for Developers and log in.
Get API Credentials
From the WhatsApp > API Setup page, collect:Found under “Phone number ID” in the API Setup tab.To create a permanent token:Found under Settings > Basic in your Meta App dashboard.
Phone Number ID
Access Token
- Go to Business Settings > System Users
- Create a system user
- Assign WhatsApp permissions
- Generate token (never expires)
App Secret
Configure Webhook
Set Up Tunnel (Development)
https://abc123.ngrok.io).Create Verify Token
Generate a random string for webhook verification:.env.local:Register Webhook in Meta
- Go to WhatsApp > Configuration in Meta App dashboard
- Click Edit next to Webhook
- Enter:
- Callback URL:
https://your-domain.com/api/whatsapp/webhook - Verify Token: The token you generated above
- Callback URL:
- Click Verify and Save
The webhook handler in
backend/whatsapp/webhook.js:52-68 validates this token.Subscribe to Messages
- In the Webhook section, click Manage
- Subscribe to messages webhook field
- Click Save
Implementation Details
Webhook Handler
The webhook is implemented inbackend/whatsapp/webhook.js:
Signature Validation
Meta signs all webhook requests with
X-Hub-Signature-256 header for security.backend/whatsapp/webhook.js:12-49
Message Processing
Messages are processed asynchronously by the BullMQ worker inbackend/whatsapp/queue.js:35-201:
Features
Intelligent Handover
The system automatically transfers to human agents when it detects keywords:backend/whatsapp/queue.js:86
Customize handover keywords in
backend/whatsapp/queue.js:86 to match your language and business needs.PII Filtering
Personally Identifiable Information is redacted before storing in conversation history:backend/utils/pii-filter.js
Session Management
Sessions expire after 24 hours (Meta’s conversation window):Real-time Dashboard Updates
Socket.IO events notify the dashboard of new messages:backend/whatsapp/queue.js:74-80
Testing
Production Deployment
Permanent Token
Create a System User token in Meta Business Settings that never expires
HTTPS Required
Meta requires HTTPS for webhook URLs. Use Let’s Encrypt or your hosting provider’s SSL
Monitor Rate Limits
WhatsApp Cloud API has rate limits. Configure BullMQ limiter accordingly
Backup Strategy
Session data and conversation history are stored in PostgreSQL for recovery
Environment Variables for Production
Troubleshooting
Webhook Verification Fails
Webhook Verification Fails
Error:
403 Forbidden when setting up webhookSolution:- Check
WHATSAPP_VERIFY_TOKENmatches exactly in both Meta dashboard and.env.local - Ensure webhook URL is accessible:
curl https://your-url/api/whatsapp/webhook - Check server logs for verification attempt
Messages Not Received
Messages Not Received
Error: Webhook registered but no messages arriveSolution:
- Check webhook subscriptions include “messages” field
- Verify phone number is added to WhatsApp Business Account
- Test webhook manually with curl
- Check ngrok is still running (URLs change on restart)
Signature Validation Errors
Signature Validation Errors
Error:
Invalid Signature in logsSolution:- Verify
WHATSAPP_APP_SECRETis correct - Ensure
express.json()includesverifycallback inserver.mjs:61: - Check
X-Hub-Signature-256header is present in request
AI Responses Not Sending
AI Responses Not Sending
Error: Jobs complete but customer doesn’t receive replySolution:
- Check
WHATSAPP_ACCESS_TOKENis valid and not expired - Verify
WHATSAPP_PHONE_IDis correct - Check rate limits:
curl https://graph.facebook.com/v21.0/me -H "Authorization: Bearer $TOKEN" - Review API response in worker logs for error details
Handover Not Working
Handover Not Working
Error: Bot continues responding after customer requests humanSolution:
- Check handover keywords match your language in
queue.js:86 - Verify session
isBotActiveis set tofalsein database - Ensure dashboard is receiving Socket.IO events
- Test with exact keyword: “quiero hablar con un humano”
Next Steps
AI Configuration
Configure RAG and knowledge base for intelligent responses
Dashboard
Monitor conversations and manage handovers