wapi-cloud

A promise-based, fully-typed Node.js wrapper for the WhatsApp Cloud API (Meta Graph API)

Documentation · Quick Start · NPM · Webhooks · Examples · Contributing

---

📚 Documentation

Full documentation is available at:

👉 Messaging API documentation The documentation site contains detailed guides and API references

---

✨ Features

• 🔒 Fully typed — first-class TypeScript support, narrows correctly on error checks
• 🧵 Never throws — every call resolves to a consistent { data, error } result, Supabase-style
• 📦 Batteries included — messages, templates, media, contacts, flows, QR codes, analytics
• 🪝 Webhook helpers — signature verification, event parsing, and an Express one-liner
• 🔁 Auto-pagination — for await over any list endpoint
• 🌲 Tree-shakeable — ships as ESM + CJS with .d.ts via tsup

---

📦 Install

npm install wapi-cloud

---

🚀 Quick Start

1. Import and configure

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!,
  appSecret: process.env.WA_APP_SECRET!,
});

2. Send your first message

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

if (error) {
  console.error(error);
} else {
  console.log(data);
}

📖 Learn more

For the complete setup guide, configuration options, authentication, and examples:

👉 Read the Quick Start documentation

---

🎯 Every call returns { data, error }

No try/catch needed for expected API failures — every SDK method resolves, never throws, and gives you a consistent result object:

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

if (error) {
  console.error(error.code, error.type, error.message);

  // Additional information:
  // error.isRetryable
  // error.raw
  // error.fbtraceId
} else {
  console.log(templates.items);
}

Why this matters: data and error are mutually exclusive — TypeScript narrows correctly once you check error.

Every response also carries:

• status
• statusText
• raw

The raw property contains the untouched Graph API JSON as an escape hatch.

Config-only failures, such as calling:

whatsapp.templates.list();

without providing a businessAccountId, also return:

{
  data: null,
  error
}

rather than throwing.

---

💬 Sending Messages

Text

await whatsapp.messages.sendText(
  "15551234567",
  {
    body: "Hello!",
  }
);

Template

await whatsapp.messages.sendTemplate(
  "15551234567",
  {
    name: "order_confirmation",
    language: "en_US",
    components: [
      {
        type: "body",
        parameters: [
          {
            type: "text",
            text: "Jordan",
          },
        ],
      },
    ],
  }
);

Image

await whatsapp.messages.sendImage(
  "15551234567",
  {
    link: "https://example.com/photo.jpg",
  }
);

Interactive message

await whatsapp.messages.sendInteractive(
  "15551234567",
  {
    type: "button",
    body: "Pick one:",
    buttons: [
      {
        id: "yes",
        title: "Yes",
      },
      {
        id: "no",
        title: "No",
      },
    ],
  }
);

📚 See the complete Messaging API documentation

---

🗂 Templates, Media & Account Management

Templates

const { data } = await whatsapp.templates.create({
  name: "order_confirmation",
  category: "UTILITY",
  language: "en_US",
  components: [
    {
      type: "BODY",
      text: "Hi {{1}}, your order is confirmed.",
    },
  ],
});

Auto-pagination

for await (const template of whatsapp.templates.listAll()) {
  console.log(template.name);
}

Media

const { data: media } = await whatsapp.media.upload(
  fileBuffer,
  {
    type: "image/png",
  }
);

await whatsapp.messages.sendImage(
  to,
  {
    mediaId: media!.id,
  }
);

Full module surface

Module	Description
messages	Send WhatsApp messages
templates	Create, list, and manage message templates
media	Upload and reference media assets
contacts	Contact management
phoneNumbers	Phone number configuration
businessProfile	Business profile details
flows	WhatsApp Flows
qrCodes	QR code / short-link management
analytics	Messaging analytics
twoStepVerification	Two-step verification settings
webhooks	Webhook verification and event parsing

See src/modules/ for the full source.

📚 For detailed API documentation, visit:

https://wapi-cloud-docs.vercel.app/

---

🪝 Webhooks

Manual style

app.post(
  "/webhook",
  express.raw({
    type: "application/json",
  }),
  (req, res) => {
    if (
      !whatsapp.webhooks.verifySignature({
        payload: req.body,
        signatureHeader:
          req.headers["x-hub-signature-256"],
      })
    ) {
      return res.sendStatus(401);
    }

    const events = whatsapp.webhooks.parse(req.body);

    for (const event of events) {
      if (
        event.type === "message" &&
        event.messageType === "text"
      ) {
        whatsapp.messages.sendText(
          event.from,
          {
            body: `Echo: ${event.text.body}`,
          }
        );
      }
    }

    res.sendStatus(200);
  }
);

One-liner style

whatsapp.webhooks.handleExpress(
  app,
  "/webhook",
  {
    verifyToken: process.env.WA_VERIFY_TOKEN!,
  }
);

whatsapp.webhooks.on("message", (msg) => {
  // Handle incoming message
});

whatsapp.webhooks.on("status", (status) => {
  // Handle message status
});

📁 See examples/node-express-webhook for a full runnable server.

📚 Read the Webhooks documentation

---

📖 Documentation & Resources

Resource	Link
📚 Documentation	wapi-cloud-docs
📦 NPM Package	npmjs.com/package/wapi-cloud
💻 GitHub Repository	github.com/niyassby/wapi-cloud
📝 Examples	./examples
🤝 Contributing	CONTRIBUTING.md
📄 License	LICENSE

---

🛠 Development

Clone the repository:

git clone https://github.com/niyassby/wapi-cloud.git

cd wapi-cloud

npm install

Run type checking:

npm run typecheck

Build the package:

npm run build

The build generates:

• ESM
• CommonJS
• TypeScript declaration files

using tsup.

---

🤝 Contributing

Contributions are welcome!

Please open an issue to discuss significant changes before submitting a PR.

See CONTRIBUTING.md for contribution guidelines.

---

📄 License

MIT © wapi-cloud contributors

---

_{Built with ❤️ for developers integrating WhatsApp into their products.}

📚 Read the full documentation →