WazzapAgent

KO | EN

gitlite — search

#mcp #agents #bash #javascript #security #ai-agents #hacktoberfest #ai #terminal #csharp

(★ 9)

No description available.

File Explorer

ZIP Download

- - deploy-docs.yml
- - 00-overview.md
  - 01-runtime-flow.md
  - 02-modules-map.md
  - 03-commands-and-permissions.md
  - 04-protocol-and-actions.md
  - 05-state-data-and-db.md
  - 06-rebuild-from-scratch.md
  - README.md
- BUTTONS.md
- ptero-boot.mjs
- ptero-bootstrap.sh
- README.md
- - __init__.py
  - account_supervisor.py
  - accounts.py
  - config.py
  - dashboard.py
  - history.py
  - log.py
  - main.py
  - session.py
  - sticker_db.py
  - stickers.py
- - stub_node_server.py
  - test_account_supervisor.py
  - test_accounts.py
  - test_ack_hydrator.py
  - test_agent_session.py
  - test_batch_processor.py
  - test_bot_mention_label.py
  - test_bug_fixes.py
  - test_context_injection_guard.py
  - test_correlation.py
  - test_daily_task.py
  - test_dashboard_isolation.py
  - test_db_resilience.py
  - test_direct_invoke.py
  - test_dump_real_prompt.py
  - test_errors.py
  - test_event_router.py
  - test_events.py
  - test_hydration.py
  - test_idle_trigger.py
  - test_invalidate_chat_caches.py
  - test_lazy_media.py
  - test_llm1_router.py
  - test_llm2_responder.py
  - test_llm_context_builder.py
  - test_llm_context_serialization.py
  - test_media_resolver.py
  - test_memory.py
  - test_mention_render.py
  - test_model_cache_tenant_isolation.py
  - test_moderation_cache.py
  - test_moderation_history.py
  - test_multi_account.py
  - test_mute_gate.py
  - test_output_path_traversal.py
  - test_protocol.py
  - test_reply_dedup.py
  - test_scheduled_task.py
  - test_socket.py
  - test_subagent_cache.py
  - test_subagent_file_ids.py
  - test_subagent_finished_lines.py
  - test_subagent_ingress_reliability.py
  - test_subagent_output.py
  - test_subagent_schema.py
  - test_subagent_steer_files.py
  - test_subagent_tracker_context.py
  - test_tagall_trigger.py
  - test_tenant_isolation_globals.py
  - test_tool_calls_and_permissions.py
  - test_transport.py
  - test_webhook_queue.py
  - test_whatsapp_format.py
  - test_ws_transport_options.py
- - __init__.py
  - correlation.py
  - errors.py
  - events.py
  - protocol.py
  - socket.py
  - transport.py
- __init__.py
- conftest.py
- promptoverride.txt
- promptoverride_assistant.txt
- promptoverride_semi_toxic.txt
- systemprompt.txt
- - accountCatalog.ts
  - accountContext.ts
  - actionDispatcher.ts
  - baileysFactory.ts
  - eventForwarder.ts
- - auditLog.ts
  - envStore.ts
  - server.ts
  - subagentOutboxClient.ts
- - Database.ts
- - ports.ts
  - types.ts
- - accountRegistry.ts
  - wsServer.ts
- - updateManager.ts
- - ambient.d.ts
- - cachedAuthState.ts
  - index.ts
- - actions.ts
  - botConfig.ts
  - connection.ts
  - events.ts
  - inbound.ts
  - index.ts
  - moderation.ts
  - outbound.ts
  - presence.ts
  - privateChat.ts
  - runCommand.ts
  - sendQueue.ts
  - utils.ts
- config.ts
- index.ts
- logFormat.ts
- logger.ts
- mediaHandler.ts
- - two-account.md
  - two_account_smoke.py
- - account-catalog.test.ts
  - account-context.test.ts
  - account-registry.test.ts
  - action-dispatcher.test.ts
  - activation-notice.test.ts
  - activation.test.ts
  - baileys-factory.test.ts
  - bot-conf.test.ts
  - botinvoke-unwrap.test.ts
  - broadcast.test.ts
  - button-command-sock.test.ts
  - button-registry.test.ts
  - caller-tier.test.ts
  - command-model.test.ts
  - compat.test.ts
  - config-default-scope.test.ts
  - control-events.test.ts
  - control-panel-data.test.ts
  - control-panel.test.ts
  - daily-task.test.ts
  - dashboard.test.ts
  - db-isolation.test.ts
  - download-command.test.ts
  - download-media.test.ts
  - event-forwarder.test.ts
  - generate-cta.test.ts
  - group-command.test.ts
  - group-join-dedup.test.ts
  - group-metadata-stampede.test.ts
  - inbound-catch-cache.test.ts
  - info.test.ts
  - join-errors.test.ts
  - media-isolation.test.ts
  - memory.test.ts
  - outbound-bot-mention.test.ts
  - owner-lid.test.ts
  - private-chat-gate.test.ts
  - prompt-mentions.test.ts
  - protocol-types.test.ts
  - registry-unbind-guard.test.ts
  - relay-cache.test.ts
  - schedule-task.test.ts
  - settings-default.test.ts
  - smoke.test.ts
  - sticker-store.test.ts
  - sticker-text.test.ts
  - subagent-default-seed.test.ts
  - tagall.test.ts
  - update-manager.test.ts
  - ws-server.test.ts
