Flaresend JavaScript SDK

Official JavaScript/TypeScript SDK for the Flaresend WhatsApp Messaging API.

Installation

npm install flaresend
# or
yarn add flaresend
# or
pnpm add flaresend

Features

• Type-safe API: Fully typed requests and responses.
• Resource-based: Intuitive organization (messages, groups, scheduled).
• Minimal Dependencies: Zero runtime dependencies, tree-shakable and minified + gzipped.
• Dual Output: Supports both ESM and CommonJS.

Quick Start

import { Flaresend } from "flaresend";

const flaresend = new Flaresend("YOUR_API_KEY");

// Send a simple text message
const result = await flaresend.messages.send({
  recipients: ["254712345678"],
  type: "text",
  text: "Hello from Flaresend SDK!",
});

console.log(result.success ? "Message sent!" : "Failed to send");

Usage

Messaging

Send Image (via URL)

await flaresend.messages.send({
  recipients: ["254712345678"],
  type: "image",
  url: "https://example.com/image.jpg",
  caption: "Beautiful sunset!",
});

Send File (using FormData - Browser/Node)

// Assuming you have a File or Blob object
await flaresend.messages.sendFile({
  recipients: ["254712345678"],
  type: "document",
  file: myFileBlob,
  fileName: "report.pdf",
});

Scheduled Messages

Schedule a message

const scheduled = await flaresend.messages.schedule({
  recipients: ["254712345678"],
  type: "text",
  text: "Happy Birthday!",
  sendAt: "2025-11-14 13:48:00",
});

List scheduled messages

const list = await flaresend.scheduled.list();

Group Management

Create a group

const group = await flaresend.groups.create({
  subject: "Dev Team",
  participants: ["254712345678", "254722334455"],
});

Send message to groups

await flaresend.groups.sendMessage({
  groupJids: ["[email protected]"],
  type: "text",
  text: "Meeting in 10 minutes!",
});

Error Handling

The SDK provides custom error classes for better error handling:

import { Flaresend, AuthenticationError, InstanceNotReadyError } from 'flaresend';

try {
  const flaresend = new Flaresend('INVALID_KEY');
  await flaresend.messages.send({...});
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API Key');
  } else if (error instanceof InstanceNotReadyError) {
    console.error('WhatsApp instance not connected');
  }
}

Architecture

graph TD
    A[Flaresend Client] --> B[Messages Resource]
    A --> C[Groups Resource]
    A --> D[Scheduled Resource]
    A --> E[Webhooks Resource]
    B --> F[HttpClient]
    C --> F
    D --> F
    F --> G[Flaresend API]

License

MIT