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.
| 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 |
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) andinbound(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.
- 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.
# Clone the repository
git clone <repository-url>
cd baileys-wa-api
# Configure Environment
cp .env.example .env
# Edit .env and configure DASHBOARD_JWT_SECRETbun install
# Development (Auto-reload)
bun run dev
# Production Build
bun run startnpm install
# Development (via tsx watch)
npm run dev:node
# Production Build
npm run start:nodeThe 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
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.
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) orany. The originating chat is always allowed;receiveris optional and defaults to it. - Rate limit —
maxPerHoursliding 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.
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
jsontosearch.formatsin itssettings.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 byAI_TOOL_MAX_RESPONSE_CHARS. - Snippets are labelled untrusted data, so instructions inside them are not treated as operator policy.
- 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_urlparts, 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.
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 Onlymatches 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) —
conservative6,balanced5,aggressive4. 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.
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.
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:
ai.enabledis on for that number (dashboard).- The current time is inside
AI_WINDOW_START–AI_WINDOW_END, evaluated inROUTING_TZ(cross-midnight supported:16:00→08:00). - 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.
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;strictanswers 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.
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.
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.
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.
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_EVERYmessages (50) orAI_MEMORY_SUMMARY_MIN_CHARScharacters (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_MODELselects 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 newestAI_MEMORY_RAW_MAX_MESSAGES(2000) lines that are younger thanAI_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
.jsonfile 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 mode700; 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
adminandmanager; 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.
| 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.
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.
GET /dashboard/api/sessions/:sessionId/ai-config
PATCH /dashboard/api/sessions/:sessionId/ai-configPATCH body (every field optional, merged):
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.
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 byROUTING_BATCH_MAX_WAIT_MSfrom the first message and byROUTING_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.
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.
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.
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/sendstill 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.
Layers, weakest to strongest:
- 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. - Instruction hierarchy — customer text is wrapped in
<pesan_pengguna>…</pesan_pengguna>and the system prompt states that this is data, never instructions. - 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.
- Output scrubbing — credential-shaped strings (API keys, bearer tokens, private keys) are redacted from the reply before it is sent.
- Abuse control — after
AI_GUARD_MAX_STRIKESblocked messages the conversation is muted forAI_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.
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.
GET /dashboard/api/ai/metrics?sessionId=<optional>
POST /dashboard/api/ai/metrics/resetCounters 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.
| 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.
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 | 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.
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.
- 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 withoutcreds.jsonolder than a day. Valid sessions (creds present) are never touched. It runs at startup and daily; run it manually withbun 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.
- 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 escapesessions/, so delete/metadata operations cannot touch other files. - Media URLs are checked before sending (
MEDIA_BLOCK_INTERNAL, default true): a/messagesrequest that points at localhost, a private range or a link-local host returns400 MEDIA_URL_BLOCKEDinstead 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 legacyGET; the auth path no longer runsKEYS/full scans, andlastUsedAtis 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.
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 aBASE_PATHimplementation 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
Secureover 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, restrictivePermissions-Policy.- Cross-origin requests to
/dashboard/*are rejected with 403. - Plain-HTTP dashboard requests are redirected to HTTPS when
TRUST_PROXY=truein 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.
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.
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-tagsThe 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.
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, …)docker compose up -d
docker compose logs -f apiThe 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 apiRedis 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 variantThe 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 downPORT in .env is honored on both sides of the mapping, and the container
health check follows it:
PORT=8080 # → host 8080 → container 8080, healthyTo stop containers: docker compose down
The API includes an intuitive, modular web dashboard to manage everything visually without touching the CLI.
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- Open
http://localhost:3000/dashboard/in your browser. - If
data/dashboard-users.jsonis empty, you will be prompted to create the very first Admin Account. - Create your account with a secure password (hashed via
bcryptjs). - Once created, recommended to set
DASHBOARD_REGISTRATION_ENABLED=falsein.envto prevent public sign-ups.
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
ownerIdmatches 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.jsonrather 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).
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.
- 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.
The raw REST API /chats, /groups, etc., supports two authentication methods:
Set AUTH_GLOBAL_TOKEN in .env:
AUTH_GLOBAL_TOKEN=your-secret-token-hereSupported 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/sessionsRequires 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 adminUse 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/sessionsNote: In
developmentmode (NODE_ENV=development), API authentication is skipped entirely.
- 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
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"}'POST /sessions/my-session
Content-Type: application/json
{
"usePairingCode": true,
"phoneNumber": "+6281234567890",
"webhookUrl": "http://your-server.com/webhook"
}POST /chats/my-session/send
Content-Type: application/json
{
"receiver": "6281234567890",
"message": {
"image": { "url": "https://example.com/image.jpg" },
"caption": "Check this out!"
}
}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"
}
}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."
}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.
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_abc123Every 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" }POST /groups/my-session/create
Content-Type: application/json
{
"groupName": "API Test Group",
"participants": ["6281234567890", "6281234567891"]
}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 APIAuthorization: Bearer <secret>— standard receivers / API gateways
When signature mode is enabled, webhook requests also include:
x-webhook-timestampx-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(defaultoptional;requiredonce the receiver verifies signatures)WEBHOOK_INCLUDE_TOKEN=true|false— legacy static-token headers. Setfalseafter the receiver verifiesX-Webhook-Signature; the secret then stays off the wire. Requests also carry a stableX-Webhook-Idfor 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:
- Per-session webhook secret
AUTH_GLOBAL_TOKEN(only when fallback is enabled)
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 forWEBHOOK_CIRCUIT_RESET_MS(default 30s). Paused deliveries are logged asskippedand never silently dropped. - Gzip — bodies larger than
WEBHOOK_GZIP_THRESHOLDbytes (default 16 KB; 0 = off) are sent withContent-Encoding: gzip. The signature is computed over the uncompressed JSON, so receivers decompress first, then verify. - Dead-letter —
WEBHOOK_DEAD_LETTER_ENABLEDkeeps deliveries that exhausted retries (in-memory, optionally persisted as JSONL toWEBHOOK_DEAD_LETTER_DIR) for manual replay via the dashboard. - SSRF guard — redirects are never followed, and when
WEBHOOK_BLOCK_INTERNAL=truethe hostname is resolved and every answer is checked against private/loopback/link-local ranges (textual checks alone miss DNS rebinding).WEBHOOK_BLOCK_INTERNAL=truerejects 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 receivedmessages.update— Message status updates (sent, delivered, read)messages.delete— Messages deletedmessages.reaction— Reactions added/removedchats.upsert,chats.update,chats.deletecontacts.upsert,contacts.updategroups.upsert,groups.updategroup-participants.updatepresence.updateblocklist.set,blocklist.update
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
| 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) |
| 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) |
| 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 |
| 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_) |
| 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 |
| 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 |
| 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.exampleis 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.
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) anddata/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 asunreadableinstead of disappearing silently. - The archive therefore holds plaintext secrets (provider keys, webhook
secrets). Treat it like an
.envfile and delete it after restoring. - Collisions:
skip(default) leaves existing sessions alone;replaceoverwrites 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_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 needAUTH_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 — spoofedx-forwarded-forheaders cannot bypass limits. SetTRUST_PROXY=trueonly behind a trusted reverse proxy / load balancer (Nginx, Caddy, Cloudflare, AWS ALB) so the real client IP is used.
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 formatAPI key helper:
# Bun runtime
bun run manage-api-keys create admin
# Node runtime
npm run manage-api-keys:node create adminThis project is licensed under the MIT License - see the LICENSE file for details.
{ "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\":{}}" } }