v1 · MIT licensed · open source

WhatsApp messaging,
with wapi-cloud

wapi-cloud is a promise-based, fully-typed Node.js wrapper for the WhatsApp Cloud API. Every call resolves to { data, error } — never throws, never surprises.

Read the docs

npm install wapi-cloud

ESM + CJSZero runtime dependencies*Node.js 18+

Jordan Silva

+1 555 123 4567

live

Hi Jordan — your order is confirmed 🎉

queued

// resolved, never thrown

const { data, error } = await whatsapp.send(...)

… awaiting receipt

why wapi-cloud

Built like the SDK you wish Meta shipped.

Fully typed

First-class TypeScript support end to end. Error checks narrow the result type correctly, no `as` required.

Never throws

Every call resolves to a consistent { data, error } result, Supabase-style. No try/catch for expected API failures.

Batteries included

Messages, templates, media, contacts, catalogs, products, commerce settings, flows, QR codes, analytics, and embedded signup.

Webhook helpers

Signature verification, event parsing, and an Express one-liner so you can stop hand-rolling HMAC checks.

Auto-pagination

`for await` over any list endpoint. wapi-cloud walks the cursor for you, page by page.

Tree-shakeable

Ships as ESM + CJS with .d.ts via tsup. Import only the modules you call.

the api

Reads like the message it sends.

One client, every endpoint. Switch tabs to see messages, templates, interactive buttons and webhooks side by side.

send.ts

import { Whatsapp } from "wapi-cloud";

const whatsapp = new Whatsapp({
  accessToken: process.env.WA_TOKEN!,
  phoneNumberId: process.env.WA_PHONE_ID!,
});

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

if (error) throw new Error(error.message);
console.log("Sent message ID:", data.messageId);

error handling

Every call is a result, not a risk.

data and error are mutually exclusive, so TypeScript narrows correctly the moment you check error. Every response also carries status, statusText and raw — the untouched Graph API JSON — as an escape hatch.

Config-only failures (like a missing businessAccountId) also come back as { data: null, error }, never a thrown exception.
error.isRetryable tells you whether it's safe to retry the exact same call.
error.fbtraceId is ready to hand to Meta support, no digging through logs.

templates.ts

const { data: templates, error } = await whatsapp.templates.list();

if (error) {
  console.error(error.code, error.type, error.message);
  // error.isRetryable, error.raw, error.fbtraceId also available
} else {
  console.log(templates.items);
}

module surface

The whole Graph API, namespaced.

One Whatsapp instance, 14 focused modules. Each maps to a corner of the Cloud API so your imports read like your intent.

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.

Ship your first message in under five minutes.

Install the package, drop in your access token, and send. The docs walk through everything else.

Get started View source

WhatsApp messaging,with wapi-cloud