Growth meta whatsapp

WhatsApp Business Platform — Production Reference (2025-2026)

Naming: Meta's umbrella is WhatsApp Business Platform; the current API is the Cloud API. "WhatsApp Business API" is legacy phrasing (the On-Premises API sunset Oct 23, 2025). "WABA" (WhatsApp Business Account) is an account entity, not an API. API current version: v23.0+. All conversation-based pricing replaced by per-message pricing July 1, 2025.

Depends on: the growth-meta skill (BM health, verification, account quality/classifier, proxy/isolation, disposable-BM strategy, ban mechanics). ALWAYS load growth-meta first. Do NOT load growth-meta-ads unless doing CTWA.

Also depends on: the database-mapping skill, for anything that measures a dispatch. Measurement has to know which table holds a person, which column holds a phone, and what counts as money arriving or leaving; that binding is the project's and lives in its database map. Load database-mapping before measuring — a dispatch whose project is unmapped, or mapped against a schema that has since moved, cannot be measured, and the engine stops rather than guessing. It is named here rather than left to a hook: the reach has to work in any project and any harness, with nothing auto-loading it on your behalf.

Related: growth-meta-ads (CTWA campaign setup + CAPI attribution); growth-ycloud (the YCloud BSP platform) + growth-ycloud-api (YCloud v2 REST API).

---

MANDATORY — read context AND report the full BM roster BEFORE any action
(including before clarifying questions):
1. READ `.maccing/growth/README.md` (the platform/account index), if it exists.
2. ENUMERATE every BM — never assume one. The path is `meta/<profile>/<bm>/`, so
   list `.maccing/growth/meta/*/` (profiles) and `.maccing/growth/meta/*/*/` (BMs),
   then READ the root README, EVERY profile README, and EVERY BM README found.
3. Also READ EVERY WABA README: `.maccing/growth/meta/*/*/whatsapp/*/README.md`.
4. TELL the operator a roster of ALL BMs up front — one line each
   (profile · BM · verification/tier · WhatsApp number · quality · wallet/ramp) —
   INCLUDING BMs unrelated to the current task. Never silently narrow to one BM.
Skipping this = operating on stale data and hiding live assets from the operator.

---

Send Doctrine — read this before the routing table

⚠️ DOCTRINE — the campaign/broadcast SEND is ALWAYS operator-executed, NEVER automated by the agent. The agent builds and validates the recipient list, runs the pre-send health gate, picks the template, and reconciles results afterward — but the human operator is the one who uploads the list and clicks Send in the BSP UI (e.g. YCloud → Campaigns → New campaign). The agent MUST NOT submit a marketing broadcast programmatically: no POST /v2/whatsapp/messages loop over a list, no broadcast endpoint, no sendDirectly fan-out. Why: a broadcast is irreversible, costs real money, reaches hundreds of real people, and one mistake (wrong template, wrong list, wrong variable mapping) can crater a hard-won quality rating or permanently ban the number — a human at the trigger is the last safety gate. Scope: this covers bulk campaign/broadcast sends; single transactional/inbox replies inside the 24h service window are not the target.

Duplicated verbatim from references/sending-and-scale.md on purpose: the router below hands out files that contain a working send, so the prohibition has to load first. Do not "de-duplicate" it away.

---

Routing Table

