Overview

engine-whatsapp adalah WhatsApp gateway ekosistem Dazo — jembatan antara akun WhatsApp dan backend Dazo. Service ini mengelola sesi login (QR), mengirim pesan/media/lokasi, menerima pesan masuk, lalu meneruskannya ke backend via webhook dan ke frontend via Socket.IO secara realtime.

Dibangun dengan Baileys (multi-device, tanpa browser), Express 5, MongoDB, dan Socket.IO. Satu proses Node dapat menjalankan banyak sesi WhatsApp sekaligus (single process, multi-device).

Peran di ekosistem

Arsitektur

                  ┌──────────────────────────────┐
   WhatsApp  ◄───►│  Baileys (WhatsAppService)   │
                  │  sesi per instanceId (UUID)  │
                  └───────────┬──────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌──────────────────┐   ┌────────────────┐
│  REST API     │   │  Webhook         │   │  Socket.IO     │
│  /api/*       │   │  → Backend Dazo  │   │  → Frontend    │
└───────────────┘   └──────────────────┘   └────────────────┘
                              │
                              ▼
                     ┌────────────────┐
                     │    MongoDB     │
                     └────────────────┘

Tiga jalur keluar-masuk data:

Alur utama

1. Login — Client hit POST /api/new, engine membuat socket Baileys, QR dikirim realtime lewat event qrcode.
2. Pesan masuk — Baileys messages.upsert → media diunduh ke public/files → payload dikirim ke webhook backend → hasil di-emit ke frontend.
3. Pesan keluar — Backend hit POST /api/send-message → Baileys kirim → status ACK dipantau lewat messages.update → diteruskan ke webhook + socket.
4. Persistensi — Kredensial sesi disimpan di filesystem (session/auth/<instanceId>), bukan di MongoDB. MongoDB dipakai untuk data device dan riwayat chat.

Stack teknologi

Struktur direktori

engine-whatsapp/
├── .github/workflows/       # CI/CD: deploy staging & production
├── public/files/            # Media hasil download pesan masuk (disajikan via /files)
├── session/auth/<uuid>/    # Kredensial Baileys per instance
├── src/
│   ├── app.ts               # Entry: Express + HTTP + Socket.IO + Mongo + restore sesi
│   ├── config/
│   │   ├── config.ts        # Loader env var
│   │   └── database.ts      # Koneksi MongoDB
│   ├── controller/          # Validasi request + bentuk response
│   │   ├── SessionController.ts
│   │   ├── MessageController.ts
│   │   ├── GroupController.ts
│   │   └── NotificationController.ts
│   ├── middleware/
│   │   └── errorHandler.ts
│   ├── model/               # 4 skema Mongoose
│   │   ├── devices.model.ts
│   │   ├── admin_devices.model.ts
│   │   ├── chatInbox.model.ts
│   │   └── chatHistory.model.ts
│   ├── routes/itemRoutes.ts # SATU-SATUNYA tempat definisi route (prefix /api)
│   ├── service/
│   │   ├── whatsappService.ts        # Inti Baileys: sesi, kirim, event (~886 baris)
│   │   ├── incomingMessageService.ts # Pipeline pesan masuk
│   │   ├── socketService.ts          # Singleton Socket.IO
│   │   ├── notificationService.ts    # Push notif, chatlist, team chat, pixel
│   │   ├── chatHistory/chatHistoryService.ts
│   │   └── devices/deviceServices.ts
│   └── utils/
│       ├── helper.ts                 # Webhook, format nomor, download media, enkripsi
│       └── responseHandler.ts        # sendSuccess / sendError
├── wa-logs.txt              # Output log Pino (dibuat otomatis saat runtime)
└── package.json

Alur lapisan: routes → controller → service → (model | Baileys | webhook | socket).

whatsappService.ts (~886 baris) adalah pusat gravitasi repo. Perubahan di sana berdampak luas — baca dulu keseluruhan fungsi terkait sebelum mengedit.

Komponen utama

Endpoint ringkas

Detail per-endpoint di API Reference.

Cara kerja singkat

Inbound (pesan masuk): messages.upsert → IncomingMessageService.handle → processMessage — skip broadcast/newsletter, normalisasi @lid, ambil metadata grup, unduh media, ekstrak content, buat chat_histories bila belum aktif, ambil foto profil, kirim webhook report: false, emit message_upsert.

Outbound (pesan keluar): backend hit POST /api/send-message → WhatsAppService.sendTextMessage → validasi onWhatsApp, simulasi presence (composing/recording lalu paused), kirim, emit sendmessage(+_bubble). Status ACK dipantau via messages.update → webhook report: true.

Status ACK: messages.update → mapping 1..5 → pending|sent|delivered|viewed|played → dedupe via Set per sesi → cari temp_id di chat_inbox → webhook report: true.

Detail alur di Session Lifecycle, Message Flow, dan Realtime Events.

Konsep inti

instanceId

Identitas sebuah device/sesi WhatsApp, berupa UUID. Nilai ini dipakai konsisten sebagai:

• nama folder kredensial: session/auth/<instanceId>
• key sesi di memory (Map)
• nama room Socket.IO
• kolom id pada koleksi devices / admin_devices

Konsistensi keempatnya wajib dijaga.

Sesi bersifat in-memory

private static sessions = new Map<string, SessionData>(). Konsekuensi yang harus diingat:

• Tidak bisa PM2 cluster mode atau scaling horizontal tanpa mengubah arsitektur.
• Kredensial persisten di filesystem, bukan di MongoDB.
• Restart = semua sesi dimuat ulang dari disk (dengan jeda 2 detik antar sesi).

Status sesi

Status internal: CONNECTING, QR_READY, CONNECTED, DISCONNECTED. Untuk konsumsi luar, status dinormalisasi menjadi open / close (atau NOT_FOUND bila sesi tidak ada di memory).

Yang TIDAK boleh diubah tanpa koordinasi

Langkah berikutnya

• Baru mulai? Baca Setup Environment — .env memegang seluruh URL service.
• Sudah punya env? Lanjut ke Local Development.
• Akan deploy? Baca Deployment — PM2, single process.
• Engineer baru wajib baca Session Lifecycle sebelum menyentuh whatsappService.ts.