wapi-cloud

Getting started

Introduction

wapi-cloud is a promise-based, fully-typed Node.js wrapper for integrating the WhatsApp Cloud API (Meta Graph API) into your applications.

Most Graph API wrappers hand you raw HTTP responses and let you figure out the rest — inconsistent error shapes, no types, and a pagination scheme you re-implement in every project. wapi-cloud wraps the full WhatsApp Cloud API surface — messages, templates, media, contacts, catalogs, products, commerce settings, flows, QR codes, analytics, embedded signup, and account management — behind a single typed client that never throws.

Why wapi-cloud

  • Fully typed. First-class TypeScript support, with error checks that narrow the response type correctly without type casts.
  • Never throws. Every call resolves to a consistent { data, error } result, Supabase-style.
  • Batteries included. Messages, templates, media, contacts, catalogs, products, commerce settings, flows, QR codes, analytics, embedded signup, and webhooks in one unified client.
  • Webhook helpers. Signature verification, event parsing, typed event dispatchers, and an Express one-liner.
  • Auto-pagination. for await over any list endpoint.
  • Tree-shakeable. Ships as ESM + CJS with .d.ts via tsup.

A 30-second look

index.ts
import { Whatsapp } from "wapi-cloud";

const whatsapp = new Whatsapp({
  accessToken: process.env.WA_TOKEN!,
  phoneNumberId: process.env.WA_PHONE_ID!,
  businessAccountId: process.env.WA_WABA_ID!, // for templates/flows/analytics
  appSecret: process.env.WA_APP_SECRET!,      // for webhook signatures
});

const { data, error } = await whatsapp.messages.sendText(
  "15551234567",
  { body: "Hello from wapi-cloud!" }
);

if (error) {
  console.error(error.code, error.type, error.message);
} else {
  console.log("Sent message ID:", data.messageId);
  console.log("Recipient WA ID:", data.waId);
}
wapi-cloud is a thin, typed layer over Meta's Graph API — it does not proxy or replace it. You'll still need a WhatsApp Business Account, a phone number ID, and an access token from Meta for Developers.

Module Surface

The SDK exposes 14 dedicated sub-modules organized cleanly by functionality:

whatsapp.messages

Send text, media, templates, interactive buttons/lists/CTA, carousels, contacts, location, reactions, and flows.

whatsapp.templates

Create, list, auto-paginate, get, update and delete message templates including carousels and SPM templates.

whatsapp.media

Upload media files, retrieve metadata with temp download URLs, download raw binary data, and delete assets.

whatsapp.contacts

Check WhatsApp registration validity for phone numbers, block users, unblock users, and list blocked contacts.

whatsapp.phoneNumbers

List, get, register with 2FA PIN, deregister, request SMS/voice verification codes, and verify phone numbers.

whatsapp.businessProfile

Read and update your WhatsApp Business profile details: about, address, description, email, websites, industry, and picture.

whatsapp.twoStepVerification

Set or update the 6-digit PIN used to re-register and secure a phone number on WhatsApp Cloud API.

whatsapp.catalogs

List Meta product catalogs, look up catalog details, verify WABA catalog connections, and send product messages.

whatsapp.products

List, get, create, update and delete catalog products with price, currency, availability, condition, and imagery.

whatsapp.commerceSettings

Check and configure WhatsApp commerce settings: toggle catalog visibility and enable/disable the in-chat cart.

whatsapp.flows

Create, list, update Flow JSON asset files, publish, deprecate, and delete native in-chat interactive WhatsApp Flows.

whatsapp.qrCodes

Create, list, get, update and delete deep link QR codes with pre-filled messages that launch a WhatsApp chat.

whatsapp.analytics

Query messaging analytics, conversation volume, and pricing analytics for your WABA by date range and granularity.

whatsapp.embeddedSignup

Generate client-side onboarding login scripts, exchange OAuth code for system user tokens, and subscribe to WABAs.

Where to go next

Head to Installation to add the package, then Quick start to send your first message in a few minutes.