Skip to content

About

WhatsApp REST API built with Hono + TypeScript and features Dual-Runtime Support (runs natively on Bun or Node.js). Includes a built-in AI Routing for auto reply & Visual Dashboard for easy management.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

API Baileys WA Socket

WhatsApp REST API powered by Baileys WA Sockets. Built with Hono + TypeScript and features Dual-Runtime Support (runs natively on Bun or Node.js). Includes a built-in Visual Dashboard for easy management, keep clean simple and avoid heavy over-engineering.

Note

This project is not meant to be a full-fledged WhatsApp server. It is a wrapper around the Baileys library, providing an HTTP interface for easier integration with other applications, don't use it for spamming or any activities that's prohibited by WhatsApp META.

Disclaimer: This project is 100% AI-assisted and intended for educational purposes only. It will be maintained as a side project in spare time only, with no guarantees of ongoing support, updates, or production readiness.

Thus, we do not store WhatsApp messages or any other data (aside from credentials for auto-reconnecting).

Release history lives in CHANGELOG.md; this README stays version-agnostic.


✨ Features

Feature Description
Dual Runtime Support Run on ultra-fast Bun or standard Node.js (cPanel/VPS compatible)
Visual Dashboard Built-in UI to manage sessions, webhooks, and send messages
Dashboard RBAC Role-based access (admin, manager, assistant) + approvals
Session Assignment ACL Optional per-user assigned sessions (dashboard scope only)
Multi-Session Manage multiple WhatsApp accounts simultaneously
QR Code & Pairing Code Connect via QR scan or 8-digit pairing code
Complete Chat API Send text, media, forward, delete, read messages
Broadcast Queue Bulk message sending with anti-spam delays
Group & Profile Full management (create, participants, status, picture)
Media Handling Download, process, retrieve, and auto-cleanup old media
Webhook System Retries, exponential backoff, and signature modes
AI Auto-Response Per-number OpenAI-compatible agent with time routing and RAG tools
AI Tooling Optional send-message tool, web search (SearXNG) and image vision
Group Reply Policy Groups are AI-only, scoped by mention/senders, opt-in static fallback
Static Auto Reply One policy: both, window-only, or failure fallback
Dual Auth State Save session data to Files (dev) or Redis (production)
API Authentication Bearer token or Redis-stored API keys with roles
Hardened Dashboard Auth JWT auth, stream token for SSE, password policy, approval flow
Swagger/OpenAPI Built-in interactive API documentation at /docs
Docker Support Ready-to-use Dockerfiles for both Bun and Node.js

Overview dashboard

The first dashboard page is an analytics view, not a status table:

  • KPIs: sessions connected, AI replies, skipped routing decisions, average latency, failures.
  • Routing Decisions (donut): AI, static, skipped, failed. "Skipped" counts inbound messages the router declined to answer (human-owned chat, AI off, outside its window) — it is not a count of messages a human sent.
  • Hourly Activity (stacked bars): the 24 in-memory buckets.
  • Daily Trend (line): persisted daily totals, 7 or 30 days.
  • Top Sessions (horizontal bars) and Recent Decisions (table).
  • Health: webhook delivery rate, dead letters, memory scopes, Redis — hidden for assistants, who have no integrations to monitor.
  • Server Health (admin): availability from the daily API history against a 99.5% target, and P50/P95/P99 latency split by surface — API (request to response), sendMessage (Baileys promise) and inbound (message received to handler finished) — plus send failures and timeouts, reconnect attempts with success rate and last downtime, session counts (open / connecting / need QR / closed) and queue depth (broadcast, AI debounce, dead letters).

Percentage samples live in bounded rings (1024) and reset with the process, so they are labelled "since restart"; availability is aggregated from the daily metric file and therefore covers the selected range. Availability and API latency need AUDIT_LOG_ENABLED=true, because they are derived from the API audit ring. Deliberately not reported: CPU percentage, event-loop lag, GC pauses and file descriptors. Each needs a sampler or is platform-specific, and none of them helps diagnose a WhatsApp gateway more than reconnects and send latency do.

Data honesty: in-process counters are labelled "since restart", because they reset with the process. The daily series is persisted to data/metrics/daily.jsonl with one line per day per session, pruned to METRICS_HISTORY_RETENTION_DAYS (30) on every write, so the file cannot grow without bound. No scheduler: the rollover is lazy, flushed by the first metric of a new day.

Live updates: a 20s poll plus the existing event stream, both coalesced. A hidden tab stops both; returning to the tab refreshes at most once every few seconds, so rapid tab switching cannot spam the API.

Charts use Chart.js from jsdelivr, pinned with SRI, like DOMPurify. When CSP_CDN=false the script is blocked and the page falls back to the numeric cards instead of breaking.

🚀 Quick Start

1. Prerequisite (Choose One Runtime)

  • Bun: Ultra-fast, ideal for VPS or Home Servers (Recommended).
  • Node.js: Standard, portable, ideal for cPanel VPS or traditional Node.js hosting.
  • Docker: Containerized deployment. Ensure you have Docker Compose installed.

2. Local Setup (Bun OR Node.js)

# Clone the repository
git clone <repository-url>
cd baileys-wa-api

# Configure Environment
cp .env.example .env
# Edit .env and configure DASHBOARD_JWT_SECRET

Running with Bun (Fastest)

bun install

# Development (Auto-reload)
bun run dev

# Production Build
bun run start

Running with Node.js (Highest Compatibility)

npm install

# Development (via tsx watch)
npm run dev:node

# Production Build
npm run start:node

The API will start at http://localhost:3000. Access the following default routes:

  • 🖥️ Dashboard: http://localhost:3000/dashboard/
  • 📖 Swagger Docs: http://localhost:3000/docs
  • 💚 Health Check: http://localhost:3000/status

🤖 AI Auto-Response (time-based routing + RAG tools)

Inside a configured window the AI answers; outside it humans do. Per-number settings live in the session metadata (dashboard), so every WhatsApp number has its own window, model, instruction and knowledge endpoints.

Built-in send tool (optional)

AI & Routing → AI Capabilities → Allow AI to send WhatsApp messages adds send_whatsapp_message to the tool list on every request when enabled. It is off by default and text-only.

  • Scope — allowlist (default: the current chat plus listed numbers/JIDs) or any. The originating chat is always allowed; receiver is optional and defaults to it.
  • Rate limit — maxPerHour sliding window per session, enforced before the send; the model cannot bypass it.
  • Groups — still governed by ALLOW_GROUP_SEND / ALLOWED_GROUP_JIDS.
  • Execution — the tool calls the same service as POST /api/v1/messages; it does not make an internal HTTP request or carry an API key.

Built-in web search (optional, SearXNG)

AI & Routing → AI Capabilities → Allow Web Search adds web_search to the tool list. It needs a SearXNG instance configured on the server through SEARXNG_URL; when that variable is empty the tool is never advertised to the model and the toggle stays disabled.

  • The model only supplies the query string. The destination host always comes from operator configuration, like AI_BASE_URL.
  • The instance must return JSON: add json to search.formats in its settings.yml, otherwise the tool reports a non-JSON error.
  • Results are bounded (SEARXNG_MAX_RESULTS, 1–10) with HTML stripped from titles and snippets, private/loopback result links dropped, and the total capped by AI_TOOL_MAX_RESPONSE_CHARS.
  • Snippets are labelled untrusted data, so instructions inside them are not treated as operator policy.

Media and link context

  • Captionless images, videos, audio and documents are described with metadata ([media: image, mime: ...]) so they still reach the AI instead of falling straight to the static reply. Video/audio contents are not processed.
  • Optional image understanding is a per-session toggle in AI & Routing. Inbound images are downloaded in memory, bounded and re-encoded to JPEG, sent as image_url parts, then discarded. Nothing is stored in the chat history or media directory; history keeps a text placeholder only. The optional vision model uses the same base URL/API key; empty means the main model, and a rejection falls back once to a text-only descriptor.
  • Customer links get bounded title/description previews through a DNS/private-IP checked, redirect-rejecting, size-capped fetch. Previews are untrusted data in the user prompt; the model cannot fetch arbitrary URLs.

OTP / verification auto-reply filter

AI & Routing → AI Capabilities → Message Filter / Ignore OTP / Verification Messages is an optional deny-list for messages that should not receive an automatic reply (OTP, login codes, verification notices).

  • Ignored Senders (Ignore List) — one phone number or JID per line. Sender matching also checks group participants.
  • Detection Mode — Keywords Only matches the phrase list directly, which is also usable for non-OTP filtering. Smart OTP / Verification (default) uses the same phrases as positive signals and adds a score for built-in code shapes near them; no OTP phrase is hardcoded.
  • Sensitivity (smart mode only) — conservative 6, balanced 5, aggressive 4. A code alone never matches; a phrase alone never matches.
  • Exclude Keywords — subtract from the smart score and prevent a direct match in keyword mode, so "I did not receive the code" is not swallowed.
  • A match skips both the AI and static auto-reply. Messages are still stored and webhooks still fire.
  • OTP content is never written to the filter log; only the match reason and, in smart mode, the score are logged. The filter is disabled by default.

Internal identifiers

Two layers, with different jobs.

1. Deterministic removal (src/services/redaction.ts) before anything reaches the model — history, current texts and tool output — and again on the reply:

  • raw WhatsApp addresses (…@s.whatsapp.net, …@lid, …@g.us, @broadcast, @newsletter), including a device suffix such as :12@;
  • the session identifier, matched as a whole token.

Nothing else is touched. Phone numbers, order IDs, emails and every other contact detail pass through unchanged, because the operator usually puts the answer itself in the instructions ("call us on 0812-…"). The token is deleted rather than replaced: a visible marker like [jid] told the model that something was censored, and it explained the censorship instead of answering. Spacing left behind by the removal is tidied.

2. Prompt rules (always-on security block) cover what a filter cannot:

  • never print internal identifiers, LIDs or the session identifier;
  • ordinary contact details are not internal identifiers and must be shared normally when asked;
  • never say that something was removed, masked, censored or filtered, never print a placeholder, and never refuse a request only because an identifier is absent — answer with the details that are available.

