Business WhatsApp API

Overview

business-whatsapp-api is a TypeScript SDK for the WhatsApp Cloud API. It offers full ESM and CommonJS support, enabling developers to integrate WhatsApp messaging with type safety, a fluent builder API, and extensive utilities.

---

Features

• Full TypeScript typings with exhaustive type definitions.
• Compatibility with both ESM and CommonJS module systems.
• Fluent builders for messages, templates, and interactive flows.
• Robust validation and error handling.
• Webhook handling utilities.
• Media upload and management helpers.
• Business account management and user‑preferences handling.
• Modular architecture for selective imports, keeping bundle size low.
• Built‑in rate‑limiting and retry logic.
• Detailed logging and debugging helpers.

---

Installation

npm install business-whatsapp-api

---

API Version

The SDK uses Facebook Graph API version v23.0 by default. You can override it via an environment variable:

process.env.FB_GRAPH_API_VERSION = "<latest_version>"

---

Quick Start

// ESM example
import { WhatsAppClient } from "business-whatsapp-api";
import { text } from "business-whatsapp-api/messages";
import { template } from "business-whatsapp-api/templates";

const client = new WhatsAppClient("phone_number_id", "access_token");

// Send a simple text message
const msg = text()
  .to("1234567890")
  .body("Hello, World!")
  .build();
await client.sendMessage(msg);

// Send a template message
const tmpl = template()
  .name("shipping_confirmation")
  .language("en_US")
  .addBody([parameter().text("Your order has been shipped!").build()])
  .build();
await client.sendTemplate(tmpl);

---

Module Structure

• client – Core client handling authentication, request signing, and HTTP transport.
• messages – Builders for text, media, location, contacts, and interactive messages.
• templates – Helpers for constructing template payloads.
• flows – High‑level abstractions for button/quick‑reply flows.
• filters – Utilities to filter inbound webhook events.
• handlers – Pre‑built webhook verification and message handlers.
• listeners – Async listeners that emit typed events for custom logic.
• utils – Miscellaneous helpers (e.g., media upload, URL signing).
• types – Full TypeScript definitions for all public APIs.

---

Advanced Usage

Selective Imports

import { text } from "business-whatsapp-api/messages"; // only pulls in message builders

Media Upload

import { uploadMedia } from "business-whatsapp-api/utils";
const mediaId = await uploadMedia({
  type: "image",
  path: "./logo.png",
});

Error Handling

All SDK methods throw WhatsAppError with code and details properties.

try {
  await client.sendMessage(msg);
} catch (err) {
  if (err instanceof WhatsAppError && err.code === "RATE_LIMIT") {
    // implement exponential back‑off
  }
}

---

Comparison with Other Packages

Feature	business-whatsapp-api	whatsapp-web.js	twilio-whatsapp
TypeScript typings	✅ Full	❌ Limited	✅ Partial
ESM support	✅	❌	✅
Fluent builder API	✅	❌	❌
Webhook utilities	✅	❌	✅
Media upload helpers	✅	✅	✅
Rate‑limit handling	✅	❌	✅
Package size (min.)	~30 KB	~45 KB	~55 KB

The SDK stands out for its type‑safe, chainable API and modular imports, offering a rich feature set while keeping bundle size low.

---

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests for new features, bug fixes, documentation improvements, or test coverage enhancements.

---

License

Distributed under the MIT License. See the LICENSE file for details.