WSApi.Client (TypeScript SDK)

A TypeScript/JavaScript SDK for integrating with the WSApi API, enabling developers to send WhatsApp messages, manage groups and chats, and receive real-time events via Webhooks or Server-Sent Events (SSE).

Features

• HTTP Client: Simple, strongly-typed client for all API commands (messages, groups, chats, contacts, etc).
• Events: Receive real-time events from the API via:
  • Webhooks: Configure your endpoint to receive HTTP POST events.
  • SSE: Use the built-in SSE client to receive events over a persistent connection.
• TypeScript Support: Full type safety with comprehensive TypeScript definitions.
• Dual Error Handling: Both throwing and non-throwing method variants for flexible error handling.
• Cross-Platform: Works in Node.js, browsers, and other JavaScript environments.

Getting Started

Prerequisites

• Node.js 16.0 or later (for Node.js environments)
• Modern browser with fetch API support (for browser environments)
• Access to the WSApi API (Valid instance with ID and API key)

Installation

From NPM

npm install @wsapichat/client

Or using Yarn:

yarn add @wsapichat/client

Usage

1. Basic Setup

import { HttpClient, 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: '[email protected]', // Phone number in WhatsApp format
  text: 'Hello from TypeScript SDK!',
});

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

2. Error Handling

The SDK provides two methods for each API call to handle different error scenarios:

Exception-based (throws on error)

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);
  }
}

ApiResponse-based (no exceptions)

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);
}

3. Receiving Events via SSE

import { WSApiClientFactory, EventFactory } from '@wsapi/client';

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;

      // Handle other event types as needed
    }
  } 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();

4. Verifying Webhook Signatures

When receiving events via webhooks, verify the X-Webhook-Signature header to ensure the payload is authentic. The signature is an HMAC-SHA256 digest of the raw request body, using your instance's signing secret.

import { verifySignature, EventFactory } from '@wsapichat/client';

const SIGNING_SECRET = process.env.WEBHOOK_SIGNING_SECRET!;

// In your HTTP handler — use the raw body bytes, not a re-parsed version
const isValid = verifySignature(rawBody, SIGNING_SECRET, req.headers['x-webhook-signature']);

if (!isValid) {
  res.writeHead(401);
  res.end('Invalid signature');
  return;
}

const event = EventFactory.parseEvent(rawBody.toString());

Important: The signature must be verified against the raw request body bytes, before any JSON parsing. Use constant-time comparison (handled internally by the SDK) to prevent timing attacks.

License

MIT