Meta Cloud API
Meta Cloud API - A powerful TypeScript wrapper for Meta's Cloud API, providing a clean and type-safe interface for WhatsApp Business Platform integration.

Resources
Features
- Type-Safe Development - Built with TypeScript to provide code completion and catch errors during development
- Comprehensive Coverage - Full support for WhatsApp Business Platform APIs including Messages, Media, Templates, Flows, and more
- Modular Architecture - Clean separation of concerns with dedicated API classes for each domain
- Framework-Specific Webhooks - Built-in support for Express.js and Next.js webhook handling
- Advanced Features - Support for Flows, Encryption, QR Codes, Two-Step Verification, and WABA management
- Error Handling - Standardized error handling with detailed Meta API error information
Installation
npm install meta-cloud-api
yarn add meta-cloud-api
pnpm add meta-cloud-api
Quick Start
import WhatsApp, { MessageTypesEnum } from 'meta-cloud-api';
const client = new WhatsApp({
accessToken: process.env.CLOUD_API_ACCESS_TOKEN,
phoneNumberId: Number(process.env.WA_PHONE_NUMBER_ID),
businessAcctId: process.env.WA_BUSINESS_ACCOUNT_ID
});
const response = await client.messages.text({
to: '+1234567890',
body: 'Hello from Meta Cloud API!'
});
console.log(`Message ID: ${response.messages[0].id}`);
Usage Examples
Messaging
Text Message
const result = await client.messages.text({
to: "15551234567",
body: "Hello from Meta Cloud API!"
});
Template Message
import { ComponentTypesEnum, LanguagesEnum, ParametersTypesEnum } from 'meta-cloud-api';
const result = await client.messages.template({
to: "15551234567",
body: {
name: "shipping_confirmation",
language: {
code: LanguagesEnum.English_US,
policy: "deterministic"
},
components: [
{
type: ComponentTypesEnum.Body,
parameters: [
{
type: ParametersTypesEnum.Text,
text: "John Doe"
},
{
type: ParametersTypesEnum.Text,
text: "12345"
}
]
}
]
}
});
Media Message
const result = await client.messages.image({
to: "15551234567",
body: {
link: "https://example.com/image.jpg"
}
});
Interactive Message
import { InteractiveTypesEnum } from 'meta-cloud-api';
const result = await client.messages.interactive({
to: "15551234567",
body: {
type: InteractiveTypesEnum.Button,
body: {
text: "What would you like to do?"
},
action: {
buttons: [
{
type: "reply",
reply: {
id: "help_button",
title: "Get Help"
}
},
{
type: "reply",
reply: {
id: "info_button",
title: "Account Info"
}
}
]
}
}
});
Webhook Integration
Express.js Webhook
import express from 'express';
import { MessageTypesEnum } from 'meta-cloud-api';
import { webhookHandler } from 'meta-cloud-api/webhook/express';
const app = express();
const bot = webhookHandler({
accessToken: process.env.CLOUD_API_ACCESS_TOKEN!,
phoneNumberId: parseInt(process.env.WA_PHONE_NUMBER_ID!),
webhookVerificationToken: process.env.WEBHOOK_VERIFICATION_TOKEN!,
});
bot.processor.onMessage(MessageTypesEnum.Text, async (whatsapp, message) => {
await whatsapp.messages.text({
to: message.from,
body: `Echo: ${message.text?.body}`,
});
});
app.get('/webhook', bot.webhook);
app.post('/webhook', express.json(), bot.webhook);
app.listen(3000);
Next.js Webhook
import { NextApiRequest, NextApiResponse } from 'next';
import { MessageTypesEnum } from 'meta-cloud-api';
import { webhookHandler } from 'meta-cloud-api/webhook/nextjs';
const bot = webhookHandler({
accessToken: process.env.CLOUD_API_ACCESS_TOKEN!,
phoneNumberId: parseInt(process.env.WA_PHONE_NUMBER_ID!),
webhookVerificationToken: process.env.WEBHOOK_VERIFICATION_TOKEN!,
});
bot.processor.onMessage(MessageTypesEnum.Text, async (whatsapp, message) => {
await whatsapp.messages.text({
to: message.from,
body: `Echo: ${message.text?.body}`,
});
});
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
return bot.webhook(req, res);
}
Advanced Message Handling
import { MessageTypesEnum } from 'meta-cloud-api';
bot.processor.onMessagePreProcess(async (whatsapp, message) => {
await whatsapp.messages.markAsRead({ messageId: message.id });
});
bot.processor.onMessage(MessageTypesEnum.Text, async (whatsapp, message) => {
});
bot.processor.onMessage(MessageTypesEnum.Image, async (whatsapp, message) => {
});
bot.processor.onMessage(MessageTypesEnum.Document, async (whatsapp, message) => {
});
bot.processor.onMessageStatus(async (whatsapp, status) => {
console.log(`Message ${status.id} status: ${status.status}`);
});
Templates Management
const templates = await client.templates.list({
businessId: process.env.WA_BUSINESS_ACCOUNT_ID
});
const newTemplate = await client.templates.create({
businessId: process.env.WA_BUSINESS_ACCOUNT_ID,
name: "welcome_message",
category: "MARKETING",
components: [
{
type: "HEADER",
format: "TEXT",
text: "Welcome!"
},
{
type: "BODY",
text: "Hi {{1}}, welcome to our service!"
}
],
language: "en_US"
});
Media Management
import fs from 'fs';
const mediaUpload = await client.media.upload({
file: fs.createReadStream("./path/to/image.jpg"),
type: "image/jpeg"
});
const media = await client.media.get({
mediaId: mediaUpload.id
});
const mediaBuffer = await client.media.download({
mediaId: mediaUpload.id
});
Business Profile Management
const profile = await client.businessProfile.update({
about: "We provide the best service!",
address: "123 Business St, City",
description: "Premium products and services",
email: "contact@business.com",
websites: ["https://www.business.com"]
});
const currentProfile = await client.businessProfile.get();
WhatsApp Flows
const flow = await client.flows.create({
name: "Customer Survey",
categories: ["SURVEY"],
clone_flow_id: "existing_flow_id"
});
const updatedFlow = await client.flows.update({
flowId: flow.id,
name: "Updated Survey",
categories: ["SURVEY", "FEEDBACK"]
});
Example Projects
We provide ready-to-use example projects demonstrating integration with different frameworks:
A simple echo bot that responds to any text message. Perfect for getting started!
cd examples/express-example
npm install
cp env.example .env
npm run dev
Next.js implementation with API routes for webhook handling.
cd examples/nextjs-page-router-example
npm install
cp env.example .env.local
npm run dev
Modular Imports
Use specific imports for better tree-shaking:
import { MessagesApi } from 'meta-cloud-api/messages';
import { MediaApi } from 'meta-cloud-api/media';
import { TemplateApi } from 'meta-cloud-api/template';
import { webhookHandler } from 'meta-cloud-api/webhook/express';
import { webhookHandler } from 'meta-cloud-api/webhook/nextjs';
import { MessageTypesEnum, InteractiveTypesEnum } from 'meta-cloud-api/types/enums';
import type { WhatsAppConfig } from 'meta-cloud-api/types/config';
Configuration
interface WhatsAppConfig {
accessToken: string;
phoneNumberId: number;
businessAcctId?: string;
apiVersion?: string;
webhookVerificationToken?: string;
requestTimeout?: number;
}
Error Handling
try {
const result = await client.messages.text({
to: "15551234567",
body: "Hello World"
});
} catch (error) {
if (error.response?.data?.error) {
console.error('Meta API Error:', error.response.data.error);
} else {
console.error('Network Error:', error.message);
}
}
Requirements
- Node.js 18 LTS or later
- TypeScript 4.5+ (for TypeScript projects)
Contributing
We welcome contributions! Please see our Contributing Guide for details.
License
This project is licensed under the MIT License - see the LICENSE file for details.