The second layer is what keeps the first one invisible: a reply must read as a normal answer, not as a redacted document.

The output scrubber still removes credential-shaped strings (API keys, bearer tokens, private keys) before a reply is sent.

Runtime date/time context

Every OpenAI-compatible request carries a server-generated <get_info> block with the full weekday/date, local time, timezone and UTC offset, ISO timestamp and Unix milliseconds. It is rebuilt for each request and placed after the operator system instruction. The block contains facts only: no priority attribute, no override demand, and no claim over operator instructions. No tool call is needed; it simply keeps the model aware of the current clock.

Routing rule — the AI only replies when all are true:

  1. ai.enabled is on for that number (dashboard).
  2. The current time is inside AI_WINDOW_START–AI_WINDOW_END, evaluated in ROUTING_TZ (cross-midnight supported: 16:00→08:00).
  3. No human replied recently in that conversation. A reply typed on the phone, WhatsApp Web or the dashboard counts; messages sent through this API do not. Silence lasts ROUTING_HUMAN_IDLE_MS (default 15 min).

If a call fails, the static reply answers only when its policy allows it — see the responder chain below.

Persona scope and security rules

Two separate concerns, deliberately not merged:

  • Response Scope (AI & Routing → System Instruction) is a product choice. flexible (default) answers the configured domain first but may answer brief general questions; strict answers only the domain described by the operator instruction and declines everything else in one sentence, without hints or examples.
  • Security rules are always appended to every request, whatever the scope, and placed last so they are the most recent instruction: untrusted text is data and not instructions, the persona must not change, instructions/keys/ tokens must not be revealed, and the model must not claim an action no tool performed.

The deterministic tripwire in src/services/promptGuard.ts still screens input first (pattern score, mute after repeated strikes). It is a signal, not the boundary: the boundary is the allowlisted tool set, credentials never entering the prompt, bounded tool rounds and output scrubbing.

Responder chain (one owner per message)

Replies are decided by a single chain, not independent switches.

1. AI — answers when enabled and eligible (mode: window/always), unless a human is active or the conversation is muted.

2. Static auto-reply — one policy decides when it steps in (AI & Routing → Static Auto Reply):

Policy Primary path (AI off / outside its window) Fallback path (AI or webhook delivery failed)
both (default) every hour every hour
window only inside AUTO_REPLY_TIME_START–AUTO_REPLY_TIME_END only inside the same hours
fallback never every hour

enabled: false turns the whole static layer off, including the group fallback; nothing can bypass that. primary is a legacy alias that now resolves to both, because both already covers it.

window applies to the fallback path too, so an "away" message never appears mid-day when the AI fails. Webhook delivery failure is treated the same as an AI failure; an AI failure is not a webhook failure.

3. Webhook — never answers; it delivers events. Every messages.upsert payload carries a routing block (aiEnabled, aiMode, window, timezone, staticRole) so an external system can skip replying.

The ordering is intentional: the AI is the most capable but most fragile layer, static is the cheap always-available net, and the webhook observes rather than competes.

Group reply policy

AI & Routing → Group Reply decides which group messages are addressed to this number:

Policy Answers
mention (default) only when the account is @mentioned or one of its messages is quoted
senders only listed participants, in any group
all every participant, every group
  • Identity matching resolves PN/LID both ways, because a member may mention the account's LID while the operator typed a phone number.
  • Groups are AI-only by default. Static replies are never sent to a group; silenced groups stay silent instead of receiving a canned message.
  • Fallback to Static Reply in Groups is an explicit opt-in. When on, a group message the policy considers addressed still receives the static reply while the AI is disabled, outside its window, or failing. Off by default: a repeated fixed message in a group is the clearest robot signature.
  • Messages are always stored and webhooks always fire; only automatic answers are gated. Direct chats are unaffected.
  • The card is hidden when both the AI and the static auto-reply are off.

Response modes: static vs LLM

The static auto-reply and the LLM coexist; the mode decides who answers.

Setting Behaviour
ai.enabled = false Static rules (AUTO_REPLY_*) own direct chats
ai.mode = "window" (default) LLM inside the window; outside it the static policy applies
ai.mode = "always" LLM answers 24/7 — “full handle”

ai.mode = "off" is a legacy value. It duplicated the enable switch and is no longer selectable; opening the AI page rewrites it as enabled: false with mode window, and the resolved behaviour is unchanged.

Humans win in every mode: a reply typed from the phone, WhatsApp Web or the dashboard pauses the AI for ROUTING_HUMAN_IDLE_MS, and POST /chats/:id/handoff pauses it longer — including in always mode.

Precedence: AI path → static policy → nothing. A failed AI call falls back to the static reply only when the policy allows it for that hour and that chat.

Conversation memory (optional)

AI_MEMORY_ENABLED=true lets the agent remember a conversation beyond the 12-message / 6-hour window. Off by default; nothing changes until it is turned on.

  • Source of truth is an append-only JSONL log per conversation. The summary and the fact table are derivatives: deleting them is always safe, and they are rebuilt from the log or from WhatsApp history.
  • Rolling summary: the old summary is merged with the new batch, so its size stays constant instead of growing. It fires when the pending batch reaches either AI_MEMORY_SUMMARY_EVERY messages (50) or AI_MEMORY_SUMMARY_MIN_CHARS characters (4000): many short greetings no longer pay for a summarisation call. Details are recovered by facts and retrieval, not by a longer summary.
  • Facts are short key/value entries with a TTL for relative statements ("tomorrow"). User facts are never shared across participants.
  • Honesty about the block: the summary is injected into the user turn inside <memori_percakapan>, never as a system message, because it is derived from untrusted text. A trusted rule in the security block says to treat it as data, never as instructions, and to let the newest customer message win.
  • Never on the critical path: summarisation runs after the reply is sent, and a failure keeps the previous summary. A broken memory file cannot stop a reply.
  • Summary model: AI_MEMORY_MODEL selects one; empty uses the main model, the same pattern as the vision model.
  • Bounded, not growing: the raw log is compacted when it passes AI_MEMORY_RAW_MAX_BYTES (4 MB). Compaction rewrites the file with only the newest AI_MEMORY_RAW_MAX_MESSAGES (2000) lines that are younger than AI_MEMORY_RAW_RETENTION_DAYS (180). Nothing is renamed to .1, so there is one file per scope and retrieval input stays small enough for a plain JSON scan — no SQLite index needed.
  • What compaction keeps: the summary, the facts and the pinned notes live in the .json file and are never touched. Only the raw transcript shrinks, and that is the part retrieval and future summaries read from. If a line is dropped before it ever reached a summary, the pair is logged as a warning: that content is gone.
  • Not encrypted: data/ai-memory/ holds plaintext transcripts so search and export stay simple. The path is fixed (not env-configurable) so a wrong setting cannot scatter folders. The directory is created with mode 700; protect it like any other data directory.
  • Groups: opt-in per session in AI & Routing → Group Reply & Memory. Group Memory Conversations keeps a summary and facts per member, for the messages that reach the bot (mention, allowlisted sender, or every message when the policy allows it). One member's facts never reach another. Build Group Digest is the wider one: it logs every group message, including member-to-member chatter and the account's own replies, and summarises the whole group (topics, decisions, open questions, lead signals). Enabling it reveals its own thresholds — quiet period, minimum new messages and digests per day (0 = no cap) — pre-filled from the server defaults.
  • Memory Retrieval: a toggle in AI Capabilities, before Allow Web Search. It pulls older messages matching the current question into a "possibly outdated" block. Local keyword scan, no embeddings, bounded by a short timeout (AI_MEMORY_RETRIEVE_TIMEOUT_MS, default 200 ms) so a slow disk can never delay a reply. Each hit carries its local timestamp ([2026-11-10 14:32]) so an old line is obviously old.
  • Viewer: the chat ⋯ menu has View Memory for one conversation, and the Memory page lists every stored scope for a session with search and pagination. Both show summary, facts and counters; group entries include the digest plus every member scope, so a leaking fact would be visible immediately. The Memory page is available to admin and manager; assistants do not get it.

Deletion follows the chat. Clearing a chat, deleting it, exiting and deleting a group, deleting a session, or using End Chat removes the matching memory files. A group deletion also removes the group digest and every participant scope belonging to that group.

End Chat forgets the assistant memory but keeps the messages. If the chat comes back later, the next inbound message starts a fresh scope and one seed summary is built from whatever history is available, so the agent does not start from zero.

Export in the chat ⋯ menu downloads one JSON bundle per chat (summary, facts and the raw log). Group exports include the digest and every participant scope.

Tuning (env defaults, overridable per number in the UI)

Variable Default Meaning
AI_MODE window window / always (legacy off = AI disabled)
AI_TEMPERATURE 0.6 Sampling temperature
AI_TOP_P 0.95 Nucleus sampling
AI_MIN_P 0.05 Min-p (sent only to OpenRouter bases)
AI_MAX_TOKENS 1024 Reply budget
AI_TIMEOUT_MS 25000 Provider request timeout
AI_TOOL_MAX_ROUNDS 2 Tool-call rounds per reply
AI_HISTORY_MAX_MESSAGES 12 Prior messages sent as context
AI_HISTORY_MAX_AGE_MS 21600000 Ignore history older than 6 hours
AI_HISTORY_MAX_CHARS 8000 Character budget for the history block
AI_GUARD_ENABLED true Prompt-injection guard on/off
AI_GUARD_MAX_INPUT_CHARS 4000 Input cap before refusal
ROUTING_BATCH_IDLE_MS 20000 Debounce window per conversation. The actual wait is drawn from ±25% of this value each batch (20s → 15–25s), so replies never land on the same interval
ROUTING_BATCH_MAX_WAIT_MS 60000 Hard cap from the first message
ROUTING_HUMAN_IDLE_MS 900000 Human-activity pause

Precedence: session metadata overrides env, and the dashboard UI writes session metadata. Nothing requires a database.

Drivers

AI_DRIVER Talks to Needs
openai (default) any OpenAI-compatible /chat/completions — OpenRouter, OpenAI, Groq, Together, Ollama AI_BASE_URL, AI_MODEL, per-number key
webhook your own agent gateway (e.g. apiLLM) AI_AGENT_URL

