███╗   ███╗███████╗████████╗ █████╗     ██████╗ ███████╗██╗   ██╗
████╗ ████║██╔════╝╚══██╔══╝██╔══██╗    ██╔══██╗██╔════╝██║   ██║
██╔████╔██║█████╗     ██║   ███████║    ██║  ██║█████╗  ██║   ██║
██║╚██╔╝██║██╔══╝     ██║   ██╔══██║    ██║  ██║██╔══╝  ╚██╗ ██╔╝
██║ ╚═╝ ██║███████╗   ██║   ██║  ██║    ██████╔╝███████╗ ╚████╔╝
╚═╝     ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝    ╚═════╝ ╚══════╝  ╚═══╝

Meta for Developers Integration Guide

Focus — the whole Meta developer surface as one platform: Graph API fundamentals, app creation, the token/permission model, webhooks, and the consumer-facing products (WhatsApp, Messenger, Instagram, Login, Marketing API), capped with a catalog of business build ideas for the Kenyan community. For the deep messaging-only reference (send/template/Twilio-vs-Meta) see the focused whatsapp-business-api guide — this guide is the platform-wide course around it.

Overview

Meta for Developers is a single platform exposed through one base URL — https://graph.facebook.com/{version}/{node-or-edge}. WhatsApp Cloud API, Messenger, Instagram, Marketing API, and Pages are all specialized layers over the Graph. Five things are worth internalizing before you write a line of code:

1. Everything is the Graph API. Master nodes/edges/fields, versioning, and error codes once; every product reuses them.
2. App type is a permanent decision. A Business app (WhatsApp, Pages, Marketing) uses access levels (Standard → Advanced via App Review). A Consumer app uses app modes (Dev/Live). You cannot convert one to the other — recreate the app if you chose wrong.
3. Tokens are a taxonomy, not a single thing. User tokens expire fast; system user tokens are the production credential for server automation.
4. Webhook HMAC is the security perimeter. Every event is signed with X-Hub-Signature-256 (HMAC-SHA256 of the raw body keyed with your App Secret). Validate with a constant-time compare before parsing.
5. WhatsApp pricing is per-message (since July 2025) and messaging limits are portfolio-wide (since Oct 2025), starting at 250 unique users / 24h and scaling algorithmically: 250 → 2,000 → 10,000 → 100,000 → unlimited.

Official Documentation

The platform map

Always pin a version (v23.0+). Unversioned calls default to the oldest supported version — a silent footgun.

Setup — register, create an app, add a product

1. Register at developers.facebook.com with a Facebook account; land in the App Dashboard.
2. Create App via the modern use-case flow — a use case auto-attaches the permissions/features/products it needs. You receive an App ID + App Secret (your OAuth client credentials — the secret never ships to a client).
3. Add Product → WhatsApp → Set up provisions a test WABA, a test phone number (free messages to 5 verified recipients), and the pre-approved hello_world template.

Tokens at a glance

Harden server-to-server calls with appsecret_proof (HMAC-SHA256 of the access token keyed with the App Secret) and enable Require App Secret so a stolen bare token is useless. See examples/graph-api-call.ts.

Quickstart

First Graph API call (official Meta Business SDK, Node)

npm install facebook-nodejs-business-sdk

// Read the node behind a token, then walk an edge. Same pattern for every product.
const adsSdk = require("facebook-nodejs-business-sdk");
adsSdk.FacebookAdsApi.init(process.env.META_SYSTEM_USER_TOKEN);
// e.g. account.read([...]) / account.getCampaigns([...]) for Marketing API

First WhatsApp message (official whatsapp SDK, verified quickstart)

npm install whatsapp
# .env: WA_PHONE_NUMBER_ID=  CLOUD_API_ACCESS_TOKEN=  CLOUD_API_VERSION=v23.0

import WhatsApp from "whatsapp";

const wa = new WhatsApp(Number(process.env.WA_PHONE_NUMBER_ID)); // sender phone-number id

