Waappa Node.js SDK

Official Node.js / TypeScript SDK for the Waappa API.

Installation

npm install waappa-sdk

Requires Node.js 18 or newer.

Quick Start

import { WaappaClient } from "waappa-sdk";

const waappa = new WaappaClient({
  apiKey: process.env.WAAPPA_API_KEY!,
  session: process.env.WAAPPA_SESSION || "default"
});

await waappa.sendText({
  chatId: "[email protected]",
  text: "Hello from Waappa"
});

The SDK sends the API key as the Authorization header. By default it uses:

https://api.waappa.com

Use baseUrl for local or private deployments:

const waappa = new WaappaClient({
  apiKey: "waappa_session_api_key",
  session: "default",
  baseUrl: "http://localhost:3001"
});

Messages

await waappa.sendImage({
  chatId: "[email protected]",
  caption: "Invoice",
  file: {
    mimetype: "image/jpeg",
    filename: "invoice.jpg",
    url: "https://example.com/invoice.jpg"
  }
});

await waappa.sendPoll({
  chatId: "[email protected]",
  poll: {
    name: "Choose one",
    options: ["A", "B"],
    multipleAnswers: false
  }
});

Supported message helpers:

• sendText
• sendImage
• sendVoice
• sendVideo
• sendFile
• sendPoll
• sendList
• sendContactVcard
• sendLocation
• sendEvent
• editMessage
• deleteMessage
• getMessages
• downloadMessageMedia

Media Upload

const formData = new FormData();
formData.append("file", file);

const uploaded = await waappa.upload(formData);

Use the returned URL in sendImage, sendVideo, sendVoice, or sendFile.

Media Download

const media = await waappa.downloadMessageMedia("[email protected]_3EB0...");

The response contains url, size_bytes, and content_type. The URL is stored in Waappa temporary media storage and can be used like an uploaded media URL.

Groups, Contacts, Labels, LIDs, Channels

await waappa.createGroup({
  name: "Support",
  participants: ["[email protected]"]
});

const contacts = await waappa.listContacts();
const labels = await waappa.listLabels();
const channels = await waappa.listChannels();

The client includes helpers for the selected Waappa API surface: groups, group participants, contacts, labels, LID/phone resolution, and channels.

Admin / Session Management

Session management methods require a master key:

const admin = new WaappaClient({
  apiKey: process.env.WAAPPA_MASTER_KEY!,
  authMode: "master"
});

const sessions = await admin.listSessions();

Errors

Failed API responses throw WaappaError:

import { WaappaClient, WaappaError } from "waappa-sdk";

try {
  await waappa.sendText({ chatId: "bad", text: "Hello" });
} catch (error) {
  if (error instanceof WaappaError) {
    console.log(error.status);
    console.log(error.data);
  }
}

Development

npm install
npm run build
npm pack --dry-run

Publishing

npm publish --access public

Before publishing, run a smoke test against a real Waappa API key and session.