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

pnpm add meta-cloud-api

import WhatsApp from 'meta-cloud-api';

const wa = new WhatsApp({
    accessToken: process.env.CLOUD_API_ACCESS_TOKEN,
    phoneNumberId: 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',
    name: 'hello_world',
    language: { code: 'en_US' },
});

// Send an image
await wa.messages.image({ to: '1234567890', 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	20 modules (Messages, Flows, Calling, Payments, and more)	Messaging-focused	Personal-account features
Webhook adapters	Built-in Express.js + Next.js	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.

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.waba                  // WhatsApp Business Account management

Webhooks

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

const app = express();
app.use(express.json());

// Handler is automatically cached per phoneNumberId — safe against HMR re-evaluation
const Whatsapp = expressWebhookHandler({
    accessToken: process.env.CLOUD_API_ACCESS_TOKEN,
    phoneNumberId: process.env.WA_PHONE_NUMBER_ID,
    webhookVerificationToken: process.env.WEBHOOK_VERIFICATION_TOKEN,
});

// 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);

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 18 LTS or later
• 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.