Install and configure WhatsApp-Meta-Business-API-Handler

Follow the source instructions for WhatsApp-Meta-Business-API-Handler. Read the prerequisites and configuration steps before running an example.

Installation

1npm install @your-package/whatsapp-handler
2# or
3yarn add @your-package/whatsapp-handler

Requirements

Node.js 16+
WhatsApp Business API credentials
Meta Business Account

Quick Start

Basic Setup

1import { createWhatsAppHandler } from './whatsapp-handler';
2 
3const whatsapp = createWhatsAppHandler({
4  token: 'YOUR_ACCESS_TOKEN',
5  phoneNumberId: 'YOUR_PHONE_NUMBER_ID',
6  webhookVerifyToken: 'YOUR_VERIFY_TOKEN'
7});
8 
9// Send a message
10await whatsapp.sendMessage('1234567890', 'Hello from WhatsApp!');

Using Environment Variables

1import { createWhatsAppHandlerFromEnv } from './whatsapp-handler';
2 
3// Reads from process.env automatically
4const whatsapp = createWhatsAppHandlerFromEnv();

Required environment variables:

1WHATSAPP_TOKEN=your_access_token
2WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
3WHATSAPP_WEBHOOK_VERIFY_TOKEN=your_verify_token
4WHATSAPP_APP_SECRET=your_app_secret

Webhook Setup

Express.js

1import express from 'express';
2 
3const app = express();
4app.use(express.json());
5 
6// Use as middleware
7app.post('/webhook', whatsapp.expressMiddleware());
8app.get('/webhook', whatsapp.expressMiddleware());
9 
10app.listen(3000, () => {
11  console.log('Webhook server running on port 3000');
12});

Next.js (App Router)

1// app/api/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3 
4export async function POST(req: NextRequest) {
5  const body = await req.json();
6  
7  const result = await whatsapp.processWebhook({
8    method: 'POST',
9    headers: Object.fromEntries(req.headers),
10    body,
11    query: Object.fromEntries(req.nextUrl.searchParams)
12  });
13 
14  return NextResponse.json(result.data, { status: result.status });
15}
16 
17export async function GET(req: NextRequest) {
18  const result = await whatsapp.processWebhook({
19    method: 'GET',
20    headers: Object.fromEntries(req.headers),
21    query: Object.fromEntries(req.nextUrl.searchParams)
22  });
23 
24  if (result.challenge) {
25    return new NextResponse(result.challenge, { status: 200 });
26  }
27 
28  return NextResponse.json(result.data, { status: result.status });
29}

Next.js (Pages Router)

1// pages/api/webhook.ts
2import type { NextApiRequest, NextApiResponse } from 'next';
3 
4export default async function handler(
5  req: NextApiRequest,
6  res: NextApiResponse
7) {
8  await whatsapp.nextjsHandler(req, res);
9}

Standalone HTTP Server

1// Start built-in server
2const server = whatsapp.startWebhookServer(3000, '/webhook', () => {
3  console.log('Webhook server started on port 3000');
4});
5 
6// Stop server
7await whatsapp.stopWebhookServer();

Generic/Universal Handler

1// Works with any framework
2const result = await whatsapp.processWebhook({
3  method: 'POST',
4  headers: req.headers,
5  body: req.body,
6  query: req.query,
7  rawBody: req.rawBody
8});

Configuration

Configuration Options

Option	Type	Default	Description
`token`	`string`	Required	WhatsApp API access token
`phoneNumberId`	`string`	Required	Your WhatsApp phone number ID
`businessAccountId`	`string`	Optional	Business account ID
`version`	`string`	`'v21.0'`	API version
`appSecret`	`string`	Optional	App secret for signature verification
`webhookVerifyToken`	`string`	Optional	Token for webhook verification
`apiTimeout`	`number`	`30000`	API request timeout (ms)
`maxRetries`	`number`	`3`	Max retry attempts for failed requests
`autoMarkRead`	`boolean`	`true`	Auto-mark messages as read
`autoProcessMessages`	`boolean`	`true`	Auto-process incoming messages
`queueEnabled`	`boolean`	`true`	Enable message queue
`maxQueueSize`	`number`	`1000`	Maximum queue size

Full Configuration Example

1const whatsapp = createWhatsAppHandler({
2  token: 'YOUR_TOKEN',
3  phoneNumberId: 'YOUR_PHONE_ID',
4  businessAccountId: 'YOUR_BUSINESS_ID',
5  version: 'v21.0',
6  appSecret: 'YOUR_APP_SECRET',
7  webhookVerifyToken: 'YOUR_VERIFY_TOKEN',
8  apiTimeout: 30000,
9  maxRetries: 3,
10  autoMarkRead: true,
11  autoProcessMessages: true,
12  queueEnabled: true,
13  maxQueueSize: 1000,
14  storage: {
15    type: 'memory',
16    autoCleanup: true,
17    maxMessagesPerConversation: 1000
18  },
19  webhook: {
20    verifyToken: 'YOUR_VERIFY_TOKEN',
21    appSecret: 'YOUR_APP_SECRET',
22    autoProcess: true,
23    autoMarkRead: true,
24    verifySignature: true,
25    maxBodySize: 10485760, // 10MB
26    timeout: 30000
27  }
28});

Check the installation

After setup, continue with the first example. If a command fails, compare the runtime version, working directory, and required configuration with the original README before changing dependencies.

Source and help

The catalog identifies the license as MIT. Read the repository license before redistributing source or assets.