wa_llm
A WhatsApp bot that can participate in group conversations, powered by AI. The bot monitors group messages and responds when mentioned.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ilanbenb/wa_llm with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ilanbenb/wa_llm'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/ilanbenb--wa-llm)HTML
<a href="/listings/ilanbenb--wa-llm"><img src="/api/listings/ilanbenb--wa-llm/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Clone & Configure
`git clone https://github.com/YOUR_USER/wa_llm.git cd wa_llm`
2. Create .env file
- Copy `.env.example` to `.env` and fill in required values.
cp .env.example .env
Environment Variables
<div style="font-size: 10px;">
| Variable | Description | Default | | ------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `WHATSAPP_HOST` | WhatsApp Web API URL | `http://localhost:3000` | | `WHATSAPP_BASIC_AUTH_USER` | WhatsApp API user | `admin` | | `WHATSAPP_BASIC_AUTH_PASSWORD` | WhatsApp API password | `admin` | | `VOYAGE_API_KEY` | Voyage AI key | – | | `DB_URI` | PostgreSQL URI | `postgresql+asyncpg://user:password@localhost:5432/postgres` | | `LOG_LEVEL` | Log level (`DEBUG`, `INFO`, `ERROR`) | `INFO` | | `ANTHROPIC_API_KEY` | Anthropic API key. You need to have a real anthropic key here, starts with sk-.... | – | | `LOGFIRE_TOKEN` | Logfire monitoring key, You need to have a real logfire key here | – | | `DM_AUTOREPLY_ENABLED` | Enable auto-reply for direct messages | `False` | | `DM_AUTOREPLY_MESSAGE` | Message to send as auto-reply | `Hello, I am not designed to answer to personal messages.` |
</div>
3. Starting the Services
**Option A: Development (Build from source)**
docker compose up -d
**Option B: Production (Use pre-built images)**
docker compose -f docker-compose.prod.yml up -d
4. Connect your device
1. Open http://localhost:3000 2. Scan the QR code with your WhatsApp mobile app. 3. Invite the bot device to any target groups you want to summarize. 4. Restart service: `docker compose restart wa_llm-web-server`
5. Activating the Bot for a Group
1. open pgAdmin or any other posgreSQL admin tool 2. connect using | Parameter | Value | | --------- | --------- | | Host | localhost | | Port | 5432 | | Database | postgres | | Username | user | | Password | password |
3. run the following update statement:
UPDATE public."group"
SET managed = true
WHERE group_name = 'Your Group Name';4. Restart the service: `docker compose restart wa_llm-web-server`
6. API usage
Swagger docs available at: `http://localhost:8000/docs`
Key Endpoints
- <b>/load_new_kbtopic (POST)</b> Loads a new knowledge base topic, prepares content for summarization. - <b>/trigger_summarize_and_send_to_groups (POST)</b> Generates & dispatches summaries, Sends summaries to all managed groups
7. Opt-Out Feature
Users can control whether they are tagged in bot-generated messages (summaries, answers) by sending Direct Messages (DMs) to the bot:
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 227 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 📱 WhatsApp Group Summary Bot
- 
- 
- 
- AI-powered WhatsApp bot that **joins any group, tracks conversations, and generates intelligent summaries**.
- ---
- ## Features
- - 🤖 Automated group chat responses (when mentioned)
- - 📝 Smart **LLM-based conversation summaries**
- - 📚 Knowledge base integration for context-aware answers
- - 📂 Persistent message history with PostgreSQL + `pgvector`
- - 🔗 Support for multiple message types (text, media, links)
- - 👥 Group management & customizable settings
- - 🔕 **Opt-out feature**: Users can opt-out of being tagged in summaries/answers via DM.
- - ⚡ REST API with Swagger docs (`localhost:8000/docs`)
- ---
- ## 🐳 Docker Compose Configurations
- This project includes multiple Docker Compose files for different environments:
- | File | Purpose | Usage |
- | ------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
- | `docker-compose.yml` | **Default/Development**. Builds the application from source code. | `docker compose up -d` |
- | `docker-compose.prod.yml` | **Production**. Uses pre-built images from GHCR. Recommended for deployment. | `docker compose -f docker-compose.prod.yml up -d` |
- | `docker-compose.local-run.yml` | **Local Execution**. For running the app on host while services run in Docker. | `docker compose -f docker-compose.local-run.yml up -d` |
- | `docker-compose.base.yml` | **Base Configuration**. Contains shared service definitions. | ❌ **Do not use directly** |
- ---
- ## 📋 Prerequisites
- - 🐳 Docker and Docker Compose
- - 🐍 Python 3.13+
- - 🗄️ PostgreSQL with `pgvector` extension
- - 🔑 Voyage AI API key
- - 📲 WhatsApp account for the bot
- ## Quick Start
- ### 1. Clone & Configure
- `git clone https://github.com/YOUR_USER/wa_llm.git
- cd wa_llm`
- ### 2. Create .env file
- - Copy `.env.example` to `.env` and fill in required values.
- ```
- cp .env.example .env
- ```
- #### Environment Variables
- <div style="font-size: 10px;">
- | Variable | Description | Default |
- | ------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------ |
- | `WHATSAPP_HOST` | WhatsApp Web API URL | `http://localhost:3000` |
- | `WHATSAPP_BASIC_AUTH_USER` | WhatsApp API user | `admin` |
- | `WHATSAPP_BASIC_AUTH_PASSWORD` | WhatsApp API password | `admin` |
- | `VOYAGE_API_KEY` | Voyage AI key | – |
- | `DB_URI` | PostgreSQL URI | `postgresql+asyncpg://user:password@localhost:5432/postgres` |
- | `LOG_LEVEL` | Log level (`DEBUG`, `INFO`, `ERROR`) | `INFO` |
- | `ANTHROPIC_API_KEY` | Anthropic API key. You need to have a real anthropic key here, starts with sk-.... | – |
- | `LOGFIRE_TOKEN` | Logfire monitoring key, You need to have a real logfire key here | – |
- | `DM_AUTOREPLY_ENABLED` | Enable auto-reply for direct messages | `False` |
- | `DM_AUTOREPLY_MESSAGE` | Message to send as auto-reply | `Hello, I am not designed to answer to personal messages.` |
- </div>
- ### 3. Starting the Services
- **Option A: Development (Build from source)**
- ```bash
- docker compose up -d
- ```
- **Option B: Production (Use pre-built images)**
- ```bash
- docker compose -f docker-compose.prod.yml up -d
- ```
- ### 4. Connect your device
- 1. Open http://localhost:3000
- 2. Scan the QR code with your WhatsApp mobile app.
- 3. Invite the bot device to any target groups you want to summarize.
- 4. Restart service: `docker compose restart wa_llm-web-server`
- ### 5. Activating the Bot for a Group
- 1. open pgAdmin or any other posgreSQL admin tool
- 2. connect using
- | Parameter | Value |
- | --------- | --------- |
- | Host | localhost |
- | Port | 5432 |
- | Database | postgres |
- | Username | user |
- | Password | password |
- 3. run the following update statement:
- ```
- UPDATE public."group"
- SET managed = true
- WHERE group_name = 'Your Group Name';
- ```
- 4. Restart the service: `docker compose restart wa_llm-web-server`
- ### 6. API usage
- Swagger docs available at: `http://localhost:8000/docs`
- #### Key Endpoints
- - <b>/load_new_kbtopic (POST)</b> Loads a new knowledge base topic, prepares content for summarization.
- - <b>/trigger_summarize_and_send_to_groups (POST)</b> Generates & dispatches summaries, Sends summaries to all managed groups
- ### 7. Opt-Out Feature
- Users can control whether they are tagged in bot-generated messages (summaries, answers) by sending Direct Messages (DMs) to the bot:
- | Command | Description |
- | :-------- | :--------------------------------------------------------------------------------- |
- | `opt-out` | Opt-out of being tagged. Your name will be displayed as text instead of a mention. |
- | `opt-in` | Opt-in to being tagged (default). |
- | `status` | Check your current opt-out status. |
- > **Note:** This only affects messages generated by the bot. It does not prevent other users from tagging you manually.
- ---
- ## 🚀 Production Deployment
- To deploy in a production environment using the optimized configuration:
- 1. **Create Production Environment File**:
- Copy `.env.example` to `.env.prod` and configure your production secrets.
- ```bash
- cp .env.example .env.prod
- ```
- 2. **Start Services**:
- ```bash
- docker compose -f docker-compose.prod.yml up -d
- ```
- This configuration includes:
- - Automatic restart policies (`restart: always`)
- ---
- ## Developing
- ### Setup
- Install dependencies using `uv`:
- ```bash
- uv sync --all-extras --dev
- ```
- ### Development Commands
- The project uses **Poe the Poet** for task automation with parallel execution:
- ```bash
- # Run all checks (format, then parallel lint/typecheck/test)
- uv run poe check
- # Individual tasks
- uv run poe format # Format code with ruff
- uv run poe lint # Lint code with ruff
- uv run poe typecheck # Type check with pyright
- uv run poe test # Run tests with pytest
- # List all available tasks
- uv run poe
- ```
- The `check` command runs formatting first, then executes linting, type checking, and testing **in parallel** for faster execution.
- ### Key Files
- - Main application: `app/main.py`
- - WhatsApp client: `src/whatsapp/client.py`
- - Message handler: `src/handler/__init__.py`
- - Database models: `src/models/`
- ---
- ## Architecture
- The project consists of several key components:
- - FastAPI backend for webhook handling
- - WhatsApp Web API client for message interaction
- - PostgreSQL database with vector storage for knowledge base
- - AI-powered message processing and response generation
- ---
- ## Contributing
- 1. Fork the repository
- 2. Create a feature branch
- 3. Submit a pull request
- ---
- ## License
- [LICENCE](CODE_OF_CONDUCT.md)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.