@wapi/sdk

TypeScript SDK for WAPI — a self-hostable, multi-session WhatsApp API server.

npm i @wapi/sdk
# or
pnpm add @wapi/sdk

Node 20+ or any modern browser. Uses native fetch and WebSocket.

Quick start

import { WapiClient, WapiSocket } from "@wapi/sdk";

const wapi = new WapiClient({
  baseUrl: "http://localhost:3000",
  apiKey: process.env.WAPI_KEY!,
});

await wapi.request("POST", "/v1/messages/text", {
  body: { to: "[email protected]", body: "hello" },
});

const ws = new WapiSocket({
  baseUrl: "ws://localhost:3000",
  sessionId: "clxxx...",
  apiKey: process.env.WAPI_KEY!,
});

ws.on((evt) => {
  if (evt.event === "message.received") console.log(evt.data.body);
});

ws.open();

What's included

• WapiClient — typed fetch wrapper with bearer auth, JSON handling, and WapiError class for non-2xx responses.
• WapiSocket — WebSocket helper with subprotocol auth, ping/pong heartbeat, exponential reconnect, typed event listeners.
• Generated types — request/response types from the OpenAPI spec, available at @wapi/sdk/types.

Error handling

Every non-2xx response throws WapiError:

import { WapiError } from "@wapi/sdk";

try {
  await wapi.request("POST", "/v1/messages/text", { body });
} catch (e) {
  if (e instanceof WapiError && e.code === "RATE_LIMITED") {
    // retry with same Idempotency-Key after e.details.retryAfterMs
  }
}

Branch on e.code, never on e.status. Full code list: WAPI error codes.

Documentation

Full SDK guide and API reference: docs/sdk/README.md.

License

MIT. See LICENSE.

Links

• Repo: https://github.com/zakirkun/wapi
• Issues: https://github.com/zakirkun/wapi/issues
• Server docs: https://github.com/zakirkun/wapi/tree/main/docs