Baileys - Typescript/Javascript WhatsApp Web API

WhatsApp Baileys is an open-source TypeScript/JavaScript library designed for developers who need direct and flexible integration with WhatsApp Web. It allows applications to establish WhatsApp connections through WebSocket communication without requiring a browser such as Chrome or Chromium.

This library provides a modular interface for authentication, session management, message processing, event handling, and raw message relay. It can be integrated into various Node.js applications, including automation systems, business bots, customer service platforms, notification services, and other communication-related projects.

The project also focuses on making the authentication and pairing workflow easier to integrate into custom applications. QR authentication and pairing code authentication can be combined with persistent session storage, allowing applications to reconnect without requiring users to authenticate every time the process restarts.

Baileys is designed to provide developers with direct access to WhatsApp Web functionality while keeping the implementation relatively lightweight. Because the library operates through a WebSocket connection rather than browser automation, it can be deployed on environments such as Linux servers, VPS instances, Docker containers, and development environments such as Termux.

This project is developed and maintained independently and is not affiliated with WhatsApp or Meta.

Main Features and Advantages

• WhatsApp Web connection through WebSocket
• QR Code authentication
• Pairing Code authentication
• Multi-device authentication
• Persistent local session management
• Automatic credential updates
• sendMessage support
• relayMessage support
• Raw message object support
• Custom message structures
• Interactive messages and action buttons
• Poll and quiz message support
• Product and order message support
• Group-related message functionality
• Event-based message and connection handling
• Lightweight Node.js integration
• Suitable for VPS, Linux, Docker, and Termux environments
• Ready-to-use examples for common use cases

Getting Started

Before starting development, make sure Node.js 20 or newer is installed on your environment.

Install the package using npm, configure the authentication state, then create a WhatsApp socket using makeWASocket().

The simplest setup uses useMultiFileAuthState() to store authentication data locally. Once the credentials have been saved, the same session can be reused when the application is restarted.

The examples below use CommonJS syntax so they can be integrated directly into most existing Node.js projects.

Table of Contents

• Requirements
• Install
• Quick Start
• Sending Messages
• Raw Message Relay
• Relay Examples
• Events
• Authentication
• Complete Example
• Why Choose WhatsApp Baileys?
• Technical Notes
• Contact Developer
• Contributors outside the Baileys code
• Credits
• Disclaimer

Requirements

• Node.js >= 20
• npm
• Internet connection
• A WhatsApp account for authentication

Depending on the features being used, additional dependencies may be required by the project.

Install

Install the package using npm:

npm install @alannxd/baileys

Or use it as an alias while keeping the standard Baileys package name in your source code:

{
  "dependencies": {
    "@whiskeysockets/baileys": "npm:@alannxd/baileys@latest"
  }
}

Then import it using:

const makeWASocket =
  require('@whiskeysockets/baileys').default

const {
  useMultiFileAuthState
} = require('@whiskeysockets/baileys')

Quick Start

The following example creates a basic WhatsApp connection, stores authentication credentials locally, and listens for connection updates.

const makeWASocket =
  require('@whiskeysockets/baileys').default

const {
  useMultiFileAuthState
} = require('@whiskeysockets/baileys')

async function start() {
  const { state, saveCreds } =
    await useMultiFileAuthState('./session')

  const sock = makeWASocket({
    auth: state
  })

  sock.ev.on(
    'creds.update',
    saveCreds
  )

  sock.ev.on(
    'connection.update',
    ({ connection }) => {
      console.log(
        'Connection:',
        connection
      )
    }
  )
}

start()

The authentication state is stored inside the session/ directory. Once authenticated, the same session can be reused when the application starts again.

Sending Messages

Text Message

await sock.sendMessage(
  '[email protected]',
  {
    text: 'Hello'
  }
)

Image Message

await sock.sendMessage(
  '[email protected]',
  {
    image: {
      url: './image.jpg'
    },
    caption: 'Hello'
  }
)

Video Message

await sock.sendMessage(
  '[email protected]',
  {
    video: {
      url: './video.mp4'
    },
    caption: 'Hello'
  }
)

Raw Message Relay

relayMessage() digunakan untuk mengirim raw message object secara langsung.

Metode ini berguna ketika aplikasi membutuhkan kontrol yang lebih langsung terhadap struktur message dibandingkan penggunaan helper sendMessage() biasa.

await sock.relayMessage(
  target,
  message,
  {
    messageId: message.key.id
  }
)

Alanself

Library ini menyediakan opsi tambahan Alanself pada relay message:

await sock.relayMessage(
  target,
  message,
  {
    messageId: message.key.id,
    Alanself: true
  }
)

Alanself: true digunakan pada implementasi tertentu untuk mengatur bagaimana pesan hasil relay diperlakukan terhadap sinkronisasi pesan milik perangkat pengirim.

Karena opsi ini merupakan bagian dari modifikasi/penyesuaian project, perilakunya dapat bergantung pada implementasi socket yang digunakan.

Relay Examples

Conversation

await sock.relayMessage(
  jid,
  {
    conversation: 'Hello'
  },
  {
    Alanself: true
  }
)

Extended Text

await sock.relayMessage(
  jid,
  {
    extendedTextMessage: {
      text: 'Hello'
    }
  },
  {
    Alanself: true
  }
)

Raw message relay memungkinkan developer menggunakan struktur message yang lebih spesifik sesuai kebutuhan aplikasinya.

Events

Semua event tersedia melalui sock.ev.

Connection

sock.ev.on(
  'connection.update',
  ({ connection }) => {
    console.log(
      'Connection:',
      connection
    )
  }
)

Incoming Message

sock.ev.on(
  'messages.upsert',
  ({ messages }) => {
    for (const message of messages) {
      console.log(
        'Incoming:',
        message.message
      )
    }
  }
)