Both drivers produce the same output (one reply text), so switching later is a configuration change.

The dashboard exposes the OpenAI-compatible driver only. The webhook driver is an advanced/env-only option for gateways that speak the custom event contract instead of OpenAI's; if your gateway is OpenAI-compatible, point Base URL at it and keep the default driver.

Default sampling values: temperature 0.6, top_p 0.95, min_p 0.05 (sent only when the base URL is OpenRouter), penalties 0, max_tokens 1024. Empty fields fall back to these, so a provider's own defaults apply only when you clear a value on purpose.

Per-number configuration

GET   /dashboard/api/sessions/:sessionId/ai-config
PATCH /dashboard/api/sessions/:sessionId/ai-config

PATCH body (every field optional, merged):

{
  "routing": { "aiWindowStart": "16:00", "aiWindowEnd": "08:00", "timezone": "Asia/Jakarta",
               "humanIdleMs": 900000, "handoffPauseMs": 1800000 },
  "ai": {
    "enabled": true,
    "driver": "openai",
    "baseUrl": "https://openrouter.ai/api/v1",
    "model": "openai/gpt-4o-mini",
    "systemInstruction": "You are a professional assistant. Answer clearly, concisely and politely in the customer's language. Never invent facts; use the available tools when data is required.",
    "ragEndpoints": [],
    "credentialsJson": "{\"apiKey\":\"sk-or-...\",\"endpoints\":{}}"
  }
}

Credentials are encrypted before persisting (AES-256-GCM) using CONFIG_ENC_KEY and are never returned by the API — reads only report credentialsSet / credentialsEncrypted. Logs redact them by key name.

Knowledge endpoints (simple RAG, no vector DB)

Each endpoint declares its own parameters — nothing is hardcoded. They are converted into tool schemas, so the model decides when to call them.

{
  "name": "web_search",
  "description": "Search the web for general information.",
  "method": "GET",
  "url": "https://api.duckduckgo.com/",
  "params": [
    { "name": "q", "type": "string", "description": "Search query", "required": true },
    { "name": "format", "type": "string", "description": "Response format", "default": "json" }
  ],
  "timeoutMs": 6000,
  "maxResponseChars": 1500
}
{
  "name": "check_weather",
  "description": "Get the current weather for a location (no API key required).",
  "method": "GET",
  "url": "https://api.open-meteo.com/v1/forecast",
  "params": [
    { "name": "latitude", "type": "number", "description": "Latitude", "required": true },
    { "name": "longitude", "type": "number", "description": "Longitude", "required": true },
    { "name": "current_weather", "type": "string", "description": "Return current weather", "default": "true" }
  ]
}

Parameter can target query, body or path (in). Path placeholders use {name}, e.g. /api/members/{member_number}/detail.

Prefer the provider's own contract? Pass a raw JSON Schema instead of the params list — it is forwarded to the model untouched:

{
  "name": "search_users",
  "method": "GET",
  "url": "https://api.example.com/v1/users/search",
  "parameters": {
    "type": "object",
    "properties": {
      "q": { "type": "string", "description": "Name, email or member id" }
    },
    "required": ["q"]
  }
}

With parameters, every argument the model produces is sent as a query string for GET and as the JSON body otherwise — no per-parameter metadata is needed.

Credentials per endpoint live in the encrypted blob, never in the prompt:

{ "apiKey": "sk-or-...", "endpoints": { "web_search": { "headers": { "X-API-Key": "..." } } } }

Safety limits: URL always comes from configuration (never from the model), optional private-host block (AI_TOOL_BLOCK_INTERNAL), per-endpoint timeout, response truncation (AI_TOOL_MAX_RESPONSE_CHARS) and AI_TOOL_MAX_ROUNDS to stop tool loops.

Status: routing window, human-activity detection, idle debounce, provider call, tool-calling and AI→human handoff are implemented.

  • Messages are collected until the chat is idle for ROUTING_BATCH_IDLE_MS (reset on every new message), capped by ROUTING_BATCH_MAX_WAIT_MS from the first message and by ROUTING_MAX_BATCH_MESSAGES. One idle window → one prompt → one reply.
  • After human activity the conversation stays human-owned for ROUTING_HUMAN_IDLE_MS; the backlog that arrived meanwhile is answered in a single prompt when the pause expires.
  • Exactly one timer is armed per conversation; a stale timer can never fire a reply (epoch guard), so there is no periodic polling.

AI → human takeover

The model (or your gateway) can stop the bot for one conversation:

POST /chats/:sessionId/handoff
{ "conversationId": "628xxx@s.whatsapp.net", "reason": "customer_minta_manusia", "pauseMinutes": 30 }

While paused the AI is silent, and messages that arrive during the pause are not queued: a human already handled that conversation, so answering the backlog after the pause would talk over them. A human reply — from the phone or from the dashboard — extends the pause for humanIdleMs. pauseMinutes is clamped to 1..1440 (default 30).

A reply that is already being generated when the pause starts is discarded instead of delivered.

Manual takeover

An operator can hold a conversation outright, so the AI never answers it:

POST   /dashboard/api/sessions/:id/chats/:jid/takeover   { "hours": 24 }
DELETE /dashboard/api/sessions/:id/chats/:jid/takeover
GET    /dashboard/api/sessions/:id/takeovers

Any role that can reply can take over and release. The claim lasts 24 hours by default (1..168) and is stored in sessions/md_<sessionId>/takeover.json, so it survives a restart — an in-memory flag would let the bot resume talking over staff after a deploy.

Agent replies (webhook driver)

With ai.driver = "webhook" the inbound event is handed to an external agent. That agent must answer through a route that re-checks ownership at send time:

POST /agent/:sessionId/reply      Authorization: Bearer <AI_SERVICE_TOKEN>

It answers 409 with { humanOwned: true, humanOwnedUntil } while a human owns the conversation, and is disabled (404) when AI_SERVICE_TOKEN is empty. This is deliberately separate from /chats/:sessionId/send: blocking the generic send route during a takeover would also block legitimate transactional traffic, which cannot be told apart from an agent reply.

Migration required. The takeover check applies only to agents that call this endpoint. An existing agent that keeps posting to /chats/:sessionId/send still replies during a human takeover — that route stays open for business traffic and cannot distinguish the two.

A debug line (LOG_LEVEL=debug) marks any message that reaches the generic route while the conversation is human-owned. It is an activity signal, not attribution: a business notification produces the same line as an un-migrated agent.

Checking the endpoint the agent is configured to call establishes its migration status — whether it can be the sender of such a line — but it does not identify the sender of a particular entry. If the agent still uses the generic route, its messages are indistinguishable from business traffic in the log. Per-message attribution would need the caller to identify itself, which this API does not ask for. The dispatch payload advertises reply.endpoint, so an agent that reads it moves over without a config change.

Prompt-injection & abuse control

Layers, weakest to strongest:

  1. Tripwire (heuristics) — obvious override / jailbreak / secret-probe patterns are refused before any provider call (AI_GUARD_BLOCK_SCORE, default 50). Heuristics are a signal, not a boundary.
  2. Instruction hierarchy — customer text is wrapped in <pesan_pengguna>…</pesan_pengguna> and the system prompt states that this is data, never instructions.
  3. Least privilege — tools only come from the configured allowlist, the URL is never model-controlled, credentials never enter the prompt, and tool rounds plus response size are bounded.
  4. Output scrubbing — credential-shaped strings (API keys, bearer tokens, private keys) are redacted from the reply before it is sent.
  5. Abuse control — after AI_GUARD_MAX_STRIKES blocked messages the conversation is muted for AI_GUARD_MUTE_MS. Messages received during a mute are ignored and not queued, so nothing stale is answered when the mute expires; the next genuine message resumes normal handling.

Honest limit: heuristics can be rephrased, so layers 3–5 carry the real protection — the tripwire mainly stops scripted abuse and produces the signal used for muting.

Dashboard page

A dedicated AI & Routing page (#ai, requires manageSessions) configures everything per number — responder mode, window, model/credentials, system instruction and knowledge endpoints — and shows live routing metrics. It reuses the existing dashboard components (cards, form groups, badges, tables), so it looks and behaves like the rest of the dashboard.

Routing metrics

GET  /dashboard/api/ai/metrics?sessionId=<optional>
POST /dashboard/api/ai/metrics/reset

Counters are kept in memory (no database): AI replies, human-handled, static replies, failures, tool calls, tokens and latency, plus 24 hourly buckets and the most recent decisions. They are visible while the app is running and reset on restart. Redis-backed persistence can be added later without changing the endpoints.

Brute force & rate limits

Layer Default Env
Dashboard login per IP 5 requests/min (built-in)
Login lockout per account and per IP 10 failures in 15 min → 15 min lock AUTH_MAX_FAILURES, AUTH_FAILURE_WINDOW_MS, AUTH_LOCK_MS
REST API per key 60 requests/min RATE_LIMIT_API_KEY
Send per session+IP 30 requests/min (built-in)
Concurrent sends per session 5 MAX_CONCURRENT_SENDS
Send timeout 30 s SEND_TIMEOUT_MS

Lockout responses are generic (ACCOUNT_LOCKED) and unknown usernames are tracked too, so locking does not reveal whether an account exists. Rate-limited responses carry Retry-After, a stable code (RATE_LIMITED, SESSION_BUSY) and retryable: true.

For a public deployment, also put a limiter in front: nginx limit_req_zone/limit_conn_zone, Cloudflare rate limiting or fail2ban for repeated 401/429s. In-process limits protect one instance; the proxy protects the whole fleet.

Clearing vs deleting a chat

Both actions live in the ⋯ menu attached to a chat — either in the chat header or on each row of the chat list — so they apply to that chat only. They stay in sync with WhatsApp and are never bulk operations, so they do not create a spam pattern. The same menu offers Reload and Mark Read.

Action WhatsApp Dashboard
Clear Chat chatModify({ clear: true }) — history removed, chat stays messages removed, room stays open and empty
Delete Chat chatModify({ delete: true }) — chat removed room and messages removed from the list

One request per action. If the remote call fails the dashboard keeps its local copy and returns 502, so the two sides never diverge silently. A disconnected session returns 409. There is deliberately no "clear/delete every chat" button: doing that through the socket would mean hundreds of requests and a real ban risk. To clean another chat, open it and act on it individually.

The Groups page offers the same pair per group: Clear Chat (clears the group chat on WhatsApp and locally) and Exit & Delete (POST /groups/:sessionId/leave-and-delete/:jid, which deletes the chat, leaves the group and removes it locally). Both use the dashboard confirmation modal — the same dialog as chat clear/delete — instead of a native browser prompt.

Changes made on the phone are mirrored back automatically: messages.delete with { jid, all: true } empties the cache for a cleared chat, and chats.delete removes the room locally.

Session config persistence & cleanup

Per-number settings (webhook, AI/routing, autoReply, owner) are written to sessions/md_<id>/metadata.json (file backend) or the Redis auth hash, so a restart reconnects the session with the same configuration. Deleting a session removes its auth folder, metadata and store file, and revokes every API key scoped to that session so a recreated session with the same id cannot reuse an old key.

Session janitor, snapshots and error messages

  • Startup janitor removes leftovers deletion/reconnect can leave behind: temp files older than an hour, store JSON without an auth directory (file backend only) older than an hour, and md_<id> directories without creds.json older than a day. Valid sessions (creds present) are never touched. It runs at startup and daily; run it manually with bun run cleanup-sessions.
  • Snapshots only write when state changed (dirty flag) instead of rewriting the JSON every 60 s. MAX_MESSAGES_PER_CHAT (default 50) caps messages kept per chat; it is per chat, so other chats are never skipped — only older messages in each chat are dropped (AI context has its own limit).
  • 5xx messages are sanitized in production: callers get "Internal server error" while the original message is logged. 4xx validation messages and development output stay detailed.

Storage, SSRF and credential handling

  • Session ids are validated at every storage boundary (^[A-Za-z0-9_-]{1,64}$): routes, connection manager, auth-state files and Redis keys. A malformed id cannot escape sessions/, so delete/metadata operations cannot touch other files.
  • Media URLs are checked before sending (MEDIA_BLOCK_INTERNAL, default true): a /messages request that points at localhost, a private range or a link-local host returns 400 MEDIA_URL_BLOCKED instead of making the server fetch it.
  • API keys are stored hashed and resolved with a single Redis HGET (or the cached file store) plus one legacy GET; the auth path no longer runs KEYS/full scans, and lastUsedAt is written at most once per minute per key.
  • Media file downloads resolve inside media/ with a separator-aware check.
  • Audit JSONL appends are asynchronous, so disk latency never delays a response.

🔐 Deployment security (TLS & reverse proxy)

The API speaks plain HTTP; terminate TLS in front of it (Caddy, nginx, Cloudflare, an ALB). Never publish port 3000 to the internet.

Subpath hosting is not supported. The dashboard, REST API, docs, SSE and session cookie use absolute root paths (/dashboard, /api/v1, /docs, Path=/dashboard). Mounting the gateway under an arbitrary subpath (for example /gateway), with or without prefix stripping, breaks assets, cookies and API calls. Run it at the root of its host. Subpath support would require a BASE_PATH implementation across routes, assets, cookies, CSP and clients.

Internet ──HTTPS──> proxy (TLS) ──HTTP──> api:3000 (compose network only)

Required settings behind a proxy

Variable Value Why
NODE_ENV production enables fail-closed JWT and rate limits
TRUST_PROXY true per-IP rate limiting from X-Forwarded-For; enables HTTPS detection (X-Forwarded-Proto) for the Secure cookie, HSTS and the HTTP→HTTPS redirect for /dashboard
DASHBOARD_JWT_SECRET long random value dashboard auth is disabled when this is missing/default
CORS_ORIGIN explicit origin(s) with * only same-origin browser requests are reflected

What the app enforces once TLS is in front

  • Dashboard session lives in an HttpOnly, SameSite=Strict, Path=/dashboard cookie (plus Secure over HTTPS). Nothing is stored in localStorage, so XSS cannot read the token. Bearer auth is still accepted for API/agent clients.
  • SSE (/dashboard/api/events/stream) authenticates by cookie; no token in the query string (those end up in proxy access logs).
  • Content-Security-Policy (same-origin scripts and <style> elements; inline style attributes are allowed because WebKit attaches one to native <select>), HSTS over HTTPS, X-Frame-Options: DENY, nosniff, no-referrer, restrictive Permissions-Policy.
  • Cross-origin requests to /dashboard/* are rejected with 403.
  • Plain-HTTP dashboard requests are redirected to HTTPS when TRUST_PROXY=true in production.

Optional hardening: restrict the dashboard to a VPN/Tailscale network or an IP allowlist at the proxy, and expose only /status + the REST API publicly.

🧱 Auth-state backend, Redis limits and broadcast persistence

Backend selection is sticky. AUTH_STATE_BACKEND accepts auto (default), file or redis. The first successful start records the choice in data/auth-state-backend.json; later starts reuse it. That is what stops auto from moving the store when Redis comes back: sessions written during an outage stay where they were written. If the recorded backend is redis and Redis is unreachable, startup fails instead of falling back to files.

Switching backends requires confirmation. Change AUTH_STATE_BACKEND to the new value and set AUTH_STATE_SWITCH_CONFIRM=true for one start. The app then records the new backend and starts with the (empty) new store so you can re-link by QR; the old store is left untouched and nothing is deleted. Remove the confirmation afterwards — it is a one-shot override, not a setting.

Session ownership and quotas. Sessions created from the dashboard record the creating user in ownerId. Non-admin users see their own sessions plus any assigned by an admin; legacy sessions without an owner keep the old assignment semantics. MAX_SESSIONS_PER_USER (default 3) and MAX_SESSIONS_PER_MANAGER (default 5) cap how many sessions a non-admin may create; admins are unlimited. Deleting a user can revoke every session they own (logout + credentials).

Dashboard markup is sanitized before insertion. The dashboard never assigns innerHTML; UI.setHtml runs markup through DOMPurify loaded from jsdelivr (pinned 3.4.17 with SRI) and fails closed to text when the sanitizer is absent. Because the asset comes from a CDN, keep CSP_CDN enabled (the default); with CSP_CDN=false the script is blocked and the dashboard renders text only. A devDependency on dompurify records the pinned version used for the SRI hash.

CSP and CDNs. The policy allows common CDNs by default (cdn.jsdelivr.net, unpkg.com, cdnjs.cloudflare.com, Google Fonts), because pinning a version and loading it from a CDN is normal practice. CSP_CDN=false locks the policy back to same-origin. Additional origins can be appended per directive with CSP_EXTRA_SCRIPT_SRC, CSP_EXTRA_STYLE_SRC, CSP_EXTRA_FONT_SRC, CSP_EXTRA_IMG_SRC and CSP_EXTRA_CONNECT_SRC (space-separated), so a specific CDN never requires disabling CSP.

Honest trade-off: an allowed CDN origin can serve any code the browser will execute. Pin exact versions and add integrity (SRI) for third-party scripts — CSP does not replace SRI. The built-in Swagger UI page does this already.

Swagger UI assets. DOCS_ASSETS=cdn (default) loads a version-pinned Swagger UI bundle from jsdelivr with SRI, and DOCS_ASSETS=local serves the copy from node_modules/swagger-ui-dist for offline installs. Both work under the same CSP.

CSP mode. CSP_REPORT_ONLY=true switches the header to Content-Security-Policy-Report-Only: violations are still posted to /dashboard/csp-report and are still printed in the browser console; the difference is that resources are not blocked. It is a staged-rollout tool, not a way to silence the console — keep enforcement (the default) in production and fix the violations. The console text is "Content Security Policy" (with spaces), so to hide only the diagnostics during development use the DevTools console filter -/Content Security Policy/i (leading - negates, matching is regex). On builds without regex negation, /Content Security Policy/ shows just those messages so they can be read or collapsed. The report endpoint accepts the opaque Origin: null that browsers send with reports.

Redis must not evict. The bundled Redis runs with --maxmemory-policy noeviction. With an eviction policy, hitting the memory cap silently drops arbitrary keys, including session credentials, which logs the WhatsApp session out. Failing writes loudly is the safer failure mode; raise --maxmemory / the container limit when you outgrow it.

Broadcast queues are in-memory. broadcastQueue is a plain in-process Map: enabling Redis does not make broadcasts survive a restart. Redis is used for auth state, API keys and the broadcast result cache only. If restart durability for broadcasts matters, it has to be implemented separately.

🏷️ Versioning & releases

Versions follow Semantic Versioning, decided by the Conventional Commit that introduced the change:

Commit Bump
feat: minor
fix:, perf:, security: patch
feat!:, refactor!:, BREAKING CHANGE major

Every release is tagged vX.Y.Z and recorded in CHANGELOG.md. Create the next one with:

bun run release:patch   # or release:minor / release:major
git push origin HEAD --follow-tags

The helper refuses a dirty tree, generates the changelog entry from commits since the previous tag, bumps package.json, commits chore(release): x.y.z and creates the annotated tag. It never pushes; the command above is the final manual step. Use node scripts/release.mjs patch --dry-run to preview.

🐳 Docker Deployment

The project provides configurations for both runtimes. Everything runs in a single API container; Redis is optional and never published to the host.

First, create your environment file:

cp .env.example .env
# edit .env (secrets, dashboard JWT, webhook flags, …)

Option A: Docker with Bun (Default & Recommended)

docker compose up -d
docker compose logs -f api

Option B: Docker with Node.js

The Node image compiles the TypeScript sources with Bun at build time and then runs the plain-JS bundle on native Node.js.

docker compose -f docker-compose.node.yml up -d
docker compose -f docker-compose.node.yml logs -f api

Redis options

Redis is optional and resolved at runtime from REDIS_ENABLED / REDIS_URL:

Scenario What to do
No Redis (file-based storage) REDIS_ENABLED=false in .env (default) — just run compose
Redis already on the VPS host REDIS_ENABLED=true and REDIS_URL=redis://host.docker.internal:6379
Redis already on the VPS in another container REDIS_ENABLED=true and REDIS_URL=redis://<host-or-container>:6379
Bundled Redis container REDIS_ENABLED=true, REDIS_URL=redis://redis:6379, then run compose with --profile redis
# bundled Redis (isolated: no host port is published)
docker compose --profile redis up -d
docker compose -f docker-compose.node.yml --profile redis up -d   # Node variant

The bundled Redis has no published port, so it never collides with a Redis already running on the VPS. Stop it with the same profile flag:

docker compose --profile redis down

Changing the port

PORT in .env is honored on both sides of the mapping, and the container health check follows it:

PORT=8080   # → host 8080 → container 8080, healthy

To stop containers: docker compose down


🖥️ Visual Dashboard

The API includes an intuitive, modular web dashboard to manage everything visually without touching the CLI.

Dashboard Configuration (.env)

DASHBOARD_ENABLED=true
DASHBOARD_REGISTRATION_ENABLED=false
DASHBOARD_REGISTRATION_REQUIRE_APPROVAL=true
DASHBOARD_JWT_SECRET=super-secret-key-change-me
DASHBOARD_PASSWORD_MIN_LENGTH=6

# Session ownership / quotas for non-admin users (0 = unlimited)
MAX_SESSIONS_PER_USER=3
MAX_SESSIONS_PER_MANAGER=5

# Keep CSP enforcing; see the CSP mode note in the security section
CSP_REPORT_ONLY=false

Initial Setup

  1. Open http://localhost:3000/dashboard/ in your browser.
  2. If data/dashboard-users.json is empty, you will be prompted to create the very first Admin Account.
  3. Create your account with a secure password (hashed via bcryptjs).
  4. Once created, recommended to set DASHBOARD_REGISTRATION_ENABLED=false in .env to prevent public sign-ups.

Role & Access Model

  • admin: all sessions plus users/approval/roles, create/delete, webhooks, AI, REST API keys and every messaging capability.
  • manager: assigned sessions (or all sessions when the admin ticks All Sessions). Can reconnect, edit session settings, manage webhooks, AI routing and REST keys for those sessions only, plus chats/groups/outbound. Can create a session — it is assigned to them immediately — and delete only the sessions they created. No account/user controls.
  • assistant: only assigned sessions, chat/group support with single-message outbound (Bulk Send is hidden). Can open Groups in view-only mode and Settings for account/password and About; role permissions, quick actions, Sessions, AI, webhooks, REST API, events and user management stay hidden. An empty assignment grants no session at all, so unassigned numbers never appear in dashboard or API responses.
  • Session creation is open to admin and manager, subject to the per-role session limit. Access is required to re-create an id that already exists, so a manager cannot take over a session they cannot see.
  • Deletion is narrower than access: admin deletes anything, manager deletes only sessions whose ownerId matches their account. A session an admin assigned to them stays visible but has no Delete button, and the API answers 403.
  • Managers receive a Reconnect action for disconnected assigned sessions; reconnect preserves persisted webhook/AI/routing settings and never deletes credentials.
  • Every session has one owner, stored in data/session-owners.json. Ownership is access: the owner always sees the session and gets the Delete action. A manager who creates a session becomes its owner; nothing is added to their assignment list.
  • An admin changes the owner from the session settings modal — pick another manager, or clear it. An unowned session is reachable by admins only, which is how a session is parked without deleting it.
  • Assignment still exists and still grants read access (used for assistants and for extra managers who should see a session without owning it), but it never grants delete rights. It can be edited from either side: per user, or per session under Also Visible To in the session settings modal.
  • Sessions that were created but never paired are listed as NOT PAIRED with a Pair action, and remain visible to their owner across restarts. The list is built from live connections plus session directories on disk, not from the credentials-backed listing alone.
  • Ownership survives a restart in data/session-owners.json rather than in session metadata, because a session that was created but never paired has no credentials directory yet.
  • Admins can add users, change roles, approve pending accounts, and delete a user while optionally revoking every session they own (logout + credentials).

Registration & Approval Behavior

  • DASHBOARD_REGISTRATION_ENABLED=false: registration form is disabled for additional users.
  • DASHBOARD_REGISTRATION_REQUIRE_APPROVAL=true: newly registered users remain pending until approved by admin.
  • The first bootstrap admin (when user file is empty) is created immediately.

Features

  • Sessions: Add WhatsApp accounts (QR/Pairing Code), Delete accounts safely (auto-cleans media/logs).
  • Messaging: Test sending texts, images, and bulk broadcasts interactively.
  • Webhooks: Configure webhook URLs, rotate secrets, and watch the delivery log and dead-letter queue per session.
  • AI & Routing: Per-number auto-response — static auto-reply policy (both/window/fallback) and its message, AI enable switch plus window/always scheduling, OpenAI-compatible model with encrypted credentials, AI capabilities (send tool, web search, vision, OTP filter), group reply policy, persona scope, system instruction, knowledge endpoints (tool-calling RAG), and live routing metrics. Cards that need the AI are hidden while it is switched off.
  • Events: Real-time SSE (Server-Sent Events) live log for WhatsApp events.
  • Admin & users: Add users, approve registrations, change roles, scope sessions, and revoke sessions/credentials when deleting a user.
  • Security: HttpOnly session cookie, strict CSP with violation reporting (/dashboard/csp-report), HSTS behind TLS, same-origin dashboard APIs.

🔐 API Authentication

The raw REST API /chats, /groups, etc., supports two authentication methods:

1. Simple Token (Dev / Single-User)

Set AUTH_GLOBAL_TOKEN in .env:

AUTH_GLOBAL_TOKEN=your-secret-token-here

Supported headers for simple token mode:

  • Authorization: Bearer <token>
  • x-api-key: <token>
  • x-access-token: <token>
  • token: <token>

Use in requests:

curl -H "Authorization: Bearer your-secret-token-here" http://localhost:3000/sessions

2. Redis API Keys (Production / Multi-User)

Requires REDIS_ENABLED=true. Manage keys using the CLI:

# Bun Runtime
bun run manage-api-keys create user

# Node.js Runtime
npm run manage-api-keys:node create admin

Use header: x-api-key: <your-api-key>

# Create user API key
bun run manage-api-keys create user

# Create admin API key
bun run manage-api-keys create admin

# List all keys
bun run manage-api-keys list

# Delete a key
bun run manage-api-keys delete <api-key>

Use in requests:

curl -H "x-api-key: <your-api-key>" http://localhost:3000/sessions

Note: In development mode (NODE_ENV=development), API authentication is skipped entirely.

Dashboard Authentication (UI)

  • Dashboard endpoints (/dashboard/api/*) use JWT-based auth.
  • SSE/Event stream endpoints use short-lived stream-scoped tokens.
  • Stream token endpoint: GET /dashboard/api/auth/stream-token

🔑 Managed API keys & audit log

Open Dashboard → REST API (admin only) to create and revoke keys without the CLI. Each key stores:

Field Meaning
Label Human name (chatbot-widget)
Session The single session this key may send from
Last used Updated on every authenticated call

There is no role selector: REST keys are send-only (user). Admin-only operations stay behind the dashboard session. One key belongs to one session, so create a separate key per number you expose; the page only appears while at least one session is connected.

The token is shown once at creation and stored only as a SHA-256 hash. A leaked dump does not expose usable keys. Storage is flexible: every record is written to data/api-keys.json, and mirrored into Redis when it is available (reads merge both, deletes remove both) — Redis is not required. Legacy plaintext keys are migrated automatically on first use. Scope is enforced on /api/v1/messages: a key bound to ROG8 gets 403 when from resolves to another session.

Every call is written to the audit log (Dashboard → REST API → Request log): time, key id/label, session, masked receiver, type, status, latency and IP. The message body is not stored unless AUDIT_LOG_BODY=true, and tokens never appear in the log. Entries also append to logs/api-audit-YYYY-MM-DD.jsonl and are pruned after AUDIT_LOG_RETENTION_DAYS.

# Create a key bound to one session (admin session cookie required)
curl -X POST https://your-domain.com/dashboard/api/api-keys \
  -H "Content-Type: application/json" \
  -b "wa_dashboard_session=<cookie>" \
  -d '{"label":"chatbot-widget","session":"ROG8"}'

📱 API Usage Examples

Create Session (Pairing Code)

POST /sessions/my-session
Content-Type: application/json

{
  "usePairingCode": true,
  "phoneNumber": "+6281234567890",
  "webhookUrl": "http://your-server.com/webhook"
}

Send an Image

POST /chats/my-session/send
Content-Type: application/json

{
  "receiver": "6281234567890",
  "message": {
    "image": { "url": "https://example.com/image.jpg" },
    "caption": "Check this out!"
  }
}

Unified send (third-party friendly)

Base URL depends on where the API runs:

Environment Base URL
Local / development http://localhost:3000
Production (VPS) https://your-domain.com (or whatever your reverse proxy exposes)

So the canonical endpoint is <BASE_URL>/api/v1/messages; the older <BASE_URL>/messages stays available as an alias. One endpoint for widgets, chatbots and LLM tools. Authenticate with the same API key as the rest of the REST API (Authorization: Bearer <API_KEY> or x-api-key). from accepts a session id or the WhatsApp number bound to it.

POST https://your-domain.com/api/v1/messages
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "from": "ROG8",
  "receiver": "628123456789",
  "type": "text",
  "messages": "Halo, ini pesan dari bot."
}
type Required fields
text (default) messages
image media.url; messages becomes the caption
document media.url, optional media.filename, media.mimetype
location location.latitude, location.longitude, optional name/address
# Image with caption
POST https://your-domain.com/api/v1/messages
{
  "from": "62812xxxxxxx",
  "receiver": "62813xxxxxxx",
  "type": "image",
  "messages": "Bukti transfer",
  "media": { "url": "https://example.com/bukti.jpg" }
}

# Document
{
  "from": "ROG8",
  "receiver": "62813xxxxxxx",
  "type": "document",
  "media": {
    "url": "https://example.com/invoice.pdf",
    "filename": "invoice.pdf",
    "mimetype": "application/pdf"
  }
}

# Location
{
  "from": "ROG8",
  "receiver": "62813xxxxxxx",
  "type": "location",
  "location": {
    "latitude": -6.2,
    "longitude": 106.8,
    "name": "Kantor",
    "address": "Jl. Contoh 1"
  }
}

Copy-paste integration snippet

Four separate blocks, ready for a chatbot tool definition (the dashboard shows the same text in REST API → Integration snippet).

Method & URL

POST https://your-domain.com/api/v1/messages

Headers

Authorization: Bearer <API_KEY>
Content-Type: application/json

JSON Schema (tool parameters)

{
  "description": "Send a WhatsApp message from a connected session. Use text for plain messages, image/document with media.url, and location with latitude/longitude.",
  "type": "object",
  "required": ["from", "receiver"],
  "properties": {
    "from": { "type": "string", "description": "Session id (e.g. ROG8) or the phone number bound to it." },
    "receiver": { "type": "string", "description": "Recipient in international digits (e.g. 628123456789), a JID, or a group id ending with @g.us." },
    "type": { "type": "string", "enum": ["text", "image", "document", "location"], "description": "Message kind. Defaults to text." },
    "messages": { "type": "string", "description": "Text body, or the caption for image and document." },
    "media": {
      "type": "object",
      "required": ["url"],
      "description": "Required for image and document.",
      "properties": {
        "url": { "type": "string", "description": "Public file URL." },
        "filename": { "type": "string", "description": "Displayed file name." },
        "mimetype": { "type": "string", "description": "MIME type, e.g. application/pdf." }
      }
    },
    "location": {
      "type": "object",
      "required": ["latitude", "longitude"],
      "description": "Required for location.",
      "properties": {
        "latitude": { "type": "number", "description": "Decimal degrees." },
        "longitude": { "type": "number", "description": "Decimal degrees." },
        "name": { "type": "string", "description": "Place name." },
        "address": { "type": "string", "description": "Street address." }
      }
    },
    "isGroup": { "type": "boolean", "description": "Force group semantics when receiver is not an @g.us JID." }
  }
}

Example body

{
  "from": "ROG8",
  "receiver": "628123456789",
  "type": "text",
  "messages": "Halo, ini pesan dari bot."
}

Full tool definition (download)

The dashboard can also emit one combined object (Download .json, saved as whatsapp-tool-<session>.json) that a tool-import UI can consume directly:

{
  "name": "send_whatsapp_message",
  "description": "Send a WhatsApp message from a connected session.",
  "method": "POST",
  "url": "https://your-domain.com/api/v1/messages",
  "headers": {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  },
  "parameters": { "...": "the schema block above" },
  "example": {
    "from": "ROG8",
    "receiver": "628123456789",
    "type": "text",
    "messages": "Halo, ini pesan dari bot."
  }
}

For validators that want the stricter contract, the full draft-07 schema (oneOf rules per type) is served at GET /api/v1/messages/schema.

Success response:

{
  "success": true,
  "data": {
    "messageId": "3EB0...",
    "to": "628123456789@s.whatsapp.net",
    "type": "text",
    "timestamp": 1761000000
  },
  "message": "Message sent successfully"
}

Every failure is structured so a calling LLM can correct itself. Nothing returns a bare status code:

{
  "success": false,
  "code": "SESSION_NOT_CONNECTED",
  "message": "Session \"ROG8\" is not connected",
  "field": "from",
  "hint": "Reconnect the session from Dashboard → Sessions (scan the QR code), then retry this request.",
  "details": { "session": "ROG8", "connected": false },
  "retryable": true,
  "requestId": "mvxu1abc-9f2k"
}
HTTP code Meaning What to do
400 INVALID_REQUEST Body failed validation Read field and details.issues (all issues, not just the first)
400 RECEIVER_NOT_ON_WHATSAPP Number not registered on WhatsApp Use international digits (628123456789) and confirm WhatsApp exists
401 UNAUTHORIZED Missing or revoked API key Send Authorization: Bearer <API_KEY>; create a key in Dashboard → REST API
403 KEY_NOT_SCOPED Key cannot use that from Use an allowed from; see details.allowed
403 GROUP_DISABLED Group sending is off Send 1:1, or enable ALLOW_GROUP_SEND
403 GROUP_NOT_ALLOWED Group not in the allowlist Add the JID to ALLOWED_GROUP_JIDS
404 SESSION_NOT_FOUND from did not resolve Use a session id from details.available (or GET /sessions)
409 SESSION_NOT_CONNECTED Session exists but is offline Reconnect via Dashboard → Sessions, then retry
500 SEND_FAILED Unexpected send failure Retry once; if it persists, report the requestId

retryable is true for 409 and 5xx only: after reconnecting a session a retry is sensible, while a bad receiver or missing field will fail again until the request changes.

Groups are opt-in. Send to ...@g.us only when ALLOW_GROUP_SEND=true; optionally restrict with ALLOWED_GROUP_JIDS. Group blasts are the highest ban risk for an unofficial client — keep them allowlisted and low-volume.

Send Bulk Messages (Anti-Spam)

POST /chats/my-session/send-bulk
Content-Type: application/json

{
  "messages": [
    { "receiver": "6281234567890", "message": { "text": "Hello #1" } },
    { "receiver": "6281234567891", "message": { "text": "Hello #2" } }
  ]
}

Response:

{
 "success": true,
 "message": "Broadcast job created",
 "data": { "jobId": "bc_1709271000_abc123", "total": 3, "status": "pending" }
}

Track progress:

GET /chats/my-session/broadcast/bc_1709271000_abc123

Standard response envelope (code & requestId)

Every public API response (success or error) is a stable JSON envelope:

  • Success — { success, message, data?, requestId }
  • Error — { success: false, message, code, requestId }

code is a machine-readable error code derived from the HTTP status so integrators can branch programmatically instead of parsing free-text messages:

HTTP code
400 VALIDATION_ERROR
401 UNAUTHORIZED
403 FORBIDDEN
404 NOT_FOUND
409 CONFLICT
422 UNPROCESSABLE_ENTITY
429 RATE_LIMITED
500 INTERNAL_ERROR
503 SERVICE_UNAVAILABLE
… HTTP_<status> fallback

requestId lets you trace a request end-to-end across logs and reverse proxies. Send your own id in the x-request-id header to have it echoed back, or omit it and one is generated for you.

Example:

curl -i -X POST /chats/missing-session/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-request-id: req_12345" \
  -H "Content-Type: application/json" \
  -d '{"receiver":"6281234567890","message":{"text":"hi"}}'
HTTP/1.1 404 Not Found
{ "success": false, "message": "Session 'missing-session' not found", "code": "NOT_FOUND", "requestId": "req_12345" }

Create a Group

POST /groups/my-session/create
Content-Type: application/json

{
  "groupName": "API Test Group",
  "participants": ["6281234567890", "6281234567891"]
}

Webhook Events

Set WEBHOOK_URL in .env or per-session. Events are sent as POST:

{
  "sessionId": "my-session",
  "event": "messages.upsert",
  "data": { "messages": [...], "type": "notify" }
}

Webhook requests are authenticated with the configured secret sent in two headers so both legacy and standard receivers work (this is deliberate, kept in a single header builder):

  • x-webhook-secret: <secret> — legacy receivers built for this API
  • Authorization: Bearer <secret> — standard receivers / API gateways

When signature mode is enabled, webhook requests also include:

  • x-webhook-timestamp
  • x-webhook-signature: sha256=<hmac>

(The signature uses the same secret — a shared-secret HMAC over "<timestamp>.<body>", not a separate signing key — so only verify it if you control the receiver and trust the shared secret.)

Controlled by:

  • WEBHOOK_SIGNATURE_MODE=off|optional|required (default optional; required once the receiver verifies signatures)
  • WEBHOOK_INCLUDE_TOKEN=true|false — legacy static-token headers. Set false after the receiver verifies X-Webhook-Signature; the secret then stays off the wire. Requests also carry a stable X-Webhook-Id for deduplication.
  • WEBHOOK_ALLOW_GLOBAL_TOKEN_FALLBACK=true|false

Webhook secrets are never returned by list endpoints; the dashboard shows only hasWebhookSecret and the last four characters. Submitting an empty secret keeps the stored one (use clearWebhookSecret: true to remove it).

Secrets are encrypted at rest in session metadata when CONFIG_ENC_KEY is set (otherwise they carry a plain: prefix for backward compatibility). POST /dashboard/api/sessions/:sessionId/webhook/rotate generates a 32-byte secret, stores the encrypted value and returns the plaintext once. The previous secret remains primary for WEBHOOK_SECRET_GRACE_MS (default 24 h), so existing receivers keep working while they are updated; the new secret is sent in x-webhook-secret-new and x-webhook-signature-new. After the grace window the new secret becomes primary. Pass graceMs: 0 (API) to invalidate the old secret immediately. Rotation is manual: there is no recurring 24-hour expiry and nothing rotates on its own. Dead-letter JSONL persistence omits the secret; replay resolves the active one from the session.

Token auth is not replay protection. TLS protects the wire only: a bearer token (Authorization, x-webhook-secret) captured in receiver, reverse-proxy, APM or error-report logs remains usable even without intercepting TLS. Redact those headers everywhere, never put secrets in URLs, and rotate if a log dump may have been exposed. x-webhook-signature + x-webhook-timestamp + x-webhook-id only add replay resistance when the receiver enforces freshness (for example ±5 minutes) and deduplicates delivery IDs; the headers themselves do not reject an old request. Prefer HMAC and stop sending the token when the receiver supports it, but token auth with strict log hygiene is an accepted tradeoff for simpler integrations.

Fallback order for webhook auth/signing secret:

  1. Per-session webhook secret
  2. AUTH_GLOBAL_TOKEN (only when fallback is enabled)

Delivery hardening (retries, rate limit, circuit breaker, dead-letter)

Outbound delivery is hardened per receiver URL (see .env.example):

  • Smart retry — non-retryable 4xx give up immediately; 429/503 honor Retry-After (capped); 5xx/408/425/network retry with backoff (WEBHOOK_RETRY_MAX, WEBHOOK_RETRY_INTERVAL, WEBHOOK_BACKOFF_FACTOR, WEBHOOK_RETRYABLE_STATUSES).
  • Per-URL rate limit — WEBHOOK_RATE_PER_MIN (0 = off) token-bucket per receiver; extra events wait (bounded, fail-open) instead of being dropped.
  • Circuit breaker — WEBHOOK_CIRCUIT_FAILURES (default 5) consecutive genuine failures (retryable 5xx / network errors — not 4xx or healthy 429s) pause delivery to that endpoint for WEBHOOK_CIRCUIT_RESET_MS (default 30s). Paused deliveries are logged as skipped and never silently dropped.
  • Gzip — bodies larger than WEBHOOK_GZIP_THRESHOLD bytes (default 16 KB; 0 = off) are sent with Content-Encoding: gzip. The signature is computed over the uncompressed JSON, so receivers decompress first, then verify.
  • Dead-letter — WEBHOOK_DEAD_LETTER_ENABLED keeps deliveries that exhausted retries (in-memory, optionally persisted as JSONL to WEBHOOK_DEAD_LETTER_DIR) for manual replay via the dashboard.
  • SSRF guard — redirects are never followed, and when WEBHOOK_BLOCK_INTERNAL=true the hostname is resolved and every answer is checked against private/loopback/link-local ranges (textual checks alone miss DNS rebinding). WEBHOOK_BLOCK_INTERNAL=true rejects webhook URLs pointing at localhost / private networks (off by default so local testing works).

Available events:

  • connection.update — Connection state changes (QR, open, close)
  • messages.upsert — New messages received
  • messages.update — Message status updates (sent, delivered, read)
  • messages.delete — Messages deleted
  • messages.reaction — Reactions added/removed
  • chats.upsert, chats.update, chats.delete
  • contacts.upsert, contacts.update
  • groups.upsert, groups.update
  • group-participants.update
  • presence.update
  • blocklist.set, blocklist.update

📂 Project Structure

baileys-wa-api/
├── data/                           # Dashboard users and internal dashboard data (JSON)
├── media/                          # Downloaded media files
├── sessions/                       # Auth/session state per WhatsApp session
├── scripts/
│   └── manage-api-keys.ts          # API key management CLI
├── src/
│   ├── index.ts                    # Runtime entry point (Bun/Node)
│   ├── app.ts                      # Hono app bootstrap + routes + docs
│   ├── config.ts                   # Centralized environment config
│   ├── baileys/
│   │   ├── connection.ts           # BaileysConnection class
│   │   ├── connectionManager.ts    # Multi-session manager
│   │   ├── types.ts                # Type definitions
│   │   ├── authState/
│   │   │   ├── index.ts            # Auth state factory + session metadata
│   │   │   ├── file.ts             # File-based auth
│   │   │   ├── redis.ts            # Redis-based auth
│   │   │   ├── backendRecord.ts    # Sticky backend marker
│   │   │   └── metadataSecrets.ts  # Encrypted metadata secrets
│   │   ├── store/
│   │   │   └── memoryStore.ts      # In-memory store + LID/PN room merge
│   │   └── helpers/
│   │       ├── downloadMedia.ts    # Media download utilities
│   │       ├── shouldIgnoreJid.ts  # JID filtering
│   │       └── visionMedia.ts      # Bounded image download for vision
│   ├── dashboard/
│   │   ├── api.ts                  # Dashboard backend APIs (stats/events/webhooks)
│   │   ├── auth.ts                 # Dashboard auth + users/roles/approval
│   │   ├── eventBus.ts             # In-process event bus for SSE
│   │   └── loader.ts               # Dashboard route/static loader
│   ├── dashboard-ui/
│   │   ├── index.html              # Dashboard SPA shell
│   │   ├── css/
│   │   │   └── styles.css
│   │   └── js/
│   │       ├── api.js
│   │       ├── app.js
│   │       ├── auth.js
│   │       ├── theme.js
│   │       ├── components/
│   │       │   ├── modal.js
│   │       │   └── toast.js
│   │       └── pages/              # overview/sessions/chatRooms/ai/api/messaging/
│   │                               # webhooks/events/settings
│   ├── lib/
│   │   ├── logger.ts               # Pino logger
│   │   ├── redis.ts                # Redis client helpers
│   │   ├── response.ts             # API response helpers
│   │   └── runtime.ts              # Bun/Node runtime abstraction
│   ├── middleware/
│   │   ├── auth.ts                 # API authentication
│   │   ├── rateLimit.ts            # API rate limiting
│   │   └── sessionValidator.ts     # Session existence check
│   ├── routes/
│   │   ├── session.ts              # Session CRUD
│   │   ├── chat.ts                 # Chat operations
│   │   ├── group.ts                # Group management
│   │   ├── profile.ts              # Profile management
│   │   ├── media.ts                # Media handling
│   │   ├── story.ts                # Story broadcasting
│   │   └── status.ts               # Server health
│   ├── schemas/
│   │   ├── chat.ts                 # Chat schemas
│   │   ├── group.ts                # Group schemas
│   │   └── session.ts              # Session schemas
│   ├── services/                   # Response + delivery layer
│   │   ├── aiAgent.ts              # OpenAI-compatible driver, tool loop
│   │   ├── aiHistory.ts            # Bounded conversation history
│   │   ├── aiMetrics.ts            # Per-session routing metrics
│   │   ├── aiSendTool.ts           # Optional send_whatsapp_message tool
│   │   ├── webSearch.ts            # Optional web_search (SearXNG)
│   │   ├── persona.ts              # Response scope + security block
│   │   ├── groupReply.ts           # Group scope and static gating
│   │   ├── autoReply.ts            # Static reply policy helpers
│   │   ├── conversationRouter.ts   # Debounce, handoff, responder chain
│   │   ├── routing.ts              # Time window evaluation
│   │   ├── otpFilter.ts            # OTP/verification deny-list
│   │   ├── promptGuard.ts          # Injection tripwire + scrubbing
│   │   ├── ragTools.ts             # Knowledge-endpoint tool calling
│   │   ├── inboundMedia.ts         # Media descriptors for prompts
│   │   ├── linkPreview.ts          # Bounded, SSRF-checked link context
│   │   ├── messageSender.ts        # Unified send path
│   │   ├── broadcastQueue.ts       # Broadcast queue with delays
│   │   ├── mediaCleanup.ts         # Media file cleanup
│   │   ├── apiKeys.ts              # Scoped API keys (file + Redis)
│   │   ├── apiAuditLog.ts          # Audit log (JSONL, pruned)
│   │   ├── loginGuard.ts           # Dashboard brute-force lockout
│   │   ├── webhookQueue.ts         # Retry, backoff, signature
│   │   ├── webhookLog.ts           # Webhook delivery log storage
│   │   └── webhookDeadLetter.ts    # Failed delivery retention
│   └── utils/
│       ├── asyncSleep.ts           # Async sleep utilities
│       ├── phone.ts                # Phone/JID formatting
│       └── validation.ts           # Validation utilities
├── .env.example
├── biome.jsonc
├── docker-compose.yml
├── docker-compose.node.yml
├── Dockerfile
├── Dockerfile.node
├── package.json
├── tsconfig.json
└── README.md

⚙️ Configuration Reference (.env)

Variable Default Description
NODE_ENV development Environment (development / production)
HOST 0.0.0.0 Server host
PORT 3000 Server port
LOG_LEVEL info Log level (debug, info, warn, error)
AUTH_GLOBAL_TOKEN — Simple auth token
REDIS_ENABLED false Enable Redis integration
REDIS_URL redis://localhost:6379 Redis connection URL
REDIS_PASSWORD — Redis password
BAILEYS_LOG_LEVEL warn Baileys internal log level
MAX_RETRIES 5 Max reconnection attempts
RECONNECT_INTERVAL 5000 Reconnection delay (ms)
MAX_SESSIONS 50 Maximum concurrent WhatsApp sessions
WEBHOOK_URL — Default webhook URL
WEBHOOK_CONCURRENCY 20 Max concurrent outbound webhook requests globally
WEBHOOK_SIGNATURE_MODE optional Webhook signature mode (off, optional, required)
WEBHOOK_INCLUDE_TOKEN true Legacy static-token headers; false after receivers verify HMAC
WEBHOOK_SECRET_GRACE_MS 86400000 After rotation, keep the old secret primary this long (0 = immediate)
WEBHOOK_ALLOW_GLOBAL_TOKEN_FALLBACK true Allow fallback to AUTH_GLOBAL_TOKEN for webhook secret/signature
WEBHOOK_ALLOWED_EVENTS ALL Comma-separated event filter
WEBHOOK_RETRY_MAX 3 Webhook delivery retry count
WEBHOOK_RETRY_INTERVAL 5000 Initial webhook retry delay (ms)
WEBHOOK_BACKOFF_FACTOR 3 Exponential backoff multiplier
BROADCAST_MIN_DELAY_MS 1500 Min delay between bulk messages
BROADCAST_MAX_RECIPIENTS_NO_REDIS 50 Per-broadcast ceiling when Redis is unavailable (memory queue); with Redis the 1000-message limit applies
BROADCAST_MAX_DELAY_MS 3000 Max delay between bulk messages
BROADCAST_BATCH_SIZE 10 Messages per batch before pause
BROADCAST_BATCH_PAUSE_MS 5000 Pause between batches
BROADCAST_TYPING_SIMULATION false Show a per-recipient "composing…" bubble during broadcasts (default: false — safer/less bot-like; adds typing delay per recipient)
BROADCAST_DELAY_DISTRIBUTION uniform Delay pattern between messages: uniform (random min–max, legacy) or human (short gaps + occasional longer pauses)
BROADCAST_BATCH_CHECK_WA false Check recipient WA-registration in batches (fewer usync queries) instead of 1-by-1
BROADCAST_CHECK_WA_BATCH_SIZE 50 Batch size when BROADCAST_BATCH_CHECK_WA=true
MEDIA_INCLUDE_BASE64 false Include media in webhooks
MEDIA_CLEANUP_ENABLED true Auto-delete old media files
MEDIA_CLEANUP_INTERVAL_MS 3600000 Media cleanup interval (ms)
MEDIA_MAX_AGE_HOURS 24 Max age of media files
CORS_ORIGIN * CORS allowed origins
TRUST_PROXY false Trust x-forwarded-for/x-real-ip/cf-connecting-ip for client IP. Enable ONLY behind a trusted reverse proxy/LB; when false the socket address is used so spoofed headers cannot bypass rate limits
DASHBOARD_ENABLED true Enable internal UI dashboard
DASHBOARD_REGISTRATION_ENABLED false Allow account creation
DASHBOARD_REGISTRATION_REQUIRE_APPROVAL true Require admin approval before new user can login
DASHBOARD_PASSWORD_MIN_LENGTH 6 Minimum password length for dashboard users
DASHBOARD_JWT_SECRET change-this-to-a-random-secret JWT secret for dashboard auth. In production: if unset/still default, dashboard auth is disabled (fail-closed, 503) — generate with openssl rand -base64 48
SIMULATE_TYPING_BEFORE_SEND true Auto-send "composing" presence before each message (default: true)
SIMULATE_TYPING_DELAY_MIN_MS 1500 Typing delay range in ms (random between min-max)
SIMULATE_TYPING_DELAY_MAX_MS 3000 Typing delay range in ms (random between min-max)
AUTO_READ_MESSAGES false ⚠ RISK: auto-mark incoming as read. Instant 0ms reads on 100% of chats is a bot signature & may trigger bans. Leave false unless required; if enabled also set AUTO_READ_DELAY_ENABLED=true for a natural delay
AUTO_READ_DELAY_ENABLED true Wait a natural "opened chat" delay before marking read (only when AUTO_READ_MESSAGES=true); false = read instantly (legacy)
AUTO_READ_DELAY_MIN_MS 1500 Min random "opened chat" delay before read receipt (ms)
AUTO_READ_DELAY_MAX_MS 4000 Max random "opened chat" delay before read receipt (ms)
AUTO_MARK_ONLINE true Auto-set presence to "available" when sending messages (default: true)
REJECT_CALLS false Auto-reject incoming calls across all sessions
HUMANIZE_READ_BEFORE_REPLY false Before auto-replying to a 1-on-1 chat, wait a natural "reading" gap then mark as read (bot-like instant replies without prior read = risky)
HUMANIZE_READ_DELAY_MIN_MS 800 Min random "reading" gap before the read receipt (ms)
HUMANIZE_READ_DELAY_MAX_MS 2500 Max random "reading" gap before the read receipt (ms)
HUMANIZE_THINK_MIN_MS 800 Min random "thinking" gap before typing starts (ms)
HUMANIZE_THINK_MAX_MS 2000 Max random "thinking" gap before typing starts (ms)
HUMANIZE_TYPING_CPS_MIN / _MAX_MS 3 / 5 Proportional typing speed in characters per second, random per message
HUMANIZE_TYPING_CAP_MIN_MS / _MAX_MS 5000 / 15000 Random ceiling for proportional typing; a fixed cap would end every long reply on the same duration. The older HUMANIZE_TYPING_MAX_MS still overrides _CAP_MAX_MS while set — remove it when migrating
HUMANIZE_PRESENCE_START_MIN_MS / _MAX_MS 300 / 900 Random gap between "available" and "composing" (ms)
HUMANIZE_PRESENCE_OFFLINE_MIN_MS / _MAX_MS 30000 / 90000 Random delay before clearing "online" for a chat (ms)
HUMANIZE_PRESENCE_IDLE_MIN_MS / _MAX_MS 300000 / 900000 Quiet period after which the account goes offline entirely (ms). Set both to 0 to disable
HUMANIZE_TYPING_PROPORTIONAL true Typing ("composing") duration scales with reply length and a random speed. Set false for the legacy fixed random delay (SIMULATE_TYPING_DELAY_*)
HUMANIZE_PRESENCE_DEDUPE_MS 0 Min gap between repeated composing/paused to the same chat (ms); 0 = always send (legacy)
HUMANIZE_GLOBAL_PACING_MIN_MS 0 Min random gap between ANY outbound actions within a session (ms); 0 = off (legacy)
HUMANIZE_GLOBAL_PACING_MAX_MS 0 Max random gap between ANY outbound actions within a session (ms); 0 = off (legacy)
HUMANIZE_DELAY_DISTRIBUTION uniform Delay pattern for humanize read/think gaps: uniform (random min–max, legacy) or human (short gaps + occasional longer pauses)

Login, limits and send guards

Variable Default Description
AUTH_MAX_FAILURES 10 Failed dashboard logins before the account/IP is locked
AUTH_FAILURE_WINDOW_MS 900000 Window in which failures are counted
AUTH_LOCK_MS 900000 Lock duration after the threshold
RATE_LIMIT_API_KEY 60 Requests per minute per API key
SEND_TIMEOUT_MS 30000 Timeout for one outbound send
MAX_CONCURRENT_SENDS 5 Concurrent sends per process
MAX_MESSAGES_PER_CHAT 50 Messages kept per chat in memory/snapshot
MAX_SESSIONS 50 Maximum concurrent WhatsApp sessions
MAX_SESSIONS_PER_USER 3 Session quota for non-admin users (0 = unlimited)
MAX_SESSIONS_PER_MANAGER 5 Session quota for managers (0 = unlimited)

Auth-state backend

Variable Default Description
AUTH_STATE_BACKEND auto auto / file / redis; the first successful start records the backend in data/auth-state-backend.json and later starts stick to it
AUTH_STATE_SWITCH_CONFIRM — One-shot confirmation required to move an existing installation to a different backend. Sessions are not migrated; re-link by QR

CSP and dashboard assets

Variable Default Description
CSP_REPORT_ONLY false true = report only; violations are logged and posted to /dashboard/csp-report but not blocked
CSP_CDN true Allow the pinned CDN origins; false = same-origin only
DOCS_ASSETS cdn Swagger UI assets: cdn (pinned + SRI) or local (offline)
CSP_EXTRA_SCRIPT_SRC — Extra origin per directive (_STYLE_, _IMG_, _FONT_, _CONNECT_)

Built-in web search (SearXNG)

Variable Default Description
SEARXNG_URL — Base URL, e.g. http://127.0.0.1:8080. Empty disables web_search entirely
SEARXNG_TIMEOUT_MS 8000 Per-query timeout
SEARXNG_MAX_RESULTS 5 Results kept per query (1–10)
SEARXNG_LANGUAGE — SearXNG language code; empty uses the instance default
SEARXNG_SAFESEARCH 1 0 none, 1 moderate, 2 strict

Outbound guards and group sending

Variable Default Description
WEBHOOK_BLOCK_INTERNAL false Refuse webhook targets that resolve to private/loopback addresses
MEDIA_BLOCK_INTERNAL true Refuse media downloads from private/loopback addresses
AI_TOOL_BLOCK_INTERNAL false Refuse configured knowledge-endpoint URLs pointing at private hosts
WEBHOOK_RETRYABLE_STATUSES 408,425,429,500,502,503,504 Statuses that trigger a retry
IGNORE_GROUP_MESSAGES false Global switch that drops every group message before any policy runs
ALLOW_GROUP_SEND false Allow outbound group sends through the API/tools
ALLOWED_GROUP_JIDS — Comma-separated group allowlist when group sending is on

Audit log

Variable Default Description
AUDIT_LOG_ENABLED true Write the REST API audit log
AUDIT_LOG_BODY false Store request bodies (off keeps payloads out of the log)
AUDIT_LOG_RETENTION_DAYS 7 Entries older than this are pruned
AUDIT_LOG_MAX_ENTRIES 5000 Hard cap on retained entries

.env.example is the authoritative, complete list. The tables above cover the settings that change behaviour most often; AI and routing defaults are listed in the AI section.

Data migrations

Settings → Data Migrations (admin only) exports and restores a zip of the file-based state: session auth, session snapshots, data/ai-memory/, data/api-keys.json, and optionally media/.

  • Not included, on purpose: .env (this machine's keys) and data/dashboard-users.json (password hashes, admin accounts). The manifest states both, and a restore creates dashboard users from scratch.
  • Secrets are decrypted on export and re-encrypted on import, because they are bound to CONFIG_ENC_KEY. A value that cannot be decrypted on the source is listed in the manifest as unreadable instead of disappearing silently.
  • The archive therefore holds plaintext secrets (provider keys, webhook secrets). Treat it like an .env file and delete it after restoring.
  • Collisions: skip (default) leaves existing sessions alone; replace overwrites them and is refused while that session is connected. A connected session is never overwritten.
  • No restart needed: imported sessions are loaded after the restore, and replaced ones are recreated from the restored auth state.
  • One credential set belongs to one running instance. Copying a session to a second machine and running both means two processes sharing one linked-device identity; pair the second number separately instead.
  • Archive name: <YYYYMMDD-HHMMSS>-<host>-Backup.zip, so backups sort by time.

CORS & reverse-proxy notes

  • CORS_ORIGIN=* (default) is safe for a token-based public API: CORS only controls which browser origins may read responses, it is not authentication — requests still need AUTH_GLOBAL_TOKEN / API keys. Restrict it (comma-separated origins) when a browser dashboard on another domain must talk to this API, or when you never want other sites to read responses.
  • TRUST_PROXY=false (default) uses the socket address for rate limiting — spoofed x-forwarded-for headers cannot bypass limits. Set TRUST_PROXY=true only behind a trusted reverse proxy / load balancer (Nginx, Caddy, Cloudflare, AWS ALB) so the real client IP is used.

🧪 Useful Scripts

Use these commands for validation and maintenance:

# Type-check only
npm run build-check

# Lint with error-level gate
npm run lint

# Full lint diagnostics
npm run lint:all

# Auto-format/fix source files
npm run format

API key helper:

# Bun runtime
bun run manage-api-keys create admin

# Node runtime
npm run manage-api-keys:node create admin

📝 License

License: MIT

This project is licensed under the MIT License - see the LICENSE file for details.

About

WhatsApp REST API built with Hono + TypeScript and features Dual-Runtime Support (runs natively on Bun or Node.js). Includes a built-in AI Routing for auto reply & Visual Dashboard for easy management.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages