Levanter: WhatsApp bot on a private Baileys fork, with API mode and multi-session support

Levanter depends on a private Baileys fork from Bitbucket, not the public npm package

Levanter uses Baileys, the unofficial WhatsApp client library, as its message transport layer. package.json pins this dependency as `git+https://[email protected]/lyfe00011/baileys.git`, a custom fork on Bitbucket rather than the standard public npm package. That distinction has real consequences for anyone setting up a build environment: yarn install fetches the Baileys code directly from that Bitbucket repository, and if the repository moves, becomes private or is deleted, the install step fails.

This is the part most setup guides for WhatsApp bots skip over. A Bitbucket-hosted git dependency means your build depends on a service you do not control and a specific account that can change ownership. Checking that the Bitbucket URL is still accessible should be the first step before any deployment, not an afterthought.

Beyond Baileys, package.json lists dependencies that include axios, cheerio, googleapis, jimp, pdfkit and pg. The pg package is a PostgreSQL client, though the README does not document how the bot uses a database.

API_MODE is a three-state switch: off, bot-plus-api, and api-only gateway

By default, API_MODE is false and the bot runs with no HTTP interface. Setting it to true enables both the bot commands and the API endpoint simultaneously. Setting it to "only" disables all bot commands and runs the bot purely as an HTTP gateway for sending and receiving messages.

When API_MODE is true, the bot messages itself an API quick-start card on startup with the base URL, auth status and a ready-to-run example. The minimal set of environment variables to enable the API is:

API_MODE=true
API_KEY=your-secret-key
PORT=3000
API_PUBLIC_URL=https://bot.example.com
API_WEBHOOK_URL=https://your-app.com/hook

API_PUBLIC_URL defaults to auto-detection on Render and Heroku but must be set manually on a VPS or behind a custom domain. API_KEY is required; without a valid key, the API is locked and all requests receive 401. API_WEBHOOK_URL is optional and controls whether incoming messages are forwarded to your application.

Installing on Ubuntu VPS requires Node.js 20.x, Yarn, PM2 and ffmpeg

Deployment to a VPS or local Ubuntu machine follows a five-step manual process. The first step installs system packages:

sudo apt update && sudo apt upgrade -y
sudo apt install git ffmpeg curl -y

ffmpeg is a required system dependency for media conversion, not optional. Node.js 20.x installs via NodeSource:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs -y

Yarn and PM2 go in next:

sudo npm install -g yarn
yarn global add pm2

Then clone and install:

git clone https://github.com/lyfe00011/levanter botName
cd botName
yarn install

Yarn install is where the Bitbucket Baileys dependency fetches. If Bitbucket is unreachable, this step hangs or fails. The README also documents a one-liner quick installer that pipes from a bit.ly shortened URL to bash; the destination of that URL is not visible in the README and cannot be verified before running.

A Docker path also exists, using a custom base image: `FROM quay.io/lyfe00011/md:beta`. That base image is tagged beta, not a pinned version, so its contents can change between builds.

POST /api/send accepts five message types, and GET /api/sessions lists connected numbers

The API exposes three endpoints. POST /api/send covers five message types: text, image, video, audio and document. The `to` field takes a phone number or a full group JID. To send a text message:

curl -X POST https://bot.example.com/api/send \
 -H "x-api-key: your-secret-key" \
 -H "Content-Type: application/json" \
 -d '{"to":"919876543210","type":"text","text":"hello from api"}'

A successful response includes the message ID: `{ "status": 200, "id": "3EB0XXXXXXXXXXXX" }`. Media messages require a publicly reachable HTTPS URL in the `url` field; local file paths and private network addresses are explicitly blocked.

GET /api/sessions returns connected session status. GET /api/media/:session/:id retrieves received media by message ID. Media is cached for approximately 10 minutes after arrival; fetching it after that window returns nothing.

All three endpoints require the x-api-key header. Session addressing uses a positional index where `"0"` is the first session, `"1"` the second, matching the SESSION_ID order.

One API key controls every session, making Levanter a single-tenant deployment

The README notes that a single API_KEY grants access to all sessions and calls this design intended for single-tenant use. That key grants full access to every connected WhatsApp number in the deployment. There is no per-session authentication, no role-based access control and no way to give one client access to session 0 while blocking access to session 1.

For a developer who runs one bot for their own use or for a single client, this is not a problem. For a service provider who wants to host multiple independent clients each with their own WhatsApp numbers, a single leaked or misused key exposes all sessions at once. Building isolation on top of this would require either running separate Levanter instances or writing a proxy layer that enforces per-client routing, neither of which the README documents.

Send operations through the API join the same queue as bot-triggered messages, so heavy API use can create congestion. WhatsApp's own rate limits apply, but the README gives no numbers for what counts as flooding.

The README says 11 languages but the configuration table lists 12

The Features bullet in the README says the bot is "Localized - responses in 11 languages." The Supported Languages table that appears immediately below lists 12 language codes: en (English), es (Spanish), fr (French), hi (Hindi), bn (Bengali), id (Indonesian), ur (Urdu), tr (Turkish), ru (Russian), ar (Arabic), ml (Malayalam) and zh (Chinese).

That count is 12, not 11. Either the bullet was written when one fewer language existed and was not updated when a twelfth was added, or there is an off-by-one error in the copy. In either case, the table is the specific configuration reference and the twelve entries are what actually exists.

Setting a language uses the BOT_LANG key in config.env, for example:

BOT_LANG=es

The README does not describe what percentage of bot strings are translated, whether all commands carry localized help text or whether any strings fall back to English when a translation is missing.

Group moderation covers five behaviours and the plugin system allows external commands

Group moderation in Levanter covers five automatic behaviours: anti-link (blocking messages with URLs), anti-spam, anti-word (blocking configured forbidden words), warnings and welcome/goodbye messages. These are listed as features with no additional configuration details in the README excerpt.

The plugin system has two tracks. Built-in plugins ship with the repository under the plugins/ directory. External plugins are loaded as "eplugins", described as command plugins. The README does not document the eplugin loading mechanism, the plugin API, or how naming collisions are handled when an eplugin uses the same command name as a built-in.

Building WhatsApp bots on the official Baileys npm package directly, rather than through Levanter's framework, gives full control over session management and the message pipeline without the bot command layer, without the Bitbucket dependency and without the plugin architecture. The trade-off is that you write all moderation logic from scratch. Levanter's value is precisely that five group-moderation behaviours are already wired up, but you accept its architecture and its dependency chain to get them.

Version 6.2.0 ships with MIT licence, and the last push was on 2026-09-28.

Editorial conclusion

Levanter suits developers who need to automate WhatsApp messaging across multiple phone numbers from one deployment, or who want a ready-made bot with group moderation and media tools without building the command layer from scratch. It is not the right choice for multi-tenant platforms: a single API_KEY controls all sessions, so any application where different clients must be isolated requires a different architecture. Before deploying, verify that the Baileys dependency at the Bitbucket URL in package.json is reachable from your build environment, since yarn install will fail silently if it is not.

Frequently asked questions

Official sources

1. Issues
2. lyfe00011/levanter on GitHub
3. README