> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wsapi.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js / TypeScript SDK

> TypeScript/JavaScript SDK for integrating WSAPI into Node.js applications

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

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @wsapichat/client
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @wsapichat/client
    ```
  </Tab>
</Tabs>

## 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

```typescript theme={null}
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:

<Tabs>
  <Tab title="Exception-based">
    Methods throw exceptions on failure. Use standard `try/catch`:

    ```typescript theme={null}
    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);
      }
    }
    ```
  </Tab>

  <Tab title="Try-based (non-throwing)">
    Methods prefixed with `try` return an `ApiResponse` object instead of throwing:

    ```typescript theme={null}
    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);
    }
    ```
  </Tab>
</Tabs>

## Receiving events via SSE

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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
// 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](https://github.com/wsapi-chat/wsapi-node)