modbender WhatsApp Business API
Official Meta Cloud API integration. See auxiliary files for detailed operations.
Quick Start
curl -X POST "https://graph.facebook.com/v21.0/$WHATSAPP_PHONE_NUMBER_ID/messages" \
-H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"messaging_product":"whatsapp","to":"1234567890","type":"text","text":{"body":"Hello!"}}'
Setup
On first use, read setup.md. Preferences stored in ~/whatsapp-business-api/memory.md.
When to Use
Any WhatsApp Business operation: send messages, templates, media, interactive elements, manage webhooks, handle conversations, update business profiles.
Architecture
~/whatsapp-business-api/
├── memory.md # Account context + phone numbers
├── templates.md # Approved templates reference
└── webhooks.md # Webhook configurations
Quick Reference
| Topic | File |
|---|---|
| Setup & memory | setup.md, memory-template.md |
| Messages (text, media, interactive) | messages.md |
| Templates (create, manage, send) | templates.md |
| Media (upload, download, manage) | media.md |
| Webhooks & Events | webhooks.md |
| Business Profile & Phone Numbers | business.md |
| Flows (interactive forms) | flows.md |
| Best practices & limits | best-practices.md |
Core Rules
- International format — Phone numbers without
+or leading zeros:1234567890 - 24-hour window — Free replies within 24h of customer message; templates required to initiate
- Template approval — Templates need Meta approval (24-48h); test in sandbox first
- Idempotency — Use
biz_opaque_callback_datato track message state - Webhook verification — Always verify webhook signature with app secret
- Rate limits — 80 messages/second per phone number; 1000 template messages/day (tier 1)
- Media limits — Images <5MB, videos <16MB, documents <100MB
Authentication
Required environment variables:
WHATSAPP_ACCESS_TOKEN— System User access token (permanent) or User access token (60-day)WHATSAPP_PHONE_NUMBER_ID— Your registered phone number IDWHATSAPP_BUSINESS_ACCOUNT_ID— Your WABA ID (for templates)WHATSAPP_APP_SECRET— App secret for webhook verification
curl "https://graph.facebook.com/v21.0/$WHATSAPP_PHONE_NUMBER_ID" \
-H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"
Token Types
| Type | Duration | Use Case |
|---|---|---|
| System User Token | Permanent | Production apps |
| User Token | 60 days | Development, testing |
| Temporary Token | 24 hours | Quick tests |
Common Traps
- Phone format with
+or00→ API rejects - Missing
messaging_product: "whatsapp"→ 400 error - Template not approved → message fails silently
- Webhook signature not verified → security vulnerability
- Sending outside 24h window without template → blocked
External Endpoints
| Endpoint | Purpose |
|---|---|
https://graph.facebook.com/v21.0/* |
Cloud API |
Security & Privacy
Environment variables used:
WHATSAPP_ACCESS_TOKEN— for API authenticationWHATSAPP_APP_SECRET— for webhook signature verification
Sent to Meta: Messages, media, customer phone numbers via graph.facebook.com Stays local: Tokens (never logged), ~/whatsapp-business-api/ preferences Never: Log message content, skip webhook verification, store tokens in code
Trust
This skill sends data to Meta (facebook.com/whatsapp).
Related Skills
Install with clawhub install <slug> if user confirms:
api— REST API patternswebhook— Webhook handlingchat— Conversational patterns
Feedback
- If useful:
clawhub star whatsapp-business-api - Stay updated:
clawhub sync