Credentials

sock.ev.on(
  'creds.update',
  saveCreds
)

Event system memungkinkan aplikasi menangani berbagai perubahan secara asynchronous, termasuk status koneksi, pesan masuk, pembaruan credential, dan event lain yang tersedia pada socket.

Authentication

Session disimpan secara lokal menggunakan:

useMultiFileAuthState()

Contoh struktur session:

session/
├── creds.json
├── app-state-sync-key-*.json
└── ...

Folder tersebut berisi informasi authentication yang memungkinkan aplikasi mempertahankan session WhatsApp.

Jangan upload folder session ke repository publik.

Tambahkan ke .gitignore:

session/
node_modules/
.env

Credential session sebaiknya diperlakukan sebagai data sensitif karena dapat digunakan untuk mempertahankan authentication pada perangkat yang menjalankan aplikasi.

Complete Example

const makeWASocket =
  require('@whiskeysockets/baileys').default

const {
  useMultiFileAuthState
} = require('@whiskeysockets/baileys')

async function start() {
  const { state, saveCreds } =
    await useMultiFileAuthState('./session')

  const sock = makeWASocket({
    auth: state
  })

  sock.ev.on(
    'creds.update',
    saveCreds
  )

  sock.ev.on(
    'connection.update',
    ({ connection }) => {
      console.log(
        '[ CONNECTION ]',
        connection
      )
    }
  )

  async function sendText(jid, text) {
    return sock.sendMessage(
      jid,
      { text }
    )
  }

  async function relay(jid, message) {
    return sock.relayMessage(
      jid,
      message,
      {
        messageId: message.key.id,
        Alanself: true
      }
    )
  }
}

start()

Why Choose WhatsApp Baileys?

Baileys memberikan pendekatan yang relatif ringan untuk membuat aplikasi yang terhubung dengan WhatsApp Web tanpa harus menjalankan browser automation.

Beberapa karakteristik utama yang membuat library ini cocok untuk berbagai kebutuhan development:

• Direct WebSocket Connection Aplikasi dapat berkomunikasi dengan WhatsApp Web melalui koneksi WebSocket tanpa membutuhkan browser sebagai perantara.

• Flexible Authentication Mendukung authentication berbasis QR Code maupun Pairing Code serta penyimpanan session secara lokal.

• Multi-Device Support Mendukung sistem multi-device WhatsApp sehingga aplikasi dapat digunakan dengan mekanisme authentication modern.

• Raw Message Access relayMessage() memungkinkan developer bekerja dengan message object secara lebih langsung ketika sendMessage() standar tidak cukup untuk kebutuhan tertentu.

• Event-Based Architecture Berbagai aktivitas dapat dipantau menggunakan event seperti connection.update, messages.upsert, dan creds.update.

• Lightweight Deployment Dapat digunakan pada VPS, Linux server, Docker, maupun Termux tanpa memerlukan browser automation.

• Flexible Integration API dapat digunakan sebagai bagian dari bot, automation system, notification service, customer service application, maupun project Node.js lainnya.

• Customizable Karena source dan struktur library dapat dikembangkan lebih lanjut, developer dapat menyesuaikannya dengan kebutuhan aplikasi masing-masing.

Technical Notes

Node.js Version

Library ditujukan untuk environment Node.js versi:

Node.js >= 20

Menggunakan versi Node.js yang sesuai membantu memastikan fitur JavaScript modern dan dependency dapat berjalan sebagaimana mestinya.

Authentication State

Authentication state menggunakan:

useMultiFileAuthState()

Credential harus tetap disimpan melalui:

sock.ev.on(
  'creds.update',
  saveCreds
)

Hal tersebut memungkinkan perubahan credential ditulis ke session secara otomatis.

Raw Relay

relayMessage() bekerja menggunakan raw message object.

Contoh:

await sock.relayMessage(
  jid,
  message,
  {
    messageId: message.key.id,
    Alanself: true
  }
)

Struktur message yang dikirim harus sesuai dengan format message yang dapat diproses oleh socket.

Environment

Library dapat digunakan pada berbagai environment Node.js, termasuk:

Linux
VPS
Docker
Termux
Local Development

Session Security

Folder session sebaiknya tidak dibagikan, dikirim ke orang lain, atau diupload ke repository publik.

Jika session tidak sengaja terekspos, authentication dapat berisiko disalahgunakan.

WhatsApp Web Compatibility

WhatsApp dapat melakukan perubahan pada sisi Web maupun protocol. Karena itu, perubahan pada WhatsApp dapat menyebabkan bagian tertentu dari library membutuhkan update atau penyesuaian.

Developer yang menggunakan library ini sebaiknya memperhatikan update dependency dan perubahan compatibility secara berkala.

Additional Features

Project ini juga menyediakan berbagai kemampuan message seperti interactive message, action button, poll, quiz, product message, order message, group-related message, dan beberapa struktur message lainnya tergantung versi library yang digunakan.

Contact Developer

Untuk pertanyaan, support, laporan bug, collaboration, atau informasi mengenai project:

• Telegram: Telegram Contact
• WhatsApp Channel: Channel WhatsApp

Untuk informasi terbaru mengenai project dan update library, silakan mengikuti channel yang tersedia.

Contributors outside the Baileys code

Thanks to the following awesome contributors who help improve this project.

Credits

AlannXD

Developer & Maintainer

Based on:

Baileys

Disclaimer

Project ini dibuat untuk keperluan development dan educational.

Developer tidak bertanggung jawab atas penyalahgunaan library, pembatasan akun, kehilangan session, atau pelanggaran Terms of Service WhatsApp.

Gunakan library secara bertanggung jawab dan ikuti ketentuan layanan WhatsApp yang berlaku.