Node.js / TypeScript SDK

The WSAPI Node.js SDK provides a strongly-typed client for sending WhatsApp messages, managing groups and chats, and receiving real-time events.

Installation

npm
yarn
pnpm

npm install @wsapichat/client

yarn add @wsapichat/client

pnpm add @wsapichat/client

Requirements

Node.js 20.0 or later
Valid WSAPI API key and instance ID

Quick start

import { WSApiClient } from "@wsapichat/client";

const client = new WSApiClient({
  baseUrl: "https://api.wsapi.chat",
  apiKey: process.env.WSAPI_API_KEY!,
  instanceId: process.env.WSAPI_INSTANCE_ID!,
});

const result = await client.messages.sendTextAsync({
  to: "1234567890@s.whatsapp.net",
  text: "Hello from the TypeScript SDK!",
});

console.log("Message sent with ID:", result.id);

baseUrl, apiKey and instanceId are all required: the constructor throws if any of them is missing. Recipients use the WhatsApp JID format, <number>@s.whatsapp.net for people and <id>@g.us for groups.

Method naming

Two conventions apply to every client:

All methods end in Async and return a Promise.
Each method has a try prefixed twin (sendTextAsync and trySendTextAsync). The plain method throws ApiException on failure; the try variant never throws and returns an ApiResponse instead.

API surface

WSApiClient groups every operation under a namespace:

Namespace	What it covers
`client.messages`	Send messages, react, edit, delete, star, pin, mark as read
`client.chats`	List chats, presence, mute, pin, archive, read state, history
`client.contacts`	List and create contacts, block list
`client.groups`	Create and manage groups, participants, invite links
`client.communities`	Communities and their linked groups
`client.newsletters`	Newsletters and subscriptions
`client.status`	Post and delete status updates
`client.users`	User info, presence, privacy settings
`client.calls`	Reject incoming calls
`client.media`	Download received media
`client.session`	QR and pairing codes, session status, logout
`client.account`	Instances and subscriptions at the account level

Error handling

Exception-based
Try-based (non-throwing)

Methods throw ApiException on failure. The API error body is available on problem:

import { ApiException } from "@wsapichat/client";

try {
  const result = await client.messages.sendTextAsync({
    to: "1234567890@s.whatsapp.net",
    text: "Hello",
  });
  console.log("Message sent with ID:", result.id);
} catch (error) {
  if (error instanceof ApiException) {
    console.log(error.problem.status, error.problem.detail);
  }
}

Methods prefixed with try return an ApiResponse instead of throwing:

const response = await client.messages.trySendTextAsync({
  to: "1234567890@s.whatsapp.net",
  text: "Hello",
});

if (response.isSuccess) {
  console.log("Message sent with ID:", response.result?.id);
} else {
  console.log(response.error?.status, response.error?.detail);
}

Sending media

Media requests use url for a remote file or data for base64 content. Documents also require filename. Use mimeType when needed (voice uses OGG; stickers use WebP). Legacy names such as imageUrl, imageBase64 and fileName remain accepted and are translated before sending; canonical fields take precedence.

// From a URL
await client.messages.sendImageAsync({
  to: "1234567890@s.whatsapp.net",
  url: "https://example.com/photo.jpg",
  mimeType: "image/jpeg",
  caption: "Our new catalogue",
});

// From base64
await client.messages.sendDocumentAsync({
  to: "1234567890@s.whatsapp.net",
  data: invoiceBuffer.toString("base64"),
  filename: "invoice-2026-04.pdf",
});

mentions, replyTo, replyToSenderId, ephemeralExpiration and isForwarded are accepted by every message type:

await client.messages.sendTextAsync({
  to: "120363000000000000@g.us",
  text: "Ready when you are @1234567890",
  mentions: ["1234567890@s.whatsapp.net"],
  replyTo: "3EB0C767D26B8F4F1C23",
});

Acting on a message

Reactions, edits, receipts and deletions take the message ID as the first argument and the rest of the payload as the second:

const chatId = "1234567890@s.whatsapp.net";
const { id } = await client.messages.sendTextAsync({ to: chatId, text: "Hi" });

await client.messages.sendReactionAsync(id, { to: chatId, reaction: "👍" });
await client.messages.sendEditTextAsync(id, { to: chatId, text: "Hi, sorry for the typo" });
await client.messages.starAsync(id, { chatId, senderId: chatId, starred: true });
await client.messages.markAsReadAsync(id, { chatId, senderId: chatId, receiptType: "read" });
await client.messages.deleteAsync(id, { chatId, senderId: chatId });

In a group, chatId is the group JID and senderId is the participant who sent the message. In a one to one chat both are the same JID.

Groups, chats, contacts and session

// Groups
const groups = await client.groups.listAsync();
const group = await client.groups.createAsync({
  name: "Release crew",
  participants: ["1234567890@s.whatsapp.net"],
});
await client.groups.updateNameAsync(group.id, { name: "Release crew Q2" });
await client.groups.getInviteLinkAsync(group.id);
await client.groups.leaveAsync(group.id);

// Chats
const chats = await client.chats.listAsync();
await client.chats.updateArchiveAsync(chatId, { archived: true });
await client.chats.updatePinAsync(chatId, { pinned: true });
await client.chats.updateReadAsync(chatId, { read: true });

// Contacts
const contacts = await client.contacts.listAsync();
await client.contacts.blockContactAsync("1234567890@s.whatsapp.net");

// Session
const status = await client.session.getSessionStatusAsync();
const qr = await client.session.getLoginQRCodeAsync();
const pairCode = await client.session.getLoginPairCodeAsync("1234567890");
await client.session.logoutAsync();

Participants are added, removed, promoted and demoted through a single call:

const update = {
  participants: ["1234567890@s.whatsapp.net"],
  action: "add" as const,
};

await client.groups.updateParticipantsAsync(group.id, update);

Receiving events

WSAPI delivers events to your own endpoint as a webhook. Point your instance at an HTTPS URL and parse the body with EventFactory. When a signing secret is configured, verifySignature checks the X-Webhook-Signature header for you, in constant time:

import express from "express";
import { EventFactory, verifySignature, type MessageEvent } from "@wsapichat/client";

const app = express();

// The raw body is required: a re-serialized JSON body breaks the signature
app.post("/wsapi/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("X-Webhook-Signature");
  if (!verifySignature(req.body, process.env.WSAPI_SIGNING_SECRET!, signature)) {
    return res.sendStatus(401);
  }

  const event = EventFactory.parseEvent(req.body.toString("utf8"));

  if (event.eventType === "message") {
    const message = event as MessageEvent;
    console.log("Message from", message.sender.id, ":", message.text);
  }

  res.sendStatus(200);
});

app.listen(3000);

EventFactory.parseEvent throws on an event type it does not know, so keep the handler in a try/catch if you want unknown events to be ignored rather than to fail the delivery. See Events for the payload envelope and the full list of event types.

Account and compatibility

Account operations are Cloud-only; the OSS administrative API is separate. Create a named Cloud instance with client.account.createSubscriptionInstanceAsync(subscriptionId, "Support") (also available in the Try variant). Session responses use isConnected, isLoggedIn and deviceId; QR text is code. Invite-link responses use link; joining via link returns id. Joining via invite returns no object (HTTP 204). To rotate a link, call getInviteLinkAsync(groupId, true). Message events, including history messages, expose optional adReferral. Persist message.adReferral?.ctwaClid when present; subsequent messages may not contain attribution.

GitHub

github.com/wsapi-chat/wsapi-node

Getting Started

Basics

SDKs & Libraries

Integrations

Node.js / TypeScript SDK

Installation

Requirements

Quick start

Method naming

API surface

Error handling

Sending media

Acting on a message

Groups, chats, contacts and session

Receiving events

Account and compatibility

GitHub

​Installation

​Requirements

​Quick start

​Method naming

​API surface

​Error handling

​Sending media

​Acting on a message

​Groups, chats, contacts and session

​Receiving events

​Account and compatibility

​GitHub

Installation

Requirements

Quick start

Method naming

API surface

Error handling

Sending media

Acting on a message

Groups, chats, contacts and session

Receiving events

Account and compatibility

GitHub