Intent	Reference	Use for
Message types, payloads, interactive messages, typing indicator, read receipt	references/message-types.md	All send-message JSON shapes; text, image, video, document, audio, sticker, location, contacts, reaction, buttons, lists, flows, typing
Template creation, approval, pacing, limits, dispatch strategy	references/templates.md	Creating templates via API, template JSON, approval process, quality states, pacing vs pausing, Template Strategy for marketing broadcasts (copy, image headers, forbidden words, opt-out)
Quality KPIs, throughput tiers, daily limits, quality rating, recovery protocol, queue management	references/sending-and-scale.md	80 MPS throughput, messaging limit tiers, quality system, quality KPIs, recovery protocol, bulk send queue code
WhatsApp Flows (native in-chat forms, appointments, surveys)	references/flows.md	Flow JSON schema, API endpoints, dynamic flows backend, payment flows (Brazil/India)
Webhook events, payloads, signature verification, BSUID, best practices	references/webhooks.md	Incoming message webhooks, status updates, BSUID June 2026 change, Express handler code, queue-first architecture
Media upload, retrieve, download, caching	references/media.md	Supported formats, size limits, upload/retrieve/download API, media ID reuse strategy
Node.js/TypeScript SDK, raw fetch, integration patterns	references/integration-sdk.md	@great-detail/whatsapp SDK setup, webhook handler, raw fetch, order lifecycle/CTWA/CRM patterns
Error codes, retry logic, delivery failures, 131026/131049/132015	references/error-codes.md	Full error code table by category, retry strategy TypeScript snippet, real-world broadcast baselines
Opt-in/opt-out, LGPD (Brazil), GDPR, anti-spam, content restrictions, Business Profile compliance, display-name approval, verification, OBA, financial-niche	references/compliance.md	Consent requirements, opt-out recognition, LGPD 5-year retention, 2026 AI restriction, Business Profile API + field definitions, display-name approval, verification, OBA requirements, financial-niche restrictions
Per-message pricing, free windows (CSW/CTWA), Meta rate card, cost optimization, BSP comparison table, WhatsApp Payments	references/pricing-and-billing.md	PMP rates by market, free window rules, volume tier discounts, Meta base rate card, cost calc, full BSP comparison table, WhatsApp Payments (Brazil/India)
Direct Cloud API setup, BSP migration, number quality/longevity, cold lists	references/waba-provisioning.md	Direct Cloud API setup sequence, switching BSP / migrating WABA (PIN reset, device-trust gotchas), cold list strategy
Outsourced dispatch (a third party sends on their numbers), and the campaign measurement contract	references/outsourced-dispatch.md	Outsource-vs-own-WABA call, unit price vs own CPDM, phone×segment attribution, split-test design, statistical power / MDE, copy-vs-product verification, vendor checklist, entity correlation; declaring cells and controls and calling measure from @maccing/growth
Disposable BM pipeline, proxy/isolation stack, BM sources, profile acquisition, phone number strategy, display name strategy	growth-meta skill	Full disposable-BM strategy, proxy comparison table, BM setup sequence, Number Warming Protocol (official WABA), phone number acquisition
YCloud BSP platform (campaigns, inbox, contacts, webhooks)	growth-ycloud skill	BSP platform operations, campaign management, YCloud features
YCloud v2 REST API (send message, list messages, webhook endpoints, pagination)	growth-ycloud-api skill	YCloud API reference, pagination gotchas (page not offset), HMAC signature, campaign-send lag caveat, broadcast monitoring

---

1. Platform Overview

WhatsApp Business App vs. Cloud API

Dimension	WhatsApp Business App	WhatsApp Cloud API
Target	Small business, 1-2 agents	Enterprise, automation, scale
Access	Free mobile app	REST API (Meta-hosted)
Volume	Manual, limited	Programmatic, unlimited
Automation	None	Full (chatbots, CRM, flows)
Templates	Basic	Full template library
Multi-agent	No	Yes (via inbox platform)
Analytics	None	Full metrics API
Cost	Free	Per-message charges apply

On-Premises API: Permanently shut down October 23, 2025. Cloud API is the only path. Error code 1005 = number still on on-prem.

Coexistence — one number on both the Business App and Cloud API

Meta's own name for this is "API Solutions for Business App Users"; support and partner channels call it Coexistence. It is entered through Embedded Signup: the business connects its existing WhatsApp Business app account and number to Cloud API, then keeps answering 1:1 from the phone while the API sends at volume, with both directions mirrored (Meta primary doc).

• Who can offer it: the integrator must already be a Solution Partner or Tech Provider; the business must run WhatsApp Business app 2.24.17+.
• Sync: contacts, and 1:1 history for the most recent 6 months, are synchronizable — but only if you subscribe to the history, smb_app_state_sync and smb_message_echoes webhook fields AND fire both smb_app_data sync calls within 24h of onboarding. Miss that window and the customer must offboard and redo Embedded Signup.
• Confirm the state: GET /{PHONE_NUMBER_ID}?fields=is_on_biz_app,platform_type — both modes live is is_on_biz_app: true plus platform_type: CLOUD_API.
• What it costs you: throughput is fixed at 20 mps (against the 80 default), Broadcast lists are disabled (existing ones go read-only), and group chats, disappearing messages, view-once, live location and voice/video calls are unsupported on the Cloud API side.
• Window and billing: a customer service window opens only when a user messages a number that is already onboarded. Messages sent from the app sit outside the CSW entirely — they neither create nor extend a Cloud API window, and are not billed as Cloud API.
• Offboarding is client-side: the Deregister API will NOT deregister a coexisting number. The business disconnects in-app (Settings → Account → Business Platform → Disconnect Account), which fires account_update with PARTNER_REMOVED.
• Expect error 131060 (an unsupported messages webhook) on a user's first inbound and from unsupported companion devices — normal, usually clears within seconds.

