meta-cloud-api

The actively maintained TypeScript SDK for the official WhatsApp Cloud API.

Meta archived their own Node.js SDK in 2023. This one kept going.

Docs · Playground · Getting Started

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.