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-cloud-api | |---|---| | Type Safety | Full TypeScript strict mode — every request and response is typed | | 17 API Modules | Messages, Media, Templates, Flows, Groups, Calling, Payments, and more | | Webhook Adapters | Built-in support for Express.js and Next.js (App Router & Pages Router) | | Modular | Tree-shakeable imports, use only what you need | | Production Ready | Error handling, typed error classes, rate limit support | | Official API | Built on the official WhatsApp Business Platform Cloud API |

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.