whatsmeow-sdk

v0.1.0

Published

2 months ago

TypeScript SDK for whatsmeow - WhatsApp Web multidevice API

0High
0Medium
0Low

suissai

whatsapp whatsmeow sdk typescript api chat messaging

WhatsMeow SDK

A comprehensive TypeScript SDK for the whatsmeow WhatsApp Web multidevice API.

📦 Installation

npm install whatsmeow-sdk

bun add whatsmeow-sdk

🚀 Quick Start

Basic Setup

import { WhatsMeowClient } from 'whatsmeow-sdk';

// Create a new client instance
const client = new WhatsMeowClient({
  serverUrl: 'http://localhost:8080',
  apiKey: 'your-api-key', // Optional
  instance: 'my-instance', // Optional
  timeout: 30000, // Optional, in milliseconds
});

Creating and Connecting an Instance

// Create a new instance
const instance = await client.instance.create({
  instanceName: 'my-bot',
  token: 'optional-token',
});

// Connect and get QR code
const qrCode = await client.instance.connect({
  instanceName: 'my-bot',
});

console.log('Scan QR Code:', qrCode.code);

// Wait for connection
await client.instance.waitForConnection('my-bot', 60000);

console.log('Connected!');

Sending Messages

// Send a text message
await client.messages.sendText({
  number: '5511999999999',
  text: 'Hello from WhatsMeow SDK! 👋',
});

// Send an image
await client.messages.sendImage({
  number: '5511999999999',
  image: 'https://example.com/image.jpg',
  caption: 'Check out this image!',
});

// Send a video
await client.messages.sendVideo({
  number: '5511999999999',
  video: 'https://example.com/video.mp4',
  caption: 'Check out this video!',
});

// Send a document
await client.messages.sendDocument({
  number: '5511999999999',
  document: 'https://example.com/document.pdf',
  fileName: 'document.pdf',
  caption: 'Here is the document',
});

// Send audio (voice message)
await client.messages.sendAudio({
  number: '5511999999999',
  audio: 'https://example.com/audio.mp3',
  ptt: true, // Push-to-talk (voice message)
});

// Send a location
await client.messages.sendLocation({
  number: '5511999999999',
  latitude: -23.5505,
  longitude: -46.6333,
  name: 'São Paulo',
  address: 'São Paulo, Brazil',
});

// Send a contact
await client.messages.sendContact({
  number: '5511999999999',
  contacts: [
    {
      displayName: 'John Doe',
      vcard: 'BEGIN:VCARD\nVERSION:3.0\nN:Doe;John\nFN:John Doe\nEND:VCARD',
    },
  ],
});

// Send a reaction
await client.messages.sendReaction({
  remoteJid: '[email protected]',
  fromMe: true,
  id: 'message-id',
  reaction: '👍',
});

📚 API Reference

Messages Module

All message-related operations:

| Method | Description | |--------|-------------| | sendText(data) | Send a text message | | sendImage(data) | Send an image message | | sendVideo(data) | Send a video message | | sendAudio(data) | Send an audio/voice message | | sendDocument(data) | Send a document | | sendSticker(data) | Send a sticker | | sendContact(data) | Send a contact | | sendLocation(data) | Send a location | | sendReaction(data) | Send a reaction to a message | | sendButton(data) | Send a button message | | sendList(data) | Send a list message | | send(data) | Send a generic message |

Chats Module

Chat management operations:

| Method | Description | |--------|-------------| | checkNumbers(numbers) | Check if numbers are on WhatsApp | | findAll() | Get all chats | | findById(chatId) | Get chat by ID | | updatePresence(data) | Update presence status | | markAsRead(data) | Mark messages as read | | archive(data) | Archive/unarchive a chat | | deleteMessage(data) | Delete a message | | findMessages(data) | Search messages | | updateMessage(data) | Edit a sent message | | getBase64FromMediaMessage(data) | Get media as base64 | | fetchProfilePicture(number) | Get profile picture URL | | findContacts(where) | Search contacts | | pin(chatId, pin) | Pin/unpin a chat | | mute(chatId, mute, duration) | Mute/unmute a chat |

