WhatsApp API for Node.js

Published on npm as wasaas (version 0.1.0). No runtime dependencies, so it adds nothing to your dependency tree beyond itself.

npm install wasaas

Create an API key in the dashboard under API Keys. Keys are prefixed wsa_, and the client rejects anything else at construction time rather than failing on your first request.

import { Wasaas } from "wasaas";

const client = new Wasaas({
  apiKey: process.env.WASAAS_API_KEY, // must start with wsa_
});

A baseUrl option exists and defaults to https://wasaas.org; you only need it when pointing at a different environment.

You need the session ID of a connected WhatsApp number — visible in the dashboard once you scan the QR code, and also returned by client.sessions.list(). Recipients are in international format without a leading +.

const res = await client.messages.sendText({
  sessionId: "customer-5-1",
  to: "966501234567",
  message: "Your order has shipped.",
});

// { success: true, to: "966501234567", status: "sent" }

Images are sent by URL. Documents are sent as base64, which means you can generate an invoice or report in memory and deliver it without hosting the file publicly first.

await client.messages.sendImage({
  sessionId: "customer-5-1",
  to: "966501234567",
  imageUrl: "https://example.com/receipt.png",
  caption: "Your receipt",           // optional
});

await client.messages.sendDocument({
  sessionId: "customer-5-1",
  to: "966501234567",
  base64: pdfBuffer.toString("base64"),
  filename: "invoice-1042.pdf",
  mime: "application/pdf",
});

Text, images and documents are the supported message types. Audio, location pins and interactive buttons are not available.

Not every phone number has WhatsApp. Validating first keeps failed sends out of your logs and out of your quota.

const check = await client.numbers.validate({
  sessionId: "customer-5-1",
  phone: "966501234567",
});

if (check.has_whatsapp) {
  // safe to send
}

Non-2xx responses throw WasaasAPIError, which carries the HTTP status and, when the API supplies one, a detail string. It extends WasaasError, so you can catch either.

import { WasaasAPIError } from "wasaas";

try {
  await client.messages.sendText({ sessionId, to, message });
} catch (err) {
  if (err instanceof WasaasAPIError) {
    // 401 invalid key · 404 session not found · 429 quota exceeded
    console.error(err.status, err.message, err.detail);
    return;
  }
  throw err;
}

A 429 means the plan's monthly message quota is spent — see WhatsApp API pricing for the per-plan allowances.