mirror of
https://github.com/simplex-chat/simplex-chat.git
synced 2026-05-03 05:28:18 +00:00
Narasimha-sc
5a3dfdd2b4
* plans: 20260207-support-bot.md * Update 20260207-support-bot.md * plans: 20260207-support-bot-implementation.md * plans: Update 20260207-support-bot-implementation.md * Relocate plans * apps: support bot code & tests * apps: support bot relocate * support-bot: Fix basic functionality * apps: support-bot /add command & fixes * apps: simplex-support-bot: Change Grok logo * Further usability improvements * simplex-support-bot: Update support plan to reflect current flow * simplex-support-bot: update product design plan * support-bot: update plan * support-bot: review and refine product spec * support-bot: update product spec — complete state, /join team-only, card debouncing - Group preferences applied once at creation, not on every startup - /join restricted to team group only - Team/Grok reply or reaction auto-completes conversation (✅) - Customer message reverts to incomplete - Card updates debounced globally with 15-minute batch flush * support-bot: update implementation plan * support-bot: implement stateless bot with cards, Grok, team flow, hardening Complete rewrite of the support bot to stateless architecture: - State derived from group composition + chat history (survives restarts) - Card dashboard in team group with live status, preview, /join commands - Two-profile architecture (main + Grok) with profileMutex serialization - Grok join race condition fix via bufferedGrokInvitations - Card preview: newest-first truncation, newline sanitization, sender prefixes - Best-effort startup (invite link, group profile update) - Team group preferences: directMessages, fullDelete, commands - 122 tests across 27 suites * support-bot: use apiCreateMemberContact and apiSendMemberContactInvitation instead of raw commands Replace sendChatCmd("/_create member contact ...") and sendChatCmd("/_invite member contact ...") with the typed API methods added in simplex-chat-nodejs. Update plans and build script accordingly. * plans: 20260207-support-bot.md * Update 20260207-support-bot.md * plans: 20260207-support-bot-implementation.md * plans: Update 20260207-support-bot-implementation.md * Relocate plans * apps: support bot code & tests * apps: support bot relocate * support-bot: Fix basic functionality * apps: support-bot /add command & fixes * apps: simplex-support-bot: Change Grok logo * Further usability improvements * simplex-support-bot: Update support plan to reflect current flow * simplex-support-bot: update product design plan * support-bot: update plan * support-bot: review and refine product spec * support-bot: update product spec — complete state, /join team-only, card debouncing - Group preferences applied once at creation, not on every startup - /join restricted to team group only - Team/Grok reply or reaction auto-completes conversation (✅) - Customer message reverts to incomplete - Card updates debounced globally with 15-minute batch flush * support-bot: update implementation plan * support-bot: implement stateless bot with cards, Grok, team flow, hardening Complete rewrite of the support bot to stateless architecture: - State derived from group composition + chat history (survives restarts) - Card dashboard in team group with live status, preview, /join commands - Two-profile architecture (main + Grok) with profileMutex serialization - Grok join race condition fix via bufferedGrokInvitations - Card preview: newest-first truncation, newline sanitization, sender prefixes - Best-effort startup (invite link, group profile update) - Team group preferences: directMessages, fullDelete, commands - 122 tests across 27 suites * support-bot: use apiCreateMemberContact and apiSendMemberContactInvitation instead of raw commands Replace sendChatCmd("/_create member contact ...") and sendChatCmd("/_invite member contact ...") with the typed API methods added in simplex-chat-nodejs. Update plans and build script accordingly. * support-bot: more improvemets * support-bot: add tests for Grok batch dedup and initial response gating 7 new tests covering the duplicate Grok reply fix: - batch dedup: only last customer message per group triggers API call - batch dedup: multi-group batches handled independently - batch dedup: non-customer messages filtered from batch - initial response gating: per-message responses suppressed during activateGrok - gating clears: per-message responses resume after activation completes Update implementation plan test catalog (122 → 129 tests). * support-bot: load context from context file * Rename Grok AI -> Grok * Remove unused strings.ts * support-bot: change messages * cardFlushMinutes 15 -> cardFlushSeconds 300 * support-bot: /team message when grok present * support-bot: correct messages * support-bot: update plans to reflect latest changes * Update plan for state derivation * support-bot: Update state machine plans * support-bot: implement customData state * Fix Grok revertStateOnFail race condition * support-bot: plans adversarial review * support-bot: /join ID part of card in plan * support-bot: implement /join ID inside card * support-bot: plans use params instead of regex in /join * support-bot: Implement adversarial review changes * support-bot: no re-invite if already invited * support-bot: /team should give owner to invited member * Don't change username for existing database * support-bot: update bot commands before sending commands * support-bot: adversarial review fixes * support-bot: implement postgresql (#6876) * support-bot: sqlite/postgres backend via typed DbConfig and parseArgs flags * support-bot: add README with setup and flags reference * support-bot: use published simplex-chat, drop build.sh/start.sh * support-bot: switch CLI to commander, add --help * support-bot: update README --------- Co-authored-by: shum <github.shum@liber.li> Co-authored-by: sh <37271604+shumvgolove@users.noreply.github.com>
102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
# SimpleX Support Bot
|
|
|
|
A business-address bot that triages incoming support chats, optionally runs them through Grok, and routes handoffs to a team group.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js v18 or newer (v24 tested)
|
|
- `GROK_API_KEY` env var (xAI) — optional; the bot runs without it
|
|
- For the PostgreSQL backend: Linux x86_64, `libpq5` installed on the host, and a reachable PostgreSQL server
|
|
|
|
## Install & build
|
|
|
|
```bash
|
|
cd apps/simplex-support-bot
|
|
npm install # downloads native libs + transitive deps
|
|
npm run build # tsc
|
|
```
|
|
|
|
By default this installs the **SQLite** backend.
|
|
|
|
To use **PostgreSQL** instead, drop a `.npmrc` next to `package.json` *before* `npm install`:
|
|
|
|
```bash
|
|
echo 'simplex_backend=postgres' > .npmrc
|
|
npm install # now pulls postgres-flavored native libs
|
|
npm run build
|
|
```
|
|
|
|
`.npmrc` lives next to the package — npm reads it natively, no extra setup.
|
|
|
|
### Switching backends
|
|
|
|
`npm install` is a no-op for already-installed deps, so editing `.npmrc` and re-running `npm install` will *not* re-trigger `simplex-chat`'s preinstall. To switch backends, force a clean install:
|
|
|
|
```bash
|
|
rm -rf node_modules
|
|
npm install # download-libs.js re-runs and pulls the right native lib
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
mkdir -p data # state file lives here by default
|
|
|
|
# SQLite (default)
|
|
npm start -- --team-group "Support Team"
|
|
|
|
# PostgreSQL
|
|
npm start -- --team-group "Support Team" \
|
|
--pg-conn "postgres://user:pass@host/db"
|
|
```
|
|
|
|
The bot runs via `npm start` so npm can expose `.npmrc` settings to the process — `detectBackend()` reads `npm_config_simplex_backend` to know which backend was installed.
|
|
|
|
## Flags
|
|
|
|
Run `npm start -- --help` for the auto-generated reference. Summary:
|
|
|
|
| Flag | Backend | Required | Default | Description |
|
|
|---|---|---|---|---|
|
|
| `--team-group` | both | yes | — | team group display name |
|
|
| `--state-file` | both | no | `./data/state.json` | path to bot state JSON |
|
|
| `--sqlite-file-prefix` | sqlite | no | `./data/simplex` | DB file prefix (creates `<prefix>_chat.db`, `<prefix>_agent.db`) |
|
|
| `--sqlite-key` | sqlite | no | (unencrypted) | SQLCipher encryption key |
|
|
| `--pg-conn` | postgres | yes | — | PostgreSQL connection string |
|
|
| `--pg-schema` | postgres | no | `simplex_v1` | schema prefix used for bot tables |
|
|
| `-a` / `--auto-add-team-members` | both | no | | comma-separated `ID:name` pairs (e.g. `1:Alice,2:Bob`) |
|
|
| `--timezone` | both | no | `UTC` | IANA zone for weekend detection |
|
|
| `--complete-hours` | both | no | `3` | auto-complete chats after N hours idle (`0` disables) |
|
|
| `--card-flush-seconds` | both | no | `300` | debounce card state writes |
|
|
| `--context-file` | both | required with `GROK_API_KEY` | | text file with Grok system context |
|
|
| `-h` / `--help` | both | no | | show usage and exit |
|
|
|
|
## Environment variables
|
|
|
|
| Var | Purpose |
|
|
|---|---|
|
|
| `GROK_API_KEY` | xAI API key; enables Grok replies |
|
|
| `SIMPLEX_BACKEND` | alternative to `.npmrc` for selecting the install backend (`sqlite` or `postgres`) |
|
|
|
|
## Local development against unreleased lib changes
|
|
|
|
This package depends on `simplex-chat` from npm. To test against an in-tree version:
|
|
|
|
```bash
|
|
# In packages/simplex-chat-nodejs
|
|
npm link
|
|
|
|
# In apps/simplex-support-bot
|
|
npm link simplex-chat
|
|
```
|
|
|
|
`npm unlink simplex-chat && npm install` reverts to the registry version.
|
|
|
|
## Troubleshooting
|
|
|
|
- **`--pg-conn is required when backend is postgres`** — the postgres backend is installed but you didn't pass a connection string.
|
|
- **`libpq5` errors at startup** — install `libpq5` on the host (`apt install libpq5` on Debian/Ubuntu).
|
|
- **`ENOENT: no such file or directory, open './data/state.json'`** — the parent directory of `--state-file` must exist; `mkdir -p data` before starting.
|
|
- **Wrong backend installed** — check `node_modules/simplex-chat/libs/installed.txt`. Edit `.npmrc`, then `rm -rf node_modules && npm install` to switch (`npm install` alone won't re-run the dep's preinstall).
|
|
- **`libpq` connection error** at startup with sqlite-flavored config (or vice versa) — `.npmrc` was changed but libs weren't reinstalled. See "Switching backends" above.
|