Dispatch verdict: the 20 mps ceiling and the loss of Broadcast lists make coexistence an inbox/service posture, not a broadcast posture. Do not onboard a number you intend to broadcast from.

Integration paths:

1. Direct Cloud API — REST against Meta directly. Full control, requires engineering effort.
2. BSP (Business Solution Provider) — managed infrastructure with inbox, automation, analytics UI. Recommended BSP: YCloud (see growth-ycloud skill).

---

2. Cloud API Setup

Prerequisites: Meta Developer account, verified Meta Business Manager, verified business entity, phone number not previously on any WhatsApp account.

Step-by-step:

1. Create Meta Business Account at business.facebook.com
2. Register as Meta Developer at developers.facebook.com
3. Create a Business type app → Set Up WhatsApp product
4. Add phone number → verify via SMS or voice call
5. Generate System User permanent token (Admin role, permissions: whatsapp_business_messaging, whatsapp_business_management, catalog_management) — never use the 24h temporary token in production
6. Configure HTTPS webhook endpoint → subscribe to the messages field
7. (Optional) Apply for OBA blue badge (WABA 30+ days old, verified, 2FA, notable coverage)

API version: v23.0. Base URL: https://graph.facebook.com/v23.0/{phone_number_id}/messages. Pin to a specific version in production.

Webhook verification handler:

app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];
  if (mode === 'subscribe' && token === process.env.WEBHOOK_VERIFY_TOKEN) {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

---

13. WhatsApp Business Calling API (July 2025)

GA July 15, 2025. Voice calls directly within WhatsApp conversations.

CSW interaction: A user-initiated call opens and resets the 24-hour Customer Service Window, identical to an inbound message. After a call, businesses can send free-form service messages and free utility templates for 24 hours.

Two call types: user-initiated (inbound) and brand-initiated (outbound, to opted-in users).

Requirements: System User token with whatsapp_business_messaging, HTTPS webhook subscribed to calls field, WebRTC implementation (or BSP), IVR via DTMF.

Key features: full conversation thread visible during call, click-to-call buttons in interactive/template messages, IVR via DTMF.

---

14. Marketing Messages Lite API (MM Lite)

Launched April 2025. A dedicated API for marketing broadcasts using Meta's ads AI to optimize delivery timing and recipient selection.

Aspect	MM Lite API	Cloud API
Purpose	Marketing broadcasts	All message types
AI optimization	Yes (Meta ads AI)	No
Delivery rate	Up to 9% higher	Standard
US users	Not delivered	Not delivered (since April 2025)
Interaction	One-way (templates only)	Two-way

When to use: large marketing broadcasts → MM Lite; customer support, utility, two-way → Cloud API.

Note for 360dialog / Gupshup users: prefer MM API route to avoid their ~6-7% marketing surcharge that applies only on the standard Cloud API endpoint.

---

15. WhatsApp Business Management API

Phone Number Management: GET /{WABA_ID}/phone_numbers, add/register numbers programmatically, set display names, manage 2FA PINs.

Template Management:

POST /{WABA_ID}/message_templates  # Create
GET  /{WABA_ID}/message_templates  # List (filter: ?status=APPROVED)
POST /{TEMPLATE_ID}                # Update
DELETE /{TEMPLATE_ID}              # Delete

QR Code Management: POST /{PHONE_NUMBER_ID}/message_qrdls — create pre-filled chat QR codes.

Analytics: GET /{WABA_ID}/analytics?start=...&end=...&granularity=DAY&metric_types=SENT,DELIVERED,READ

---

16. Business Profile Fields

See references/compliance.md for all Business Profile field definitions, the POST /{PHONE_NUMBER_ID}/whatsapp_business_profile API reference, display-name approval mechanics, verification, OBA requirements, and financial-niche profile compliance.

---

18. 2025-2026 Key Changes Summary

Change	Date	Impact
On-Premises API sunset	October 23, 2025	All must use Cloud API
Per-message pricing (PMP replaces CBP)	July 1, 2025	Each template message billed individually
Utility free in CSW	July 1, 2025	Utility templates inside 24h window are free
Auth rates -65% to -78% (LATAM)	July 1, 2025	Major OTP cost reduction
Marketing blocked to US numbers	April 1, 2025	No marketing to US users (error 131049)
MM Lite API launched	April 2025	AI-optimized marketing delivery
Messaging limits: portfolio-level	October 7, 2025	All numbers in portfolio share tier
Tier evaluation: every 6 hours	2025	Faster scaling
WhatsApp Business Calling GA	July 15, 2025	Voice calls in WhatsApp
Blue badge replaces green badge	2024 (rolled out 2024-2025)	UI change only; existing badges converted
Service conversations unlimited-free	November 1, 2024	No monthly cap; all service conversations free
Utility/Auth body cap: 512 chars	October 1, 2025	Error 2388040 if exceeded at creation
Flagged phone-number status eliminated	October 7, 2025	Red quality only blocks advancement, no auto-downgrade
Verified tier floor raised to 2,000/day	October 7, 2025	Was 1,000
HTTPS URL requirement for templates	January 1, 2026	Shorteners rejected; must be live HTTPS
Brazil BRL local billing	July 1, 2026	Eligible accounts billed in BRL
Meta CA cert change (mTLS)	March 31, 2026	Update trust store: meta-outbound-api-ca-2025-12.pem
BSUID added to webhooks	March 31, 2026	New identity.user_id field
BSUID may replace phone in from	June 2026+	CRM must handle both identifiers
AI chatbot restriction	2026	Only task-specific AI allowed
Auto-categorization enforcement	April 9/16, 2025	Meta auto-corrects category; repeat offenders lose UTILITY access 7 days
Carousel messages (interactive)	unverified	2-10 cards, CSW only (non-template) — references/message-types.md
Business App + Cloud API coexistence	unverified	Same number in both; 20 mps ceiling, Broadcast lists disabled — §1 → Coexistence

Two dates above read unverified on purpose. Neither feature page carries a publication or updated date, and Meta's public changelog — the one place a landing date is published — returned HTTP 500 on every attempt. So the "February 2026" and "January 2026" dates previously asserted here could not be confirmed against a primary source, and are no longer asserted. Both features are confirmed from Meta docs — interactive media carousel and coexistence — only their ship dates are unknown. To close the gap, retry the changelog; do not restore a remembered date.

---

19. Quick Reference

Essential Endpoints

POST https://graph.facebook.com/v23.0/{PHONE_NUMBER_ID}/messages        # Send message
POST https://graph.facebook.com/v23.0/{PHONE_NUMBER_ID}/media           # Upload media
GET  https://graph.facebook.com/v23.0/{MEDIA_ID}                        # Get media URL
POST https://graph.facebook.com/v23.0/{WABA_ID}/message_templates       # Create template
GET  https://graph.facebook.com/v23.0/{WABA_ID}/message_templates       # List templates
GET  https://graph.facebook.com/v23.0/{WABA_ID}/phone_numbers           # Get phone numbers
POST https://graph.facebook.com/v23.0/{WABA_ID}/flows                   # Create flow
POST https://graph.facebook.com/v23.0/{FLOW_ID}/publish                 # Publish flow
GET  https://graph.facebook.com/v23.0/{WABA_ID}/analytics               # Analytics

Required Permissions

whatsapp_business_messaging    # Send/receive messages
whatsapp_business_management   # Manage templates, phone numbers, settings
catalog_management             # Product catalog integration (optional)

New Integration Checklist

• Meta Business account created and verified
• App created in Meta Developer dashboard
• Phone number added and verified (6-digit code)
• System User created with Admin role
• Permanent access token generated and stored securely
• Webhook endpoint deployed with HTTPS
• Webhook verification challenge handler implemented
• Webhook signature verification implemented (x-hub-signature-256)
• messages field subscribed in webhook settings
• At least one template created and approved
• Opt-in collection mechanism in place before any proactive messaging
• Env vars: WA_PHONE_NUMBER_ID, WA_BUSINESS_ACCOUNT_ID, WA_ACCESS_TOKEN, APP_SECRET, WEBHOOK_VERIFY_TOKEN
• CRM stores both phone number AND BSUID fields
• Error handling with retry logic implemented
• Idempotent webhook processing with message ID deduplication

Cost Calculation Formula

Monthly Cost = Σ (messages_delivered × country_rate × category_multiplier)
             - volume_discounts (utility/auth only)
             - free_CSW_utility_messages
             - free_72h_CTWA_messages

Effective Rate: Marketing >> Utility > Authentication >> Service (free)