- - index.md
- - .nojekyll
- .gitignore
- docusaurus.config.ts
- package-lock.json
- package.json
- README.md
- sidebars.ts
- tsconfig.json
.env.example
.env.minimal.example
.gitignore
.python-version
AGENTS.md
CONTRACT.md
DOCS_ACCURACY_REVIEW.md
llms.txt
package.json
pnpm-workspace.yaml
pyproject.toml
README.md
requirements-dev.txt
requirements.txt
start.sh
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

Node 18+ Visit
Python 3.10+ Visit
License Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A WhatsApp AI agent: it links a WhatsApp account, listens to your chats, and
replies with an LLM — plus group moderation, stickers, quizzes, and slash
commands. It runs as **two processes** you start together:

- a **Node.js gateway** (Baileys) that talks to WhatsApp, and
- a **Python bridge** that runs the LLM pipeline.

> 🚀 **Want to deploy on a Pterodactyl panel instead of running locally?**
> See **[pterodactyl/README.md](./pterodactyl/README.md)** for the full guide
> (including pairing without a QR code and running on a fixed node-only image).

> For architecture, concepts, and developer docs, see
> [AGENTS.md](./AGENTS.md); the wire protocol lives in [CONTRACT.md](./CONTRACT.md).

---

## Prerequisites

- **Node.js 18+** (tested up to Node 25)
- **Python 3.10+**
- **pnpm 9+** — `npm i -g pnpm` or `corepack enable pnpm`
- **ffmpeg** on your `PATH` — only needed for the `/sticker` video → sticker
  feature; everything else works without it.
- An **OpenAI-compatible LLM API key** (OpenAI, OpenRouter, etc.)
- A phone with **WhatsApp** to link the bot to.

---

## Quick start

### 1. Install dependencies

```bash
pnpm install                      # Node gateway
pip install -r requirements.txt   # Python bridge (Python 3.10+)
```

`start.sh` resolves the bridge's absolute Python executable without leaving its
virtualenv, then exports it as `PY_BIN`; Node uses that same interpreter for
Python-backed tools such as SpotDL. Dependency installation remains an explicit
setup/deployment step.

### 2. Configure

Copy the minimal env template and fill in your keys:

```bash
cp .env.minimal.example .env
```

Then edit `.env`. Only four decisions are shown in the starter file:

```dotenv
LLM2_API_KEY=your-api-key
BOT_OWNER_JIDS=6281234567890
CONTROL_PANEL_TOKEN=replace-with-a-long-random-value
WA_PAIRING_NUMBER=6281234567890   # optional; leave empty for QR/panel pairing
```

The defaults use OpenAI and `gpt-4.1`. Add `LLM2_ENDPOINT` and `LLM2_MODEL` only
for another OpenAI-compatible provider. [`.env.example`](./.env.example) is the
full reference for routing, networking, multi-account, and optional features.

### 3. Run the bot

Start the **gateway first**, then the **bridge** (two terminals, or two
background processes):

```bash
# terminal 1 — Node gateway (WhatsApp side)
pnpm dev

# terminal 2 — Python bridge (LLM side)
PYTHONPATH=python python -m bridge.main
```

### 4. Link your WhatsApp

- **Pairing code (no QR):** with `WA_PAIRING_NUMBER` set, the gateway prints an
  8-character code in terminal 1:
  ```
  ================ WhatsApp Pairing Code ================
    Number : 6281234567890
    Code   : ABCD-EFGH
  ======================================================
  ```
  On the bot's phone: **WhatsApp → Linked Devices → Link a Device → Link with
  phone number**, then enter the code.
  If WhatsApp rejects or closes the attempt, the gateway deliberately does not
  retry automatically. Restart to make one fresh attempt; repeated rapid
  attempts can trigger a temporary WhatsApp pairing restriction. The default
  in-process cooldown is 15 minutes (`WA_PAIRING_RETRY_COOLDOWN_MS=900000`).
- **QR code:** leave `WA_PAIRING_NUMBER` empty and scan the QR printed in
  terminal 1 instead.

Once linked you'll see `WhatsApp socket connected`. Message the bot (or add it
to a group) and it replies. The WhatsApp session is saved under `./data/auth`,
so you only link once.

### Control panel

The Node gateway also serves a multi-tenant control panel at
`http://127.0.0.1:8080` by default. Enter `CONTROL_PANEL_TOKEN` on its login
screen. The API stays locked only when the token is empty; any non-empty token
is accepted.

From the panel you can:

- inspect Node, Python bridge, WhatsApp, queue, and per-tenant state;
- generate a native WhatsApp pairing code directly (leave
  `WA_PAIRING_NUMBER` empty if you want pairing to be panel-driven);
- reconnect or explicitly disconnect a WhatsApp session;
- edit chat/default settings, prompts, memories, models, activation codes,
  tenant-wide bot config, and sticker catalogs;
- use locally persisted chat/group names for scopes without a live metadata
  sweep;
- edit the shared `.env` through focused System sections with secret values
  masked and restart-only fields marked;
- inspect durable sub-agent completion callbacks under **System → Sub-agent
  outbox**, retry terminal/pending deliveries, or discard only the callback
  envelope while retaining the sub-agent result and output files until normal
  idle cleanup;
- check the installed/upstream application and compatibility versions, then
  safely fast-forward update or restart both supervised services; and
- review the persistent control-panel audit trail.

The terminal renders only the first QR emitted by each unregistered socket, so
long-running logs are not flooded by Baileys' ~20-second QR refresh. Request a
fresh native code from the panel or explicitly reconnect the account when the
first QR expires.

While an account is unpaired or reconnecting, the bridge remains connected to
Node but parks cold sub-agent recovery, scheduled tasks, and direct-invoke
delivery. They resume only after WhatsApp reports `open`; pre-pair actions are
rejected before execution and remain safe to retry after pairing.

Sub-agent completion ownership transfers as soon as the bridge has durably
stored the result. A file larger than the bridge's 200 MiB staging limit is
reported as an explicit skipped output instead of keeping the entire callback
in an infinite retry loop. The text report and any other valid outputs remain
deliverable after pairing.

`package.json` carries an application `version` and a separate
`compatibilityVersion`. The latter must be incremented when an update may need
manual environment, dependency, database, or deployment changes. The panel
blocks silent cross-compatibility updates and presents an explicit warning.

The server binds loopback by default. Set `CONTROL_PANEL_HOST=0.0.0.0` to keep
localhost access and also listen on Tailscale/LAN, then open
`http://<tailscale-ip>:8080` from the other device. Set it to the server's exact
Tailscale IP to restrict the listener to that interface. Host and port can also
be changed from **System → Control panel network**; use **System → Runtime &
updates → Restart services** after
saving. When reachable from another device, keep the token private and use
Tailscale ACLs, a firewall, or an HTTPS reverse proxy. Pairing and session-reset
endpoints must never be exposed without access control.

---

## Using the bot

- **Direct messages** always get a reply.
- **Groups** respond based on the chat's mode (configure via `/setting`) and
  triggers (`/trigger`) — e.g. when mentioned, replied to, or by name.
- **Slash commands** (type `/help` in a chat to list them) cover settings,
  moderation, stickers, broadcasts, and more.

Owner-only commands (like `/broadcast`) require your number to be in
`BOT_OWNER_JIDS`.

---

## Useful commands

```bash
pnpm dev          # run the gateway (alias of pnpm start)
pnpm typecheck    # TypeScript type-check (must be 0 errors)
pnpm test         # Node tests
PYTHONPATH=python python -m pytest python/tests -q   # Python tests
```

---

## Multiple accounts (optional)

Open **Accounts → Add account** in the control panel, enter a tenant name/ID and
the WhatsApp phone number, then enter the generated pairing code in WhatsApp.
The account becomes live without restarting Node or the Python bridge.

The panel stores its catalog in the git-ignored `accounts.json`. Each account is
fully isolated under `tenants/<id>/{auth,db,media,stickers}` and owns a stable
callback port slot plus a generated per-account WebSocket credential. Removing
an account stops its runtime but deliberately keeps that tenant directory, so an
accidental removal does not destroy auth or data.

Manual `FOLDER_PATHS` and `ACCOUNTS_JSON` configuration remains supported for
custom deployments; see [`.env.example`](./.env.example).

---

## Deploy on Pterodactyl

To run on a Pterodactyl panel — even a locked-down managed host that only offers
a fixed node-only image — follow **[pterodactyl/README.md](./pterodactyl/README.md)**.

---

## License

ISC — see [package.json](./package.json).

WazzapAgent

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README