async function sendMessage(recipient) {
  // text() works only inside the 24h service window; use template() to initiate.
  const res = await wa.messages.text({ body: "Habari! Your order has shipped." }, recipient);
  console.log((await res).rawResponse());
}

For raw curl/PowerShell sends, interactive messages, templates, and media, the focused whatsapp-business-api guide has the runnable recipes. This guide owns the platform-wide patterns below.

Key patterns

Webhooks (the universal push channel)

One mechanism delivers inbound WhatsApp/Messenger/Instagram messages, delivery statuses, template-review outcomes, Page events, and more — all as signed HTTPS POSTs. The contract is always:

• GET verification handshake: echo hub.challenge iff hub.verify_token matches.
• POST delivery: validate X-Hub-Signature-256 over the raw bytes, then ACK 200 immediately and process asynchronously (queue-first). Meta retries non-200 with backoff, which floods slow synchronous handlers.
• Payloads are arrays — walk every entry[].changes[].messages[]. Handling only [0] silently drops messages. Dedupe on wamid/event id (retries happen).

See examples/webhook-router.ts for a complete queue-first receiver.

WhatsApp Flows — chat that behaves like an app

Flows ship multi-screen native UI (forms, booking, lead-gen) inside the thread. Static Flows (pure Flow JSON) deliver collected data to your webhook on completion; Dynamic Flows add an encrypted data endpoint for live validation/availability. Published Flows can only be deprecated, not deleted. See examples/booking-flow.json for a Kenyan-business intake Flow.

Embedded Signup — onboard other businesses

For Tech Providers/agencies: a Meta-hosted popup (built on Facebook Login for Business) that creates/links a customer's portfolio + WABA + phone number and returns a code your server exchanges for a business token scoped to that customer. This is how you operate WhatsApp for many SMEs from one dashboard.

Build ideas for Kenyan businesses

WhatsApp is the default channel in East Africa, so the highest-leverage builds pair a WhatsApp surface with M-Pesa (see MPESA_PATTERNS.md / daraja-api). A starter catalog — the full list with effort/revenue notes is in reference/build-ideas-kenya.md:

1. Duka order bot — a WhatsApp Flow catalog + cart; checkout fires an M-Pesa STK Push; utility template confirms inside the free service window.
2. Boda / delivery dispatch — inbound location message → assign rider → delivery-status templates; rider replies drive the 24h window.
3. Clinic / salon booking — a booking Flow writes to Neon; reminder utility templates 24h before; reschedule via reply buttons.
4. Sacco / chama assistant — members check balances and contribution status; authentication templates send OTPs; statements as document messages.
5. School fees & comms — fee-balance utility templates + an M-Pesa paybill link; broadcast announcements via marketing templates (with opt-out).
6. Agri price & advisory — daily market-price templates by crop; a Flow captures produce listings; buyers reply to express interest.

Every one of these is a thin WhatsApp/Flows front-end over the codeAmani stack (Next.js + Neon/Supabase + Daraja), which is exactly the build sweet spot.

codeAmani notes

• Secrets server-side only. App Secret, system user tokens, and Flow private keys never reach a client. Store in .env.local / Vercel env (see ENV_MASTER.md). Run gitleaks before any push.
• Webhook verification is non-negotiable — HMAC-SHA256 of the raw body with timingSafeEqual, mirroring our Stripe/Clerk webhook discipline (SECURITY.md).
• Phone format: WhatsApp's JSON to uses E.164 without + (254712345678). This matches Daraja's 254… rule — but normalize per API; never reuse a Daraja-formatted string directly in a Twilio call (Twilio wants whatsapp:+254…).
• AI routing: put the reply brain (Claude primary per AI_WORKFLOWS.md) in the async webhook worker, never inline in the 200-ACK path. Cap output to WhatsApp's text limits.
• Payments: Kenyan-targeted WhatsApp commerce → M-Pesa/Daraja; US-first → Stripe (the default rail). The build ideas above assume the Kenyan rail.
• Pricing discipline: prefer utility templates inside the open 24h window (free) over marketing templates; record per-message pricing category from webhook statuses for cost rollups.