Skip to content

myusp/waha-api-client-ts

BranchesTags

Repository files navigation

waha-api-client-ts

TypeScript client library for WAHA (WhatsApp HTTP API) - Unofficial

✨ This library is fully auto-generated and maintained by GitHub Copilot

Features

  • ✅ Complete API Coverage: All 147 WAHA API endpoints implemented
  • � Auto-Generated Types: 200+ TypeScript types generated from OpenAPI schema
  • �🌐 Universal Compatibility: Works in both Node.js and browser environments
  • 🚫 Zero Dependencies: No axios or other HTTP libraries - uses native fetch API
  • 🔑 Default Configuration: Set API key, base URL, and default session on initialization
  • 🔄 Config Override: Override session, timeout, retry attempts, and retry delay per API call
  • 🔁 Automatic Retries: Built-in retry logic with configurable attempts and delays
  • 📝 Fully Typed: Complete TypeScript support with JSDoc comments
  • 🚀 Easy to Use: Simple and intuitive API
  • 🛡️ Safe Send Methods: Built-in number verification to prevent blocking

Installation

npm install waha-api-client-ts

Bundles and Compatibility

This package ships multiple bundle formats so it works both in Node.js and in web browsers:

  • dist/index.cjs.js — CommonJS (Node require)
  • dist/index.esm.js — ES Module (Node & modern bundlers)
  • dist/index.cjs.min.js / dist/index.esm.min.js — Minified versions
  • dist/index.umd.js / dist/index.umd.min.js — UMD bundle for browsers (script tag / CDN)

The package.json browser and unpkg entry point point to the UMD minified bundle for CDN usage.

Usage

Node (ESM import)

import { WAHAClient } from 'waha-api-client-ts';

const client = new WAHAClient({ baseURL: 'https://your-waha-instance.com' });

Node (CommonJS require)

const { WAHAClient } = require('waha-api-client-ts');
const client = new WAHAClient({ baseURL: 'https://your-waha-instance.com' });

Browser (ES Module)

If your app supports ES modules in the browser, you can import the ESM build directly from a bundler or local server:

<script type="module">
  import { WAHAClient } from '/node_modules/waha-api-client-ts/dist/index.esm.js';
  const client = new WAHAClient({ baseURL: 'https://your-waha-instance.com' });
  // use client...
</script>

Browser (UMD Global via CDN or local file)

Include the UMD bundle and access the library via the global name (package name or WAHA):

<script src="https://unpkg.com/waha-api-client-ts@latest/dist/index.umd.min.js"></script>
<script>
  // If package name is not a valid JS identifier the global is also available as 'WAHA'
  const client = (window.WAHA || window['waha-api-client-ts']).WAHAClient
    ? new (window.WAHA || window['waha-api-client-ts']).WAHAClient({ baseURL: 'https://...' })
    : null;
  // use client...
</script>

Development & Building

Types are generated from the included OpenAPI specification. Regenerate types and build the library with:

# regenerate types from OpenAPI
npm run generate:types

# build all bundles (CJS/ESM/UMD + d.ts)
npm run build

# or build only browser-targeted bundles
npm run build:browser

The build process will output files to dist/ including index.d.ts for TypeScript consumers.

Quick Start

import { WAHAClient } from 'waha-api-client-ts';

// Initialize client with default configuration
const client = new WAHAClient({
  baseURL: 'https://your-waha-instance.com',
  apiKey: 'your-api-key',
  session: 'default',
  timeout: 30000,
  retryAttempts: 3,
  retryDelay: 1000,
});

// Send a text message
await client.sendText({
  chatId: '1234567890@c.us',
  text: 'Hello from WAHA!',
});

Configuration

Default Configuration

When initializing the client, you can set default values:

const client = new WAHAClient({
  baseURL: 'https://your-waha-instance.com',  // Required: Your WAHA API base URL
  apiKey: 'your-api-key',                     // Optional: API key for authentication
  session: 'default',                          // Optional: Default session name (default: 'default')
  timeout: 30000,                              // Optional: Request timeout in ms (default: 30000)
  retryAttempts: 3,                            // Optional: Number of retry attempts (default: 3)
  retryDelay: 1000,                            // Optional: Delay between retries in ms (default: 1000)
});

Per-Request Configuration Override

You can override configuration for individual API calls:

await client.sendText({
  chatId: '1234567890@c.us',
  text: 'Hello!',
  config: {
    session: 'custom-session',      // Override session for this request
    timeout: 60000,                  // Override timeout for this request
    retryAttempts: 5,                // Override retry attempts
    retryDelay: 2000,                // Override retry delay
  },
});

Safe Send Methods (Avoid Blocking)

To prevent your WhatsApp account from being blocked, it's recommended to check if a number is registered on WhatsApp before sending messages. This library provides "safe send" methods that automatically implement WhatsApp's anti-blocking best practices.

Why Use Safe Send?

When you send messages to numbers that don't exist on WhatsApp, it can lead to your account being flagged or blocked. Safe send methods help prevent this by implementing the following anti-blocking measures:

  1. Number Verification: Checks if the number is registered on WhatsApp before sending
  2. Seen Receipt: Sends a "seen" indicator to appear more human-like
  3. Typing Indicators: Shows "typing..." with realistic delays based on message type and length
  4. Random Delays: Adds random delays between actions to simulate human behavior
  5. Smart Timing: Calculates appropriate delays based on message length (1-5 seconds for text, 2-6 seconds for media)

These methods return null if the number doesn't exist, preventing failed delivery attempts that could flag your account.

Delay Timings:

  • Text messages: 1-5 seconds (calculated based on message length)
  • Images: 2-4 seconds
  • Videos: 3-6 seconds
  • Files: 2-5 seconds
  • Voice, Location, Contacts, Buttons, Lists, Polls: 1.5-3 seconds

Available Safe Send Methods

All safe send methods follow the same pattern: they check the number status first, then send only if the number exists.

  • safeSendText() - Safe version of sendText()
  • safeSendImage() - Safe version of sendImage()
  • safeSendFile() - Safe version of sendFile()
  • safeSendVoice() - Safe version of sendVoice()
  • safeSendVideo() - Safe version of sendVideo()
  • safeSendLocation() - Safe version of sendLocation()
  • safeSendContactVcard() - Safe version of sendContactVcard()
  • safeSendLinkPreview() - Safe version of sendLinkPreview()
  • safeSendButtons() - Safe version of sendButtons()
  • safeSendList() - Safe version of sendList()
  • safeSendPoll() - Safe version of sendPoll()

How Safe Send Works

When you call a safe send method, the following sequence occurs automatically:

  1. Verify Number: Check if the recipient's number exists on WhatsApp
  2. Send Seen: Mark the chat as "seen" (if applicable)
  3. Start Typing: Show typing indicator in the chat
  4. Wait: Realistic delay based on message type (see "Delay Timings" above: 1-6 seconds depending on content)
  5. Stop Typing: Hide typing indicator
  6. Send Message: Deliver the actual message

This mimics human behavior and significantly reduces the risk of being flagged as a bot or spam account.

Safe Send Usage Examples

// Safe send text message with anti-blocking measures
const result = await client.safeSendText({
  chatId: '1234567890@c.us',
  text: 'Hello! How are you?',
});

if (result === null) {
  console.log('Number does not exist on WhatsApp - message not sent');
} else {
  console.log('Message sent successfully with anti-blocking measures:', result);
}

// Safe send image with anti-blocking measures
const imageResult = await client.safeSendImage({
  chatId: '1234567890@c.us',
  file: 'https://example.com/image.jpg',
  caption: 'Check this out!',
});

if (imageResult === null) {
  console.log('Number does not exist on WhatsApp - image not sent');
} else {
  console.log('Image sent successfully:', imageResult);
}

// Safe send file with anti-blocking measures
const fileResult = await client.safeSendFile({
  chatId: '1234567890@c.us',
  file: 'https://example.com/document.pdf',
  filename: 'document.pdf',
  caption: 'Important document',
});

if (fileResult === null) {
  console.log('Number does not exist on WhatsApp - file not sent');
} else {
  console.log('File sent successfully:', fileResult);
}

Anti-Blocking Best Practices

Following WhatsApp's guidelines to avoid getting blocked:

✅ DO:

  • Use safe send methods for new/unknown contacts
  • Add random delays between messages (the safe send methods do this automatically)
  • Only reply to messages, never initiate conversations with strangers
  • Send personalized messages that vary in content
  • Respect rate limits (maximum 4 messages per hour per contact is a safe guideline - exceeding this may trigger spam detection)
  • Have a profile picture and status
  • Use HTTPS URLs and avoid previously marked spam links

❌ DON'T:

  • Send messages to numbers not on WhatsApp
  • Send bulk messages without delays
  • Use the same message template repeatedly
  • Send messages 24/7 without breaks
  • Send long texts or multiple messages to new contacts
  • Ignore user reports (if users block/report you, stop messaging them)

When to Use Safe Send vs Regular Send

  • Use Safe Send when:

    • Sending to numbers from external sources (databases, forms, APIs)
    • You're not sure if the number is on WhatsApp
    • You want maximum protection against blocking
    • You're doing any form of bulk messaging
    • Initiating conversations with new contacts
    • Building a bot or automated system

  • Use Regular Send when:

    • Sending to group chats (groups don't need number verification)
    • Replying to received messages (they initiated the conversation)
    • You're certain the number exists and you have an ongoing conversation
    • You need minimal latency and have already verified the number
    • Sending to your own saved contacts from your phone

API Methods

This client implements all 147 WAHA API endpoints organized into the following categories:

🔑 Authentication (2 methods)

  • getQR() - Get QR code for pairing
  • requestCode() - Request authentication code

🖥️ Session Management (13 methods)

  • getSessions() - Get all sessions
  • getSession() - Get session info
  • createSession() - Create new session
  • updateSession() - Update session config
  • deleteSession() - Delete session
  • startSession() / startSessionAlt() - Start session
  • stopSession() / stopSessionAlt() - Stop session
  • logoutSession() / logoutSessionBulk() - Logout session
  • restartSession() - Restart session
  • getSessionMe() - Get session "me" info

🆔 Profile Management (5 methods)

  • getProfile() - Get my profile
  • setProfileName() - Set profile name
  • setProfileStatus() - Set profile status
  • setProfilePicture() - Set profile picture
  • deleteProfilePicture() - Delete profile picture

📤 Messaging (24 methods)

  • sendText() / sendTextAlt() / sendTextGet() - Send text message
  • sendImage() / sendImageAlt() - Send image
  • sendFile() / sendFileAlt() - Send file
  • sendVoice() - Send voice message
  • sendVideo() - Send video
  • sendButtons() - Send buttons
  • sendList() - Send list message
  • sendPoll() - Send poll
  • sendPollVote() - Vote in poll
  • sendLocation() - Send location
  • sendContactVcard() - Send contact vCard
  • sendLinkPreview() - Send link with preview
  • sendLinkCustomPreview() - Send link with custom preview
  • forwardMessage() - Forward message
  • reply() - Reply to message
  • replyButton() - Reply to button
  • sendSeen() - Mark as seen
  • startTyping() - Start typing indicator
  • stopTyping() - Stop typing indicator
  • reaction() - React to message
  • star() - Star/unstar message
  • getMessages() / getMessagesAlt() - Get messages
  • checkNumberStatus() - Check if number is on WhatsApp

Migration / Compatibility notes

We made the client follow the OpenAPI canonical endpoints for sending messages. Concretely:

  • The library now uses the documented POST endpoints such as POST /api/sendText, POST /api/sendImage, POST /api/sendFile, POST /api/sendVoice, and POST /api/sendVideo and includes the required session field in the request body when calling those endpoints.
  • Legacy/alternative helpers (for example sendTextGet(), getMessagesAlt(), sendTextAlt()) remain in the client for backwards compatibility but are annotated as deprecated in the source. Prefer the modern methods such as sendText() and getMessages(chatId).

If you previously relied on internal session-prefixed send URLs (e.g. /api/{session}/messages/text), update your calls to use the canonical methods above. If you need the library to retain automatic fallback to legacy endpoints (try canonical first, fallback to legacy), tell me and I can add graceful retry/fallback behavior.

💬 Chat Management (16 methods)

  • getChats() - Get all chats
  • getChatsOverview() - Get chats overview
  • createChatsOverview() - Create chats overview
  • deleteChat() - Delete chat
  • getChatPicture() - Get chat picture
  • getMessage() - Get specific message
  • deleteMessage() - Delete message
  • editMessage() - Edit message
  • deleteAllMessages() - Delete all messages
  • readMessages() - Mark messages as read
  • pinMessage() - Pin message
  • unpinMessage() - Unpin message
  • archiveChat() - Archive chat
  • unarchiveChat() - Unarchive chat
  • markChatUnread() - Mark chat as unread

📢 Channels Management (14 methods)

  • getChannels() - Get all channels
  • createChannel() - Create channel
  • getChannel() - Get channel by ID
  • deleteChannel() - Delete channel
  • getChannelMessagesPreview() - Get messages preview
  • followChannel() - Follow channel
  • unfollowChannel() - Unfollow channel
  • muteChannel() - Mute channel
  • unmuteChannel() - Unmute channel
  • searchChannelsByView() - Search channels by view
  • searchChannelsByText() - Search channels by text
  • getChannelSearchViews() - Get search views
  • getChannelSearchCountries() - Get search countries
  • getChannelSearchCategories() - Get search categories

🟢 Status Management (6 methods)

  • postTextStatus() - Post text status
  • postImageStatus() - Post image status
  • postVoiceStatus() - Post voice status
  • postVideoStatus() - Post video status
  • deleteStatus() - Delete status
  • getNewMessageId() - Get new message ID

🏷️ Labels Management (7 methods)

  • getLabels() - Get all labels
  • createLabel() - Create label
  • updateLabel() - Update label
  • deleteLabel() - Delete label
  • getChatLabels() - Get labels for chat
  • setChatLabels() - Set labels for chat
  • getChatsByLabel() - Get chats by label

👤 Contacts Management (12 methods)

  • getAllContacts() - Get all contacts
  • getContact() - Get contact info
  • checkContactExists() - Check if contact exists
  • getContactAbout() - Get contact about
  • getContactProfilePicture() - Get contact profile picture
  • blockContact() - Block contact
  • unblockContact() - Unblock contact
  • updateContact() - Update contact
  • getLids() - Get LIDs
  • getLidsCount() - Get LIDs count
  • getLid() - Get LID by ID
  • getLidByPhone() - Get LID by phone

👥 Groups Management (25 methods)

  • createGroup() - Create group
  • getGroups() - Get all groups
  • getGroup() - Get group by ID
  • deleteGroup() - Delete group
  • getGroupsCount() - Get groups count
  • refreshGroups() - Refresh groups
  • getGroupJoinInfo() - Get group join info
  • joinGroup() - Join group
  • leaveGroup() - Leave group
  • getGroupPicture() - Get group picture
  • setGroupPicture() - Set group picture
  • deleteGroupPicture() - Delete group picture
  • setGroupDescription() - Set group description
  • setGroupSubject() - Set group subject
  • getGroupInfoAdminOnly() - Get info admin only setting
  • setGroupInfoAdminOnly() - Set info admin only
  • getGroupMessagesAdminOnly() - Get messages admin only setting
  • setGroupMessagesAdminOnly() - Set messages admin only
  • getGroupInviteCode() - Get invite code
  • revokeGroupInviteCode() - Revoke invite code
  • getGroupParticipants() - Get participants
  • addGroupParticipants() - Add participants
  • removeGroupParticipants() - Remove participants
  • promoteGroupParticipant() - Promote to admin
  • demoteGroupParticipant() - Demote from admin

✅ Presence Management (4 methods)

  • setPresence() - Set presence
  • getAllPresence() - Get all presence info
  • getPresence() - Get presence for chat
  • subscribePresence() - Subscribe to presence

🔍 Observability (9 methods)

  • ping() - Ping endpoint
  • health() - Health check
  • getVersion() - Get API version
  • getServerVersion() - Get server version
  • getServerEnvironment() - Get server environment
  • getServerStatus() - Get server status
  • stopServer() - Stop server
  • getHeapSnapshot() - Get heap snapshot
  • getBrowserTrace() - Get browser trace

🖼️ Media Management (2 methods)

  • convertToVoice() - Convert audio to voice format
  • convertVideo() - Convert video

🖼️ Screenshot (1 method)

  • takeScreenshot() - Take screenshot

📅 Events (1 method)

  • sendEvent() - Send event

🧩 Apps Management (6 methods)

  • getApps() - Get all apps
  • createApp() - Create app
  • getApp() - Get app by ID
  • updateApp() - Update app
  • deleteApp() - Delete app
  • getChatwootLocales() - Get Chatwoot locales

Usage Examples

Send Text Message

await client.sendText({
  chatId: '1234567890@c.us',
  text: 'Hello, World!',
  reply_to: 'message-id',  // Optional: Reply to a specific message
  config: { ... },          // Optional: Override config
});

Send Image

await client.sendImage({
  chatId: '1234567890@c.us',
  file: 'https://example.com/image.jpg', // URL or base64
  caption: 'Check this out!',             // Optional
  reply_to: 'message-id',                 // Optional
  config: { ... },                        // Optional
});

Send File

await client.sendFile({
  chatId: '1234567890@c.us',
  file: 'https://example.com/document.pdf',
  filename: 'document.pdf',               // Optional
  caption: 'Important document',          // Optional
  reply_to: 'message-id',                 // Optional
  config: { ... },                        // Optional
});

Create and Manage Groups

// Create a group
const groupResponse = await client.createGroup({
  name: 'My Group',
  participants: ['1234567890@c.us', '0987654321@c.us']
});

// Add participants (use the group ID from the response)
const groupId = 'group-id@g.us'; // Extract from response
await client.addGroupParticipants(groupId, {
  participants: ['1111111111@c.us']
});

// Promote to admin
await client.promoteGroupParticipant(groupId, {
  participants: ['1234567890@c.us']
});

Session Management

Get Session Info

const session = await client.getSession({
  session: 'custom-session',  // Optional: Override session
});

Start Session

const session = await client.startSession({
  session: 'new-session',  // Optional: Override session to start
});

Stop Session

await client.stopSession({
  session: 'session-to-stop',  // Optional: Override session
});

Get All Sessions

const sessions = await client.getSessions();

Chat Operations

Get Chats

const chats = await client.getChats({
  session: 'custom-session',  // Optional: Override session
});

Get Messages

const messages = await client.getMessages('1234567890@c.us', {
  session: 'custom-session',  // Optional: Override session
});

Contact Operations

Check Number Status

const status = await client.checkNumberStatus('1234567890', {
  session: 'custom-session',  // Optional: Override session
});
console.log(status.exists); // true if number is on WhatsApp

Advanced Usage

Multiple Sessions

You can work with multiple WhatsApp sessions using the same client:

const client = new WAHAClient({
  baseURL: 'https://your-waha-instance.com',
  apiKey: 'your-api-key',
  session: 'default',
});

// Send from default session
await client.sendText({
  chatId: '1234567890@c.us',
  text: 'From default session',
});

// Send from a different session
await client.sendText({
  chatId: '1234567890@c.us',
  text: 'From custom session',
  config: { session: 'session-2' },
});

Custom Retry Logic

Adjust retry behavior for specific operations:

// For a critical message that needs more retries
await client.sendText({
  chatId: '1234567890@c.us',
  text: 'Important message',
  config: {
    retryAttempts: 10,
    retryDelay: 5000,
  },
});

// For a quick operation with no retries
await client.sendText({
  chatId: '1234567890@c.us',
  text: 'Quick message',
  config: {
    retryAttempts: 0,
  },
});

Error Handling

try {
  await client.sendText({
    chatId: '1234567890@c.us',
    text: 'Hello!',
  });
} catch (error) {
  console.error('Failed to send message:', error);
}

Types

The library exports TypeScript types for all configurations and responses:

import type {
  WAHAConfig,
  RequestConfig,
  SendTextParams,
  SendImageParams,
  SendFileParams,
  SessionInfo,
  ChatInfo,
  MessageInfo,
  APIResponse,
} from 'waha-api-client-ts';

Examples

See src/example.ts for code examples and src/demo.ts for a complete feature demonstration.

To run the demo:

npm install
npx tsx src/demo.ts

Viewing Documentation

Once deployed, the API documentation will be available at:

  • GitHub Pages: https://myusp.github.io/waha-api-client-ts/

You can also generate documentation locally:

npm run docs
# Documentation will be generated in the ./docs directory

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This is an unofficial client library for WAHA API. It is not affiliated with or endorsed by the WAHA project.

USE AT YOUR OWN RISK: This software is provided "as is" without warranty of any kind, either expressed or implied. The authors and contributors are not responsible for any damages, data loss, account bans, or other issues that may arise from using this library. You are solely responsible for ensuring your use complies with WhatsApp's Terms of Service and applicable laws. By using this library, you acknowledge and accept all risks associated with automated messaging and API usage.

About

Waha Api Client TS for https://github.com/devlikeapro/waha (unofficial)

myusp.github.io/waha-api-client-ts/

Topics

typescript whatsapp waha waha-api-client

Resources

Readme

License

ISC license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.2 Latest
Oct 16, 2025

Contributors 3

  •  
  •  
  •  

Languages