Groups Module

Group management operations:

| Method | Description | |--------|-------------| | create(data) | Create a new group | | findAll(withParticipants) | Get all groups | | findByJid(data) | Get group by JID | | findByInviteCode(data) | Get group by invite code | | updateSubject(data) | Update group name | | updateDescription(data) | Update group description | | updatePicture(data) | Update group picture | | updateMembers(data) | Add/remove/promote/demote members | | addParticipants(groupJid, participants) | Add members | | removeParticipants(groupJid, participants) | Remove members | | promoteParticipants(groupJid, participants) | Promote to admin | | demoteParticipants(groupJid, participants) | Demote from admin | | findMembers(groupJid) | Get group members | | leave(data) | Leave a group | | fetchInviteCode(data) | Get group invite code | | revokeInviteCode(data) | Revoke invite code | | acceptInviteCode(data) | Accept invite code | | getInviteLink(groupJid) | Get group invite link |

Profile Module

Profile and privacy management:

| Method | Description | |--------|-------------| | fetchProfile(number) | Get user profile | | fetchBusinessProfile(number) | Get business profile | | updateName(data) | Update profile name | | updateStatus(data) | Update status message | | updatePicture(data) | Update profile picture | | removePicture() | Remove profile picture | | fetchPrivacySettings() | Get privacy settings | | updatePrivacySettings(data) | Update privacy settings | | isRegisteredUser(number) | Check if user is on WhatsApp | | getProfilePictureUrl(number, preview) | Get profile picture URL | | updateBlockStatus(jid, block) | Block/unblock user | | getBlocklist() | Get blocked users |

Instance Module

Instance lifecycle management:

| Method | Description | |--------|-------------| | create(data) | Create a new instance | | connect(data) | Connect instance (get QR code) | | connectionState(data) | Get connection status | | logout(data) | Logout from instance | | restart(data) | Restart instance | | delete(data) | Delete instance | | fetchAll() | Get all instances | | setPresence(data) | Set instance presence | | getQRCode(instanceName) | Get QR code | | isConnected(instanceName) | Check if connected | | waitForConnection(instanceName, timeout) | Wait for connection |

Presence Module

Presence and typing notifications:

| Method | Description | |--------|-------------| | update(data) | Send presence update | | sendTyping(chatJid) | Send typing notification | | sendRecording(chatJid) | Send recording notification | | sendPaused(chatJid) | Send paused notification | | sendAvailable() | Set as available | | sendUnavailable() | Set as unavailable | | subscribe(jid) | Subscribe to presence updates | | unsubscribe(jid) | Unsubscribe from presence updates |

Receipts Module

Message receipts (read, delivery, etc.):

| Method | Description | |--------|-------------| | send(data) | Send a receipt | | sendRead(chatJid, messageIds) | Send read receipt | | sendDelivery(chatJid, messageIds) | Send delivery receipt | | getStatus(chatJid, messageId) | Get receipt status |

AppState Module

Application state synchronization:

| Method | Description | |--------|-------------| | sync(data) | Sync app state | | getInfo(stateName) | Get state info | | fetchAll() | Get all states | | set(stateName, index, value) | Set state value | | remove(stateName, index) | Remove state value | | getContacts() | Get contacts from state | | fullSync() | Perform full sync |

Media Module

Media upload and download:

| Method | Description | |--------|-------------| | upload(file, mediaType) | Upload media | | uploadImage(file) | Upload image | | uploadVideo(file) | Upload video | | uploadAudio(file) | Upload audio | | uploadDocument(file) | Upload document | | download(message) | Download media | | downloadBase64(message) | Download as base64 | | getUrl(mediaId) | Get media URL | | delete(mediaId) | Delete media | | getInfo(mediaId) | Get media info |

🔌 Event Handling

Listen for connection events:

import { ConnectionEvent } from 'whatsmeow-sdk';

// Handle QR code
client.on(ConnectionEvent.QR, (data) => {
  console.log('QR Code:', data.data.code);
  console.log('Base64:', data.data.base64);
});

// Handle successful login
client.on(ConnectionEvent.LOGGED_IN, (data) => {
  console.log('Logged in successfully!');
});

// Handle disconnection
client.on(ConnectionEvent.LOGGED_OUT, (data) => {
  console.log('Logged out');
});

// Handle connection status changes
client.on(ConnectionEvent.CONNECTION_UPDATE, (data) => {
  console.log('Connection status:', data.data.status);
});

🎯 Instance Override

All methods support an optional instance override parameter:

// Using default instance
await client.messages.sendText({
  number: '5511999999999',
  text: 'Hello!',
});

// Using a specific instance
await client.messages.sendText(
  {
    number: '5511999999999',
    text: 'Hello!',
  },
  { instance: 'other-instance' }
);

📝 Complete Example

import {
  WhatsMeowClient,
  ConnectionEvent,
  PresenceType,
} from 'whatsmeow-sdk';

async function main() {
  // Create client
  const client = new WhatsMeowClient({
    serverUrl: 'http://localhost:8080',
    instance: 'my-bot',
  });

  // Setup event handlers
  client.on(ConnectionEvent.QR, async (data) => {
    console.log('Scan this QR code:');
    console.log(data.data.code);
  });

  client.on(ConnectionEvent.LOGGED_IN, async () => {
    console.log('Successfully logged in!');

    // Send a welcome message
    await client.messages.sendText({
      number: '5511999999999',
      text: 'Bot is online! 🤖',
    });
  });

  // Create and connect instance
  await client.instance.create({ instanceName: 'my-bot' });
  await client.instance.connect({ instanceName: 'my-bot' });

  // Wait for connection
  await client.instance.waitForConnection('my-bot', 60000);

  // Set presence to available
  await client.presence.sendAvailable();

  console.log('Bot is ready!');
}

main().catch(console.error);

📋 Types and Enums

MessageType

enum MessageType {
  TEXT = 'text',
  IMAGE = 'image',
  VIDEO = 'video',
  AUDIO = 'audio',
  DOCUMENT = 'document',
  STICKER = 'sticker',
  CONTACT = 'contact',
  LOCATION = 'location',
  REACTION = 'reaction',
  BUTTON = 'button',
  LIST = 'list',
}

PresenceType

enum PresenceType {
  AVAILABLE = 'available',
  UNAVAILABLE = 'unavailable',
  COMPOSING = 'composing',
  RECORDING = 'recording',
  PAUSED = 'paused',
}

ReceiptType

enum ReceiptType {
  READ = 'read',
  READ_SELF = 'read-self',
  DELIVERY = 'delivery',
  DELIVERY_SELF = 'delivery-self',
  SERVER_ACK = 'server-ack',
  PLAYER_ACK = 'player-ack',
}

ConnectionEvent

enum ConnectionEvent {
  OPEN = 'open',
  CLOSE = 'close',
  LOGGED_IN = 'logged-in',
  LOGGED_OUT = 'logged-out',
  CONNECTING = 'connecting',
  DISCONNECTED = 'disconnected',
  QR = 'qr',
  PAIR_SUCCESS = 'pair-success',
}

🔧 Configuration

Client Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | serverUrl | string | - | API server URL (required) | | apiKey | string | - | API key for authentication | | instance | string | - | Default instance name | | timeout | number | 30000 | Request timeout in ms |

🛠️ Development

# Install dependencies
npm install

# Build the SDK
npm run build

# Watch mode
npm run dev

# Run linter
npm run lint

# Run tests
npm test

🧪 Poliglot Testing

Este SDK utiliza um sistema de testes poliglota inovador através da biblioteca local packages/tests2dialects.

Confira a documentação detalhada na pasta tests/:

Para rodar os testes:

bun testall tests/*.spec.ts

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

whatsmeow - The original Go library for WhatsApp Web
evolution-api-sdk - Inspiration for the SDK structure

📞 Support

Documentation: https://pkg.go.dev/go.mau.fi/whatsmeow
whatsmeow Matrix Room: #whatsmeow:maunium.net

🤝 Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request