whattsreply/openwiki/quickstart.md

---

type: overview title: Quickstart description: What the wh WhatsApp terminal client with per-chat and global AI autoreply (system prompt in SOUL.md, reply delay, image descriptions) and optional web control panel does, how to build and run it, and where to find each topic in this wiki. tags: [overview, quickstart, rust, whatsapp, tui, ai, web-panel] sources:

• id: openwiki-source-651d1fb6c9 resource: repo://Cargo.toml
• id: openwiki-source-9fec9d1af4 resource: repo://src/app.rs
• id: openwiki-source-043e6252ba resource: repo://src/autoreply.rs
• id: openwiki-source-2a737474d8 resource: repo://src/config.rs
• id: openwiki-source-b55a21a31e resource: repo://src/main.rs generated: { by: "claude-code", at: "2026-10-21T21:49:12.291Z" } verified:
• by: openwiki/0.7.2 at: 2026-10-21T21:49:12.291Z ---

Quickstart

wh (Cargo.toml:1-5) is a Rust terminal client for WhatsApp. It links as a companion device by QR code, shows chats and contacts in a ratatui interface, stores messages locally in SQLite and can answer incoming messages automatically with an OpenAI-compatible model — chat by chat or for all chats at once — in private chats and in groups (broadcasts, status and newsletters excluded). An optional web control panel lets a browser toggle the autoreplies and stop the bot.

Build and run

cargo build --release
cargo run --release
cargo test

The crate uses edition 2024. whatsapp-rust is built with default-features = false because its default simd feature needs nightly (Cargo.toml:8-10). The release profile strips symbols and uses LTO with a single codegen unit (Cargo.toml:27-33). [lints.rust] linker_messages = "allow" (Cargo.toml:35-37) silences the informational MSVC linker line printed because the binary exports symbols.

wh --version (or -V) prints wh <version> (<git commit>) and exits; the same version is shown at the bottom right of the main screen (src/main.rs:24-41, build.rs).

On first start the app shows a QR code: scan it from WhatsApp → Linked devices. The session is kept in session.db, so later starts connect directly. Main keys: Tab switches list/input, Enter opens a chat or sends, typing in the list filters it, PgUp/PgDn/Home/End move through the list, F2 chats/contacts, F3 toggles autoreply for the open chat, F4 toggles the global autoreply ("AI tutte"), Canc twice deletes the selected chat locally, F10 quits (key bindings).

Configuration in short

Settings live in config.toml inside the data directory <platform config dir>/wh (on Windows %APPDATA%\wh, on Linux ~/.config/wh), next to session.db and history.db (src/config.rs:46-58, src/config.rs:160-168); the repository's config.toml.global.template lists every key. The system prompt is not a key: it is the file SOUL.md in the same folder (start from soul.md.template), and the optional vision.md replaces the built-in request used to describe images. The two databases are separate by design: session.db is the WhatsApp library's session and key store, history.db holds the app's chats, messages, autoreply flags and image descriptions. Without openai_api_key and a non-blank SOUL.md the app still runs as a plain WhatsApp client. Optional keys tune the reply delay (reply_delay_seconds), the startup catch-up (catch_up_seconds), AI retries (ai_retries), the vision model (openai_vision_model), an AI request log (ai_log, written to ai_requests.log in the same folder) and the web panel port (web_port, unauthenticated, all interfaces). The old keys system_prompt, cooldown_seconds and group_cooldown_seconds are ignored. Keys and defaults: Configuration and data.

Autoreply in one paragraph

The first unanswered message of an enabled chat starts a reply_delay_seconds wait; messages arriving meanwhile join the same reply. Images are described once by the vision model and only their descriptions reach the AI. The reply is dropped if the owner answered by hand, and the model can stay silent by calling the no_reply tool, whose use is decided by SOUL.md. Details: AI auto-reply workflow.

Startup in one line

main prints the version and exits for --version; otherwise it loads the config, opens the history, starts the WhatsApp client, the optional web panel and an input thread, then runs the draw/receive loop until quit (src/main.rs:36-64, see Runtime and event loop).

Where to look

Task	Page	Source
Startup, version flag, channels, threads, main loop	Runtime and event loop	src/main.rs, build.rs
Events, state, keys, filter, chat deletion, reply orchestration, background tasks	Application state	src/app.rs
Screens, rendering, message formatting, footer version	Terminal UI	src/ui.rs
WhatsApp session, events, JIDs, media	WhatsApp client	src/whatsapp.rs
AI HTTP requests, no_reply tool, image descriptions, retries, errors	AI client	src/ai.rs
Web control panel: routes, security, browser page	Web control panel	src/web.rs, src/web_page.html
When and how the AI replies (global/per-chat, groups, reply delay, owner-answered drop, images, catch-up, context)	AI auto-reply workflow	src/autoreply.rs, src/app.rs
Local SQLite messages, chats, contacts, settings, image descriptions	History store	src/history.rs
Config keys, SOUL.md / vision.md, data dir, security notes	Configuration and data	src/config.rs
Test suites and how to run them	Unit tests	src/*.rs