WhatsApp Embedded Signup Expert Skill

Available in English and Spanish — SKILL.md (EN) · SKILL-ES.md (ES)

A production-grade knowledge skill for AI coding assistants (Claude Code,
OpenClaw, Codex) that guides you through the complete implementation of
WhatsApp Embedded Signup as a Meta Tech Provider.

Built from real production experience — not from reading documentation alone.
Every error documented here was caught live and fixed iteratively.

What problem does this solve?

Meta's official documentation for Embedded Signup is fragmented across
multiple pages and missing critical implementation details. This skill
consolidates everything into a single, battle-tested reference that an
AI coding assistant can use as active context while you build.

What's included

What the skill covers

Part 1 — Meta Developers Configuration

Step-by-step field reference for Facebook Login for Business, including the
critical toggles that are easy to miss (like "Iniciar sesión con el SDK de
JavaScript" which must be YES or the entire flow fails silently).

Covers: Configuration ID creation, System User token setup, webhook field
subscriptions, compliance webhook registration (deauthorize + data deletion).

Part 2 — Backend Implementation

Complete Python/FastAPI reference including:

• HMAC-SHA256 signed_request verification (no external service needed)
• OAuth code exchange server-side (never in the browser)
• Generic webhook routing by phone_number_id (one URL for all clients)
• WABA subscription to webhooks after connect
• Critical: SET LOCAL search_path scoping in multi-tenant PostgreSQL

Part 3 — Frontend Implementation (Next.js / React)

• Loading the Facebook SDK only where needed (not globally)
• The exact FB.login() call with featureType: "whatsapp_business_app_onboarding"
  for Coexistence mode
• Parsing the postMessage from Meta correctly (arrives as JSON string, not object)
• inferConnectionType() using the real event field values from Meta
• Client-facing Coexistence instructions

Part 4 — Client Invitation Flow

Single-use token system for onboarding clients without platform accounts.

Part 5 — Known Errors & Fixes

12 documented production errors with root cause and fix, including:

• JSSDK disabled error
• Coexistence option not appearing
• False HTTP 409 from database transaction scope issues
• phone_number_id empty after completing signup
• relation "X" does not exist in multi-tenant PostgreSQL

Part 6 — Security Checklist

What must never reach the frontend, what tokens expire and break connections,
and how to generate secure verification tokens.

How to use with Claude Code

# Reference the English skill
claude --context SKILL.md "implement the webhook handler"

# Reference the Spanish skill  
claude --context SKILL-ES.md "implementa el endpoint de verificación"

Or add to your project's .claude/settings.json:

{
  "contextFiles": ["SKILL.md"]
}

Who is this for

• SaaS developers building WhatsApp automation platforms
• Agencies onboarding clients to WhatsApp Business API
• Meta Tech Providers implementing Embedded Signup for the first time
• Developers who spent hours debugging the same errors that are now
  documented here

Language support

The full skill is available in both languages:

• English: SKILL.md — recommended for international teams
• Spanish: SKILL-ES.md — native Spanish technical documentation
  for Latin American and Spanish markets

All code examples, Meta API references, and official terminology remain
in English in both versions (they are proper nouns of the Meta platform).

Built by

Jose Vallejo - Digintelia — WhatsApp AI agent platform for businesses.
Support: [email protected]