fdciabdul/waxum repository overview

⁠Waxum

WhatsApp REST API gateway. Written in Rust.

Docs⁠ · API⁠ · Releases⁠

Native single-binary. Multi-session. Multi-DB. Webhooks + HMAC. JWT + Bearer. Swagger. Prometheus. NATS JetStream (optional).

Two WhatsApp providers behind one API. Each session runs on the multi-device protocol (QR / pair code) or on Meta's official WhatsApp Cloud API. Both share the same /messages/* routes and the same webhook events.

Production-grade. 230+ REST endpoints across 34 feature modules.

⁠Features

⁠Messaging

⁠Scheduling & bulk send

⁠Voice & video calls

⁠Session management

⁠Groups

⁠Contacts / privacy / presence

⁠Media & storage

⁠Webhooks

⁠Ops / observability

⁠Storage backends

⁠Known limitations

⁠Console

Server-rendered ops dashboard baked into the binary. Point a browser at http://<host>:3451/, sign in with your SUPERADMIN_TOKEN, and you land on the fleet overview. Click any session for the per-session playground covering 60+ REST endpoints — send messages, drive calls, manage groups, inspect webhooks, all without leaving the tab.

⁠Install

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/imtaqin/waxum/main/scripts/install.sh | sudo bash

# Windows (elevated PowerShell)
irm https://raw.githubusercontent.com/imtaqin/waxum/main/scripts/install.ps1 | iex

# Docker
docker pull fdciabdul/waxum

Or build from source:

git clone https://github.com/imtaqin/waxum && cd waxum
cargo build --release
./target/release/waxum

⁠Toolchain

waxum builds on a pinned Rust nightly — nightly-2026-04-05. You do not have to select it: the pin lives in rust-toolchain.toml, and rustup reads that file and installs the right toolchain on your first cargo build. If you have rustup, there is nothing to do.

To install it up front, or to check what you are actually building with:

rustup toolchain install nightly-2026-04-05 --component rustfmt --component clippy
rustup show active-toolchain   # from the repo root; expect nightly-2026-04-05-<host>

Do not run rustup default nightly. That selects a floating latest nightly globally, which is not what this project builds against.

Without rustup, the pin does not apply. rust-toolchain.toml is a rustup feature; a distro-packaged, Homebrew, or Nix cargo ignores it silently — no warning, no error, just a different compiler than the one we test. If a build fails in a way this section does not explain, check cargo --version before anything else.

If you force stable — cargo +stable build — we cannot tell you what happens, because nobody has run it. Historically it failed inside upstream whatsapp-rust with error[E0554]: #![feature] may not be used on the stable release channel⁠, which is the error this pin was introduced to prevent. That cause is gone at the revision we now pin, so a stable build may well succeed — it is simply unverified, and therefore unsupported.

The pin is historical. Upstream whatsapp-rust used the unstable portable_simd feature, which is nightly-only; at the revision waxum currently pins, upstream has removed SIMD from its tree and declares a stable MSRV, and waxum itself uses no unstable features. The pin has not been re-validated against stable, so it stays until someone does that end to end. Tracked in #87⁠.

⁠Dependencies

The WhatsApp protocol layer is not ours. It is whatsapp-rust⁠, a third-party project, and waxum pins eight of its crates to a single git revision rather than to crates.io versions. That is a deliberate choice with real consequences for anyone depending on waxum — including that waxum cannot itself be published to crates.io. The reasoning, the risk, and the bump cadence are written down in docs/DEPENDENCIES.md⁠.

⁠Providers

Each session has a provider:

A Cloud session sends and receives through the same /messages/* routes: text, media, location, contact, reaction, buttons, list, and read receipts. Meta's webhooks are normalized into the same message event, so a consumer works unchanged across both providers.

On top of that, a Cloud session gets:

Full reference: waxum.imtaqin.id/docs/api/cloud⁠.

⁠Endpoints

⁠Stack

Rust nightly · Axum 0.8 · Tokio · whatsapp-rust⁠ · Postgres/MySQL/SQLite · NATS JetStream · Prometheus · Utoipa.

⁠Ecosystem

⁠Docs

Everything else — endpoints, webhooks, health probes, deployment, .env reference — lives in the docs:

waxum.imtaqin.id⁠

⁠License

MIT