BF WABA Expert (bf-waba-expert)

Meta WhatsApp Cloud API (WABA) Senior Integration Expert
Direct Graph API v26.0 (Zero BSP, Zero MCP middleman). Built by BF Labs AI.

Install directly to Claude Code, Cursor, Windsurf, or any compatible agent harness:

# Install globally to all supported agents:
npx skills add BFLabsAI/bf-waba-expert -g

# Or install specifically to Claude Code:
npx skills add https://github.com/BFLabsAI/bf-waba-expert --agent claude-code

# Clone to your agents skills directory:
git clone https://github.com/BFLabsAI/bf-waba-expert.git ~/.agents/skills/bf-waba-expert

# Link to Claude Code:
ln -sfn ~/.agents/skills/bf-waba-expert ~/.claude/skills/bf-waba-expert

# Link to Hermes:
ln -sfn ~/.agents/skills/bf-waba-expert ~/.hermes/skills/bf-waba-expert

# Link to OMP:
mkdir -p ~/.omp/skills && ln -sfn ~/.agents/skills/bf-waba-expert ~/.omp/skills/bf-waba-expert

bf-waba-expert is a complete engineering and operational doctrine for building production bots and enterprise WhatsApp integrations on Meta's WhatsApp Cloud API (Graph API v26.0) directly.

• Zero Third-Party Dependency: Direct communication with graph.facebook.com. No dependency on BSPs (Twilio, Zenvia, Wassenger) or MCP tools.
• Full Messaging Types: Text, media (image, audio/PTT voice notes, video, document), interactive buttons (max 3), interactive lists (max 10), CTA URLs, native WhatsApp Flows (Flow JSON 7.3), reactions, location, and contacts cards.
• Enterprise Webhook Pipeline:
  • GET handshake validation with Reflected-XSS defense (text/plain content type and regex validation).
  • POST signature verification using HMAC-SHA256 (X-Hub-Signature-256) with constant-time equality checks.
  • Delivery receipt lifecycle (sent, delivered, read, failed).
  • Idempotency & deduplication patterns.
• Resolution of the 3 Silent Failure Modes: In WhatsApp Cloud API, misconfigurations fail with silence rather than errors. This skill provides explicit detection and auto-repair.
• Automated Diagnostic & Repair Script: Standalone Python script (scripts/diagnose.py) with --fix flag.
• Production Boilerplates: Ready-to-run microservices in Node.js (TypeScript) and Python (FastAPI/httpx).

1. WABA Not Subscribed to the App:
   • Meta requires explicitly subscribing the WABA to your App ID. Without this, webhook pings from the dashboard work, but real customer messages are dropped silently.
   • Auto-fix: python scripts/diagnose.py --fix
2. Webhook Field Subscriptions Missing:
   • The app must be subscribed to messages and smb_message_echoes. Editing the webhook URL in Meta Dashboard frequently unchecks these fields silently.
   • Auto-fix: python scripts/diagnose.py --fix
3. Token Expiration & Missing Asset Assignment:
   • System User Tokens require assigning the WABA asset to the System User under Business Settings, in addition to permissions whatsapp_business_messaging and whatsapp_business_management.

bf-waba-expert/
├── SKILL.md                          # Main agent instructions (< 400 lines)
├── README.md                         # Documentation & installation guide
├── package.json                      # Metadata for npx skills & npm
├── LICENSE                           # MIT License
├── .env.example                      # Sample configuration
├── references/                       # In-depth architectural guides
│   ├── api-reference-v26.md          # Endpoints, tokens, rate limits, pricing
│   ├── messaging-types.md            # Exact JSON schemas for all message types
│   ├── templates-and-lifecycle.md    # Template creation, approval, and 24h window
│   ├── webhooks-and-security.md      # HMAC-SHA256, payload parsing, deduplication
│   ├── troubleshooting-and-diagnostics.md # Silent failures & error codes
│   └── coexistence-and-compliance.md # Mobile App + Cloud API coexistence
├── scripts/                          # Diagnostic and management scripts
│   ├── diagnose.py                   # Diagnostic engine with --fix
│   ├── send_test_message.py          # Message testing utility
│   ├── validate_config.py            # Environment auditing
│   └── setup_project.py              # Microservice scaffolding
└── assets/
    └── boilerplate/                  # Production boilerplate code
        ├── nodejs/                   # Express + TypeScript + typed client
        └── python/                   # FastAPI + httpx async + typed client

• Constant-Time HMAC Comparison: Prevents timing attacks on webhook signature validation.
• Reflected-XSS Defense: Webhook verification challenges are returned strictly as text/plain.
• Log Sanitization: Bearer tokens and unmasked phone numbers are never printed in plaintext to application logs.

MIT © BF Labs AI.