Bf Waba Expert

BF WABA Expert (WhatsApp Cloud API)

Direct, production-grade integration and diagnostics for Meta's WhatsApp Cloud API (Graph API v26.0). Zero intermediary BSPs (no Twilio, Zenvia, Wassenger) and zero MCP dependencies.

When to Use

Activate this skill whenever:

• Implementing, reviewing, or fixing WhatsApp Cloud API direct integrations (graph.facebook.com).
• Sending messages: text, media (image, audio, video, document), interactive (buttons, list, catalog, CTA), location, contacts, reactions, or templates.
• Configuring webhooks: GET verification handshake, POST payload parsing, HMAC-SHA256 signature verification, and delivery/read/failed status processing.
• Investigating silent delivery failures: webhook returns 200 OK or panel shows "connected successfully" but customer messages never arrive.
• Managing WhatsApp Business Accounts (WABA): System User Tokens, phone number registration, 2-step verification, display names, and Coexistence (App + Cloud API on same number).
• Working with message templates (marketing, utility, authentication), variable mapping, and the 24-hour service window.
• Scaffolding or debugging backend implementations in Node.js (TypeScript) or Python (FastAPI/httpx).

Quick Reference (Graph API v26.0)

Core Operational Law: The 3 Silent Failure Modes

In Meta's Cloud API, the default failure mode is silence. No error is returned, the developer dashboard shows green checks, test webhooks succeed, yet customer messages never arrive. Always check these three invisible steps:

1. WABA Not Subscribed to the App:
   • Meta requires explicitly binding the WABA to your App ID. Without this, webhook pings from the dashboard work, but real customer messages are dropped silently.
   • Fix: POST https://graph.facebook.com/v26.0/{WABA_ID}/subscribed_apps
2. Webhook Field Subscriptions Missing:
   • The app must subscribe specifically to the messages and smb_message_echoes fields under whatsapp_business_account. Updating your webhook URL in Meta Dashboard frequently unchecks these fields silently!
   • Fix: POST https://graph.facebook.com/v26.0/{APP_ID}/subscriptions?object=whatsapp_business_account&fields=messages,smb_message_echoes (requires App Access Token {app_id}|{app_secret}).
3. Token Expiration & Missing Asset Assignment:
   • Temporary dashboard tokens expire after 24h. Production requires a Permanent System User Token.
   • Simply having the permissions whatsapp_business_messaging and whatsapp_business_management is not enough: the WABA asset must be explicitly assigned to the System User in Business Manager (business.facebook.com → Accounts → WhatsApp Accounts → Assign People / System Users).

Automated Healing with diagnose.py

Run the bundled diagnostic script to identify and automatically repair these issues:

# Inspection & report only:
python scripts/diagnose.py

# Automatically subscribe WABA and webhook fields:
python scripts/diagnose.py --fix

Architecture & Workflows

1. Inbound Webhook Pipeline

A production webhook server must execute three steps in strict order:

Meta GET Handshake  ──► Verify hub.verify_token ──► Return hub.challenge as text/plain (200 OK)
Meta POST Event     ──► Compute HMAC-SHA256 (raw body) ──► Constant-time compare X-Hub-Signature-256
                    ──► Return 200 OK immediately (<3s) ──► Dispatch payload to async worker/queue

Security Invariants:

• Reflected XSS Prevention: Always respond to hub.challenge with Content-Type: text/plain and validate challenge character set (^[A-Za-z0-9_\-]+$).
• Timing Attacks: Validate signatures using constant-time comparison (crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python).
• Fast Ack (<3s): Meta retries exponentially if your webhook takes longer than 3 seconds. Return 200 OK before heavy business logic or AI processing.
• Idempotency: WhatsApp webhooks may retry delivery. Deduplicate incoming events by entry[].changes[].value.messages[].id.

2. Outbound Messaging Pipeline

All messages use POST /{phone-number-id}/messages.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "text",
  "text": { "body": "Olá! Como posso ajudar?", "preview_url": false }
}

• Session Window (24h): Free-form messages (text, media, interactive, audio, location) can only be sent within 24 hours of the user's last inbound message.
• Outside 24h Window: You must use an approved Meta Message Template (type: "template"). Sending free-form text outside the window returns error 131047 (Re-engagement message).
• Mark as Read: Always acknowledge customer messages to display blue double ticks: POST /{phone-number-id}/messages with {"messaging_product": "whatsapp", "status": "read", "message_id": "<ID>"}.

Message Types Quick Guide

Full payload schemas and examples available in references/messaging-types.md.

Troubleshooting & Error Taxonomy

Full error catalog and field diagnoses in references/troubleshooting-and-diagnostics.md.

Bundled Tools & Scripts

The skill provides production utilities in the scripts/ directory:

1. scripts/diagnose.py: Full diagnostic and auto-repair utility.
   • Inspects access token validity, expiration, and scopes.
   • Verifies phone number display status and verified name.
   • Queries and binds WABA app subscription (--fix).
   • Checks and registers webhook field subscriptions (--fix).
   • Simulates external Meta GET handshake test.
2. scripts/send_test_message.py: Validates outbound message delivery with E.164 sanitization.
3. scripts/validate_config.py: Audits local .env configuration.
4. scripts/setup_project.py: Scaffolds a full Node.js or Python WhatsApp Cloud API microservice with secure webhooks and typed clients.

Project Boilerplates

Pre-configured boilerplates ready to drop into projects:

• Node.js (TypeScript): assets/boilerplate/nodejs/
  • Express server with raw-body HMAC validation middleware.
  • Complete TypeScript types for all incoming/outgoing payloads.
  • Typed WhatsAppClient with automatic retries and exponential backoff.
• Python (FastAPI): assets/boilerplate/python/
  • FastAPI server with async httpx client.
  • HMAC-SHA256 request validator decorator.
  • Template manager and media upload/download utilities.

Detailed References

For deep-dive documentation, consult the files in references/:

• references/api-reference-v26.md — Endpoints, auth tokens, headers, rate limits, and pricing.
• references/messaging-types.md — Exact JSON payload specifications for every message type.
• references/webhooks-and-security.md — HMAC validation, signature headers, payload models, and deduplication.
• references/templates-and-lifecycle.md — Template creation, approval guidelines, and parameter mapping.
• references/troubleshooting-and-diagnostics.md — Silent failures, error codes, and Coexistence runbook.
• references/coexistence-and-compliance.md — Coexistence setup, opt-in rules, and quality rating management.