waha-api-client-ts

v1.0.2

Published

3 months ago

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

Downloads

0High
0Medium
0Low

myusp

waha api client whatsapp typescript

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
🌐 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
📝 TypeScript: Fully typed with TypeScript for better development experience
🚀 Easy to Use: Simple and intuitive API
🛡️ Safe Send Methods: Built-in number verification to prevent blocking

Installation

npm install waha-api-client-ts

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: '[email protected]',
  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: '[email protected]',
  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:

Number Verification: Checks if the number is registered on WhatsApp before sending
Seen Receipt: Sends a "seen" indicator to appear more human-like
Typing Indicators: Shows "typing..." with realistic delays based on message type and length
Random Delays: Adds random delays between actions to simulate human behavior
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:

Verify Number: Check if the recipient's number exists on WhatsApp
Send Seen: Mark the chat as "seen" (if applicable)
Start Typing: Show typing indicator in the chat
Wait: Realistic delay based on message type (see "Delay Timings" above: 1-6 seconds depending on content)
Stop Typing: Hide typing indicator
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: '[email protected]',
  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: '[email protected]',
  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: '[email protected]',
  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

💬 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

🟢 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: '[email protected]',
  text: 'Hello, World!',
  reply_to: 'message-id',  // Optional: Reply to a specific message
  config: { ... },          // Optional: Override config
});

Send Image

await client.sendImage({
  chatId: '[email protected]',
  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: '[email protected]',
  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: ['[email protected]', '[email protected]']
});

// Add participants (use the group ID from the response)
const groupId = '[email protected]'; // Extract from response
await client.addGroupParticipants(groupId, {
  participants: ['[email protected]']
});

// Promote to admin
await client.promoteGroupParticipant(groupId, {
  participants: ['[email protected]']
});

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('[email protected]', {
  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: '[email protected]',
  text: 'From default session',
});

// Send from a different session
await client.sendText({
  chatId: '[email protected]',
  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: '[email protected]',
  text: 'Important message',
  config: {
    retryAttempts: 10,
    retryDelay: 5000,
  },
});

// For a quick operation with no retries
await client.sendText({
  chatId: '[email protected]',
  text: 'Quick message',
  config: {
    retryAttempts: 0,
  },
});

Error Handling

try {
  await client.sendText({
    chatId: '[email protected]',
    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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

waha-api-client-ts

Features

Installation

Quick Start

Configuration

Default Configuration

Per-Request Configuration Override

Safe Send Methods (Avoid Blocking)

Why Use Safe Send?

Available Safe Send Methods

How Safe Send Works

Safe Send Usage Examples

Anti-Blocking Best Practices

When to Use Safe Send vs Regular Send

API Methods

🔑 Authentication (2 methods)

🖥️ Session Management (13 methods)

🆔 Profile Management (5 methods)

📤 Messaging (24 methods)

💬 Chat Management (16 methods)

📢 Channels Management (14 methods)

🟢 Status Management (6 methods)

🏷️ Labels Management (7 methods)

👤 Contacts Management (12 methods)

👥 Groups Management (25 methods)

✅ Presence Management (4 methods)

🔍 Observability (9 methods)

🖼️ Media Management (2 methods)

🖼️ Screenshot (1 method)

📅 Events (1 method)

🧩 Apps Management (6 methods)

Usage Examples

Send Text Message

Send Image

Send File

Create and Manage Groups

Session Management

Get Session Info

Start Session

Stop Session

Get All Sessions

Chat Operations

Get Chats

Get Messages

Contact Operations

Check Number Status

Advanced Usage

Multiple Sessions

Custom Retry Logic

Error Handling

Types

Examples

Viewing Documentation

License

Contributing

Disclaimer