Quick Start

New project? Scaffold a working WhatsApp app in 30 seconds. No Meta account needed to start:

npm create whatsapp-app@latest my-bot
cd my-bot && npm run dev

It opens in mock mode: you play the customer in the browser, your message runs through the SDK as a real webhook payload, and lib/bot.ts replies. Add credentials to .env.local and the same code talks to real WhatsApp. See create-whatsapp-app.

Existing project?

pnpm add meta-cloud-api

import WhatsApp from 'meta-cloud-api';

const wa = new WhatsApp({
    accessToken: process.env.CLOUD_API_ACCESS_TOKEN!,
    phoneNumberId: Number(process.env.WA_PHONE_NUMBER_ID),
});

// Send a text message
await wa.messages.text({ to: '1234567890', body: 'Hello from TypeScript!' });

// Send a template message
await wa.messages.template({
    to: '1234567890',
    body: {
        name: 'hello_world',
        language: { code: 'en_US', policy: 'deterministic' },
    },
});

// Send an image
await wa.messages.image({ to: '1234567890', body: { link: 'https://example.com/image.png' } });

Why meta-cloud-api?

Meta's own WhatsApp Node.js SDK has been archived since June 2023 — no fixes, no updates, no OpenAPI v23 support. meta-cloud-api is a maintained, type-safe alternative built on the same official Cloud API.

| | meta-cloud-api | Official SDK | Unofficial libraries (whatsapp-web.js, Baileys) | |---|---|---|---| | API basis | Official Cloud API | Official Cloud API | Reverse-engineered, unofficial | | Account ban risk | None | None | Yes — violates WhatsApp ToS | | Maintenance | Active (tracks OpenAPI v23) | Archived since 2023 | Varies | | TypeScript | Strict, full request/response types | Partial | Varies | | API coverage | 22 modules (Messages, Flows, Calling, Payments, and more) | Messaging-focused | Personal-account features | | Webhook adapters | Built-in Express.js, Next.js, Hono, Fastify (NestJS via Express) | Manual | Custom event system |

If you're building on the official Cloud API and don't want to bet on an unmaintained SDK, this is what the archived one would look like if Meta had kept shipping it.

Coming from the whatsapp package? The migration guide maps every API of the archived SDK (config, messages, templates, webhooks, errors) to meta-cloud-api, with a checklist.

API Coverage

wa.messages              // Text, image, video, document, audio, sticker, location, contact, template, interactive, reaction
wa.media                 // Upload, get, delete media
wa.templates             // Create, list, delete message templates
wa.flows                 // WhatsApp Flows management
wa.groups                // Group management
wa.calling               // Voice calling
wa.payments              // Payment processing (India)
wa.businessProfile       // Business profile management
wa.phoneNumbers          // Phone number management
wa.commerce              // Commerce settings
wa.marketingMessages     // Marketing message management
wa.qrCode               // QR code generation
wa.registration          // Phone registration
wa.twoStepVerification   // 2FA management
wa.encryption            // End-to-end encryption
wa.blockUsers            // Block/unblock users
wa.contactBook           // Delete a BSUID contact book entry
wa.threadControl         // Conversation Routing: pass, release, take threads
wa.waba                  // WhatsApp Business Account management
wa.business              // Business portfolio, pre-verified phone numbers, owned/client WABAs, credit lines
wa.messageHistory        // Message history and history events
wa.solutions             // Multi-Partner Solutions management

Webhooks

import express from 'express';
import { expressWebhookHandler } from 'meta-cloud-api';

const app = express();
// Keep the raw body: signatures are computed over the exact bytes Meta sent
app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf.toString(); } }));

// Handler is automatically cached per phoneNumberId — safe against HMR re-evaluation
const Whatsapp = expressWebhookHandler({
    accessToken: process.env.CLOUD_API_ACCESS_TOKEN!,
    phoneNumberId: Number(process.env.WA_PHONE_NUMBER_ID),
    webhookVerificationToken: process.env.WEBHOOK_VERIFICATION_TOKEN,
    // Reject forged POSTs: require a valid X-Hub-Signature-256 from Meta
    appSecret: process.env.APP_SECRET,
    verifyWebhookSignature: true,
});

// Handle incoming text messages — echo back to sender
Whatsapp.processor.onText(async (wa, processed) => {
    const { message } = processed;
    await wa.messages.text({ to: message.from, body: `Echo: ${message.text.body}` });
});

// Handle message status updates
Whatsapp.processor.onStatus((wa, processed) => {
    const { status } = processed;
    console.log(`Message ${status.id}: ${status.status}`);
});

// Handle template status changes
Whatsapp.processor.onMessageTemplateStatusUpdate((wa, { value }) => {
    console.log(`Template "${value.message_template_name}" is now ${value.event}`);
});

// Mount on Express
app.get('/webhook', Whatsapp.GET);
app.post('/webhook', Whatsapp.POST);

Other frameworks use the same handler object (GET, POST, webhook, flow, processor, destroy):

| Framework | Adapter | Guide | |---|---|---| | Express.js | expressWebhookHandler | Express | | Next.js App Router | nextjsAppWebhookHandler | Next.js App Router | | Next.js Pages Router | nextjsPagesWebhookHandler | Next.js Pages Router | | Hono (Node.js, Bun, Deno, Workers, Edge) | honoWebhookHandler | Hono | | Fastify | fastifyWebhookHandler | Fastify | | NestJS | expressWebhookHandler or fastifyWebhookHandler | NestJS |

All 30+ webhook field types are supported — messages, statuses, templates, flows, groups, calls, and more. See the Webhooks documentation for the full list of handlers.

Requirements

• Node.js 20.12+, Bun, Deno, Cloudflare Workers or Vercel Edge — no runtime dependencies, no node:* imports (runtime guide)
• TypeScript 4.5+ (for TypeScript projects)

Resources

• Documentation — Guides, API reference, and examples
• Getting Started — Setup in 5 minutes
• API Reference — Every endpoint documented
• Examples — Express, Next.js App Router, Pages Router

Examples

| Example | Description | |---|---| | express-simple | Basic Express.js integration | | express-production | Production-ready with conversation flows, DB, and queues | | nextjs-app-router | Next.js App Router integration | | nextjs-pages-router | Next.js Pages Router integration |

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see the LICENSE file for details.