Installation¶

Requirements¶

Node.js 18 or higher
npm, yarn or pnpm
Active WhatsApp account

Package installation¶

npmyarnpnpm

npm install @arcaelas/whatsapp

yarn add @arcaelas/whatsapp

pnpm add @arcaelas/whatsapp

TypeScript configuration¶

The library is written in TypeScript and provides complete types. Make sure you have a compatible configuration:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  }
}

File structure¶

When using FileEngine (default), the library creates the following structure:

.baileys/
  default/                    # or the name you specify
    session/
      creds                   # Authentication credentials
      {type}/
        {id}                  # Signal keys (e.g. session/app-state-sync-key/abc123)
    lid/
      {lid}                   # Reverse index: LID -> JID
    contact/
      {jid}/index             # Contact data (IContactRaw JSON)
    chat/
      {jid}/
        index                 # Chat data (IChatRaw JSON)
        messages              # Message index: "TIMESTAMP MID" per line
        message/
          {mid}/
            index             # Message metadata (IMessageIndex JSON)
            raw               # Full WAMessage raw (JSON)
            content           # Binary content base64 (media)

ID normalization

The @ characters in JIDs are replaced with _at_ in directory names. Example: 5491112345678@s.whatsapp.net -> 5491112345678_at_s.whatsapp.net

Tip

Add .baileys/ to your .gitignore to avoid uploading credentials to the repository.

Verify installation¶

Create a test file:

test.ts

import { WhatsApp, FileEngine } from "@arcaelas/whatsapp";

const wa = new WhatsApp({
  engine: new FileEngine(".baileys/test"),
});

console.log("Installation successful!");
console.log("Available classes:", {
  Chat: wa.Chat,
  Contact: wa.Contact,
  Message: wa.Message,
});

Run:

npx tsx test.ts

If you see the success message, the installation is complete.

Common issues¶

Error: Cannot find module 'baileys'¶

Make sure baileys is installed as a dependency:

npm install baileys

Error: libffi.so.7 not found (Linux)¶

Install system dependencies:

# Debian/Ubuntu
sudo apt-get install libffi-dev

# CentOS/RHEL
sudo yum install libffi-devel

Error: ENOENT .baileys/default¶

The directory is created automatically on first connection. If it persists, check write permissions.

Next step¶

Getting started