README.md

ZapToBox Whatsapp Api

REST API platform for integrating systems with WhatsApp with stability, multi-instance management, message sending, and full webhook event streaming. Designed for enterprise automation, bots, SaaS platforms, CRMs, ERPs, and large-scale integrations.

Overview

ZapToBox WhatsApp API is an advanced REST platform built on top of Baileys, enabling fast and stable integration between applications and WhatsApp.

The project supports:

• Multi-instance session management

• File-system based authentication (/sessions/{{owner}}/{{instanceName}})

• Full event webhook streaming

• High-performance message persistence

• All Baileys methods exposed through endpoints

• Scalable architecture using DDD (Domain Driven Design)

• Full TypeScript backend with Prisma ORM

• Automatic reconnection and failure handling

Features

Multi-instance Session Architecture

Each instance is fully isolated using the structure:

/sessions/{owner}/{instanceName}

This enables:

• Multiple authenticated devices per system

• Multi-user/multi-tenant architecture

• Stateless REST integration across environments

All Baileys Functionalities Exposed via API

The platform exposes every usable operation from Baileys, including:

• Messages

• Media

• Chat

• Group

• Profile

• Privacy

Webhook Event Streaming

All supported Baileys events are forwarded to your system in real-time, they are:

• messaging-history.set
• chats.upsert
• chats.update
• chats.delete
• lid-mapping.update
• presence.update
• contacts.upsert
• contacts.update
• messages.upsert
• messages.update
• messages.delete
• messages.media-update
• messages.reaction
• message-receipt.update
• groups.upsert
• groups.update
• group-participants.update
• group.join-request
• blocklist.set
• blocklist.update
• call
• labels.edit
• labels.association
• newsletter.reaction
• newsletter.view
• newsletter-participants.update
• newsletter-settings.update

And as additional webhook events:

• chats.set
• messages.set
• qrcode.updated
• qrcode.limit
• connection.open
• connection.close
• connection.removed

Project Structure

• /prisma
  • /migrations
    • ...
  • schema.prisma
• /src
  • /core
    • /connection
      • prisma.ts
    • /repositories
      • instances.ts
  • /infra
    • /baileys
      • services.ts
    • /config
      • env.ts
    • /http
      • /controllers
        • chat.ts
        • group.ts
        • instances.ts
        • media.ts
        • messages.ts
        • privacy.ts
        • profile.ts
      • /routes
        • chat.ts
        • group.ts
        • instances.ts
        • media.ts
        • messages.ts
        • privacy.ts
        • profile.ts
    • /mappers
      • contactMapper.ts
      • messageMapper.ts
    • /state
      • auth.ts
      • sessions.ts
    • /webhook
      • queue.ts
  • /shared
    • constants.ts
    • types.ts
    • utils.ts
  • main.ts
• /docs
• .env.example
• .gitignore
• docker-compose.yml
• Dockerfile
• LICENSE
• package.json
• prisma.config.ts
• README.md
• tsconfig.json

Installation

Clone the repository

git clone https://github.com/jeankassio/ZapToBox-Whatsapp-Api.git
cd ZapToBox-Whatsapp-Api

Install dependencies

npm install

Environment configuration

Rename .env.example to .env

cp .env.example .env

Please fill in all the information correctly within the .env file before proceeding, especially the PostgreSQL connection URL.

Deploy Prisma

npx prisma migrate deploy

Confirm and proceed

Running

Development

npm run dev

Production (auto build)

npm run start

Production (PM2)

build

npm run build

run

npm run start:pm2

//optionals:
pm2 save
pm2 startup

Docker Deploy

Build the image

docker build -t zaptobox-whatsapp-api

Run

docker run -d --name zaptobox -p 3000:3000 --env-file .env zaptobox-whatsapp-api

API Docs

You can find complete documentation for the endpoints at:

• Postman

Donate

Pix

6dcc2052-0b7c-4947-831d-46d67235416e