Skip to main content
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 install @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:
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);
  }
}

​
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