WhatsApp Business API Builder Kit

Everything you need to build, ship, and debug WhatsApp Business Platform (Meta Cloud API) integrations correctly the first time. Five battle-tested Claude skills covering message templates, carousels, interactive Flows, coexistence mode, and the Meta OAuth preflight checklist — including the error catalog and the silent-failure gotchas that normally cost days of debugging. Install them into your Claude skills directory and they activate automatically whenever you work on WhatsApp.

This pack includes 5 Claude skills:

whatsapp-cloud-api, whatsapp-carousel-template, whatsapp-flows-builder, whatsapp-coexistence-guide, meta-oauth-preflight

---

WhatsApp Cloud API Skill

What it does

Turns Claude into a WhatsApp Business Platform (Meta Cloud API) expert. It knows the rules that make WhatsApp integrations succeed — and, more importantly, the rules whose violation makes them fail silently. The skill covers:

**Message templates** — naming rules, component structure (header/body/footer/buttons), the three

categories (MARKETING / UTILITY / AUTHENTICATION), variable rules, and the media-header gotcha that causes most template rejections.

**Media messages** — sending images, videos, and documents (upload-then-send and send-by-URL), with

exact size limits and payload shapes.

**Product catalog messages** — single-product and multi-product list messages, with the catalog/SKU

requirements.

**The 24-hour customer service window** — the rule that decides when you can send free-form messages

versus when you must use an approved template, with a decision tree.

**The Meta error catalog** — a lookup table mapping the codes you actually hit in production

(132000, 132012, 132018, 131009, 131047, 131042, and more) to their real root cause and the fix, plus a deep-dive on the recurring 132012 (media-header template sent with body-only components).

**Three worked examples** — send an approved template, send a media message, and debug a 132012 end

to end with reproduce → inspect → fix curls.

The payoff: Claude writes correct WhatsApp payloads the first time and debugs failures by error code instead of guessing.

How to use it

Once installed, the skill activates automatically whenever you discuss WhatsApp Cloud API work — creating templates, sending media or catalog messages, or debugging a Meta error code. You can also invoke it explicitly with the Skill tool (`whatsapp-cloud-api`).

Everything is genericized with placeholders (`YOUR_PHONE_ID`, `YOUR_ACCESS_TOKEN`, `YOUR_WABA_ID`, `YOUR_CATALOG_ID`, `RECIPIENT_E164`, `GRAPH_VERSION`). Replace them with your own Meta values before running any command, and keep tokens in environment variables rather than in source.

Typical prompts:

"Create a UTILITY template that confirms an order and has a tracking-URL button."

"My VIDEO-header template fails with 132012 on every send — fix the payload."

"Send product SKU-12345 from my catalog to this customer."

"Why does my message return 131047, and how do I send it correctly?"

Claude pulls the exact payload, validation rule, or error-code fix from the skill and applies it to your case. See `README.md` for the full quick-start and a map of the skill's sections.

How to install it

This is a Claude skill, so installation is just placing the folder where Claude auto-loads skills:

unzip whatsapp-cloud-api.zip -d ~/.claude/skills/
# results in: ~/.claude/skills/whatsapp-cloud-api/skill.md

Restart Claude Code (or your Claude client) so it picks up the new skill. It then loads automatically when relevant, and you can invoke it directly via the Skill tool using the name `whatsapp-cloud-api`. No dependencies, no build step — the skill is plain Markdown knowledge.

---

WhatsApp Carousel Template Builder

What it does

This is a Claude skill that gives Claude the complete, battle-tested knowledge to build, submit, and track **WhatsApp Carousel message templates** on the Meta WhatsApp Business Platform — the multi-card format of 2–10 horizontally swipeable cards, each with an image, a short body, and a URL button.

It encodes the things people get wrong:

The critical distinction between a **carousel template** (pre-approved, works for cold

outreach with no open conversation window) and an **interactive carousel** (runtime only, works inside the 24-hour window) — so Claude always picks the right one.

Meta's exact rules and limits: 2–10 cards, ≤160-char card bodies, ≤20-char button

labels, ≤1024-char intro body, homogeneous cards (same button type and structure), and image specs (JPEG/PNG, ≤5MB, 1.91:1 or 1:1).

The two-step build flow: upload each image to get a `media_handle`, then submit the

assembled carousel — in the same session, because handles expire.

The approval lifecycle (`pending` → `approved`/`rejected`) and how to poll/sync it.

A generic DB storage pattern, a localization note (incl. RTL / Arabic), a full worked

3-card example, and a failure-mode troubleshooting table.

The result: fewer Meta rejections, correct copy lengths the first time, and a clean upload-then-submit flow you can run by hand or wire into your own backend.

How to use it

Once installed, the skill loads automatically when your request matches it. Just ask Claude in natural language, for example:

"Create a WhatsApp carousel template with 3 product cards and URL buttons."

"Should I use a carousel template or an interactive carousel for this campaign?"

"Meta rejected my carousel — what's wrong?"

"Write the upload + create API calls for a 4-card carousel."

Claude will plan the cards within Meta's limits, walk through the upload-then-submit steps, and tell you what to check for approval. You can also invoke it explicitly with the Skill tool using the name `whatsapp-carousel-template`.

The skill is backend-agnostic: it uses placeholders (`YOUR_DOMAIN`, `YOUR_API_KEY`, `YOUR_TENANT_ID`) that you replace with your own API gateway / WhatsApp integration values.

How to install it

This is a Claude skill, so installation just means placing the folder where Claude looks for skills:

1. Unzip the package into your skills directory so the path is `~/.claude/skills/whatsapp-carousel-template/` and that folder contains `SKILL.md`. 2. That's it — Claude auto-loads skills from `~/.claude/skills/` on the next session. 3. To use it, either ask a matching question (it activates by description) or invoke it explicitly via the Skill tool with the name `whatsapp-carousel-template`.

No build step, no dependencies, no API keys are bundled — you supply your own backend endpoints and credentials when you use it.

---

WhatsApp Flows Builder

A Claude skill that turns Claude into an expert at building **WhatsApp Flows** — Meta's interactive in-chat forms (radio menus, dropdowns, text/date inputs, multi-screen wizards) for any WhatsApp Business number.

What it does

It gives Claude a complete, production-tested playbook for the full WhatsApp Flow lifecycle, so it can build flows correctly the first time instead of rediscovering Meta's quirks by trial and error. Specifically, the skill teaches Claude to:

**Design the right architecture** — when to answer with a plain text reply vs a flow, how to size menus to Meta's 9-option radio limit, and when to split into a Language Selection flow plus sub-flows.

**Handle bilingual audiences correctly** — a hard rule against mixing two languages on one screen, plus the "Language Selection → fully-monolingual flows" isolation pattern (with copy-paste language helper code) that prevents the most common UX failure.

**Author valid Meta Flow JSON (v7.1)** — every component (RadioButtonsGroup, Dropdown, TextInput, TextArea, DatePicker, text displays, navigate/complete Footers), the `terminal`/`complete` rules, and naming conventions Meta enforces.

**Publish and route** — insert as draft, publish to Meta, wire the language chain, and set the per-number routing flag (`response_mode`) that is the single most common reason a flow "doesn't work."

**Handle submissions** — a full submission-handler pattern with account guarding, flow-name matching, fallbacks, async-safe notifications, a mandatory "What's Next" follow-up, and PII redaction.

**Avoid the known traps** — a curated table of the mistakes everyone hits (immutable published flows, blocked event loops, brittle name matching, missing fallbacks, Unicode escaping, and more) with the exact fix for each.

It ships with five ready-to-adapt example files: a single-menu flow, a bilingual language-selection flow, a multi-screen booking wizard, a "What's Next" flow, and a complete submission handler in Python.

How to use it

Once installed, the skill activates automatically whenever you ask Claude to build, set up, design, or wire WhatsApp Flows — for example: "Build a WhatsApp Flow with a main menu and a call-back form," "Add an Arabic + English booking flow to my WhatsApp number," or "Why does my published flow's edit not take effect?"

You can also invoke it explicitly with the Skill tool (`whatsapp-flows-builder`).

Claude will follow the step-by-step process: design → author the JSON (starting from the examples) → publish → set routing → write the submission handler → verify. Provide your `phone_number_id`, `waba_id`, and how your backend stores flows, and Claude will map the generic data model (`flows`, `flow_submissions`, `numbers`) onto your stack. Replace the placeholders (`YOUR_PHONE_ID`, `YOUR_WABA_ID`, `YOUR_TENANT_ID`, `YOUR_ACCESS_TOKEN`, `YOUR_API_BASE`, `YOUR_API_KEY`) with your real values, and never commit real access tokens.

How to install it

This is a Claude skill. To install it:

1. Unzip the package into your Claude skills directory so the files live at `~/.claude/skills/whatsapp-flows-builder/` (the folder should contain `SKILL.md`, `README.md`, `description.md`, and the `examples/` directory). 2. That's it — Claude auto-loads skills from `~/.claude/skills/` on the next session, and the skill activates on relevant requests. 3. To run it on demand, invoke it via the Skill tool with the name `whatsapp-flows-builder`.

No dependencies, no build step, no API keys required to install. The skill is documentation-only; it instructs Claude and provides example files you adapt to your own backend.

---

WhatsApp Coexistence Guide

What it does

This is a Claude skill that gives Claude expert, battle-tested knowledge of **WhatsApp coexistence mode** — running one phone number on both the WhatsApp Business App (the owner's mobile app) and the WhatsApp Cloud API at the same time. It is a compact bonus/add-on reference for anyone building on the WhatsApp Cloud API.

When loaded, it lets Claude:

Explain exactly what coexistence is and its hard Meta limits (20 msg/sec cap, 1:1 only, ~6 months one-time history sync).

Walk through onboarding a number into coexistence (manual/admin flow, app-owner path, and Embedded Signup path).

Identify the coexistence-only webhook fields (`history`, `smb_app_state_sync`, `smb_message_echoes`) and how each behaves.

Debug the common failures: history that never imports, business-sent replies that never appear, media placeholders, and offboarding.

It includes the gotchas that normally cost a day of debugging — most notably that the `smb_message_echoes` webhook value uses the `message_echoes` key (not `messages`), the strict 24h history window, and the requirement that chat backup be enabled before onboarding. Two worked debugging examples are included.

All vendor-specific identifiers are placeholders (`YOUR_META_APP_ID`, `YOUR_COEXISTENCE_CONFIG_ID`, `{phone_number_id}`) — drop in your own values.

How to use it

1. After installing, the skill auto-loads and Claude will draw on it whenever your request involves WhatsApp coexistence — for example: "onboard this number in coexistence mode", "old chats didn't sync", "the owner's phone replies aren't showing in our inbox", or "how do I offboard a coexistence number". 2. You can also invoke it explicitly with the Skill tool by its name, `whatsapp-coexistence-guide`. 3. Replace the placeholders (`YOUR_META_APP_ID`, `YOUR_COEXISTENCE_CONFIG_ID`, `{phone_number_id}`, and your own data-model flags such as the bot-active flag and `waba_id` column) with your platform's real values when applying the guidance. 4. Use the two worked examples as step-by-step debugging checklists when a sync or echo problem appears.

See `README.md` for a quick-start summary and the placeholder table.

How to install it

This is a Claude skill. To install:

1. Unzip the package into your Claude skills directory so the files live at `~/.claude/skills/whatsapp-coexistence-guide/` (the folder must contain `SKILL.md`). 2. That's it — Claude auto-loads skills from `~/.claude/skills/` on the next session. No build step or restart configuration is required. 3. To confirm, start a new session and either ask a WhatsApp coexistence question or invoke the skill by name (`whatsapp-coexistence-guide`) via the Skill tool.

---

Meta OAuth Preflight

What it does

Meta OAuth Preflight is a Claude skill that turns the painful, trial-and-error process of wiring up a Meta / Facebook / Instagram OAuth login into a deterministic checklist. It encodes the hard-won knowledge of what actually breaks Meta OAuth integrations and gives Claude an exact diagnosis path for the four failure modes that derail almost every implementation:

**Bad `redirect_uri`** — "URL blocked" / "domain not included in the app's domains"

**"Unauthorized" callbacks** — the callback path isn't whitelisted as a public route

**Silent redirects that go nowhere** — the proxy drops the `Location` header on the OAuth 302

**`config_id` vs `scope`** — using `scope=` instead of a Login-for-Business `config_id`, which

silently returns a token missing the permissions you need

It also covers a 6-point pre-flight checklist (redirect URI, web-tier public paths, backend public paths, `config_id` usage, proxy header forwarding, and App Domains), a quick failure-mode diagnosis table, three worked examples (a happy-path Instagram connect, an "Unauthorized" debug, and a "redirect goes nowhere" debug), a fix for `ERR_CONNECTION_REFUSED` during heavy testing, and a clean pattern for labeling/routing connected accounts without environment variables.

How to use it

Once installed, the skill loads automatically and Claude consults it whenever you work on a Meta OAuth flow. Start a request like:

"Add an Instagram OAuth connect flow to my app."

"My Meta OAuth callback returns Unauthorized — help me debug it."

"After Facebook consent the redirect goes nowhere, what's wrong?"

"Why does my OAuth token come back missing permissions?"

You can also invoke it explicitly via the Skill tool by name (`meta-oauth-preflight`).

Before applying the steps, substitute the documented placeholders for your own values: `YOUR_DASHBOARD_DOMAIN`, `YOUR_API_DOMAIN`, `YOUR_META_APP_ID`, `YOUR_META_APP_SECRET`, `YOUR_CONFIG_ID`, `YOUR_ROOT_DOMAIN`, and your own OAuth route paths. The skill is framework-agnostic — the grep commands and patterns adapt to whatever web server, backend, and proxy you run. Keep your app secret in an environment variable or secret manager; the skill never asks you to hardcode it.

How to install it

This is a standard Claude skill distributed as a folder.

1. Unzip the package so its contents live at `~/.claude/skills/meta-oauth-preflight/` (the folder should contain `README.md` and `description.md`). 2. That's it — Claude Code auto-loads skills from `~/.claude/skills/` on startup. No build step, no configuration. 3. To use it, just describe a Meta OAuth task in chat, or invoke it by name (`meta-oauth-preflight`) with the Skill tool.

To verify installation, run `ls ~/.claude/skills/meta-oauth-preflight/` and confirm `README.md` is present. If skills were already loaded, restart your Claude Code session so the new skill is picked up.

---

Delivered as a ZIP of Claude skill folders. Unzip into your Claude skills directory; each skill auto-loads on the next session.