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 via webhooks or Server-Sent Events (SSE).

Installation

npm
yarn

npm install @wsapichat/client

yarn add @wsapichat/client

Requirements

Node.js 16.0 or later (server environments)
Modern browser with Fetch API support (browser environments)
Valid WSAPI API key and instance ID

Quick start

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

const client = WSApiClientFactory.create({
  apiKey: "your-api-key",
  instanceId: "your-instance-id",
});

// Send a text message
const result = await client.messages.sendText({
  to: "1234567890@s.whatsapp.net",
  text: "Hello from TypeScript SDK!",
});

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

Features

HTTP Client — strongly-typed client supporting all API operations across messages, groups, chats, and contacts
Real-time Events — dual event delivery through webhooks (HTTP POST) or SSE with persistent connections
TypeScript Support — complete type safety with comprehensive type definitions
Error Handling — both exception-throwing and non-throwing variants for each API method
Cross-Platform — compatible with Node.js, browsers, and other JavaScript runtimes

Error handling

The SDK provides two error handling patterns:

Exception-based
Try-based (non-throwing)

Methods throw exceptions on failure. Use standard try/catch:

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

try {
  const result = await client.messages.sendText(request);
  console.log("Message sent with ID:", result.messageId);
} catch (error) {
  if (error instanceof ApiException) {
    console.log("Failed to send message:", error.problem.detail);
  }
}

Methods prefixed with try return an ApiResponse object instead of throwing:

const response = await client.messages.trySendText(request);
if (response.isSuccess) {
  console.log("Message sent with ID:", response.result?.messageId);
} else {
  console.log("Failed to send message:", response.error?.detail);
}

Receiving events via SSE

Connect to WSAPI’s Server-Sent Events stream to receive real-time events without exposing a public endpoint:

import { WSApiClientFactory, EventFactory } from "@wsapichat/client";
import { MessageEvent } from "@wsapichat/client/events";

const sseClient = WSApiClientFactory.createSSEClient({
  apiKey: "your-api-key",
  instanceId: "your-instance-id",
});

sseClient.on("rawEventReceived", (args) => {
  try {
    const event = EventFactory.parseEvent(args.rawJson);

    switch (event.eventType) {
      case "message":
        const messageEvent = event as MessageEvent;
        console.log("Message received:", messageEvent.text);
        break;
      case "logged_in":
        console.log("Session logged in");
        break;
      case "logged_out":
        console.log("Session logged out");
        break;
    }
  } catch (error) {
    console.error("Error parsing event:", error);
  }
});

sseClient.on("connectionStateChanged", (args) => {
  console.log("Connection state changed to:", args.state);
  if (args.error) {
    console.error("Connection error:", args.error);
  }
});

// Start the SSE client
await sseClient.start();

Available operations

Messages

await client.messages.sendText({ to, text });
await client.messages.sendImage({ to, image, caption });
await client.messages.sendVideo({ to, video, caption });
await client.messages.sendAudio({ to, audio });
await client.messages.sendDocument({ to, document, filename });
await client.messages.sendSticker({ to, sticker });
await client.messages.sendContact({ to, contacts });
await client.messages.sendLocation({ to, latitude, longitude });
await client.messages.sendLink({ to, url });
await client.messages.sendReaction({ to, messageId, reaction });
await client.messages.editMessage({ to, messageId, text });
await client.messages.deleteMessage({ to, messageId });
await client.messages.markAsRead({ to, messageId });
await client.messages.starMessage({ to, messageId });

Groups, Chats, Contacts, Session

// Groups
await client.groups.getGroups();
await client.groups.createGroup({ name, participants });
await client.groups.updateGroupName({ groupId, name });
await client.groups.updateParticipants({ groupId, participants, action });

// Chats
await client.chats.getChats();
await client.chats.getChat({ chatId });
await client.chats.archiveChat({ chatId });
await client.chats.pinChat({ chatId });

// Contacts
await client.contacts.getAll();
await client.contacts.getContact({ contactId });

// Session
await client.session.getStatus();
await client.session.getQrCode();
await client.session.getPairCode({ phoneNumber });
await client.session.logout();

GitHub

github.com/wsapi-chat/wsapi-node

Getting Started

Basics

SDKs & Libraries

Integrations

Node.js / TypeScript SDK

Installation

Requirements

Quick start

Features

Error handling

Receiving events via SSE

Available operations

Messages

Groups, Chats, Contacts, Session

GitHub

​Installation

​Requirements

​Quick start

​Features

​Error handling

​Receiving events via SSE

​Available operations

​Messages

​Groups, Chats, Contacts, Session

​GitHub

Installation

Requirements

Quick start

Features

Error handling

Receiving events via SSE

Available operations

Messages

Groups, Chats, Contacts, Session

GitHub