Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ilanbenb--wa-llm/badge.svg)](/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

i

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)

  1. # 📱 WhatsApp Group Summary Bot
  2. ![release version](https://img.shields.io/github/v/release/ilanbenb/wa_llm)
  3. ![Build Image](https://github.com/ilanbenb/wa_llm/actions/workflows/docker.yml/badge.svg)
  4. ![Release](https://github.com/ilanbenb/wa_llm/actions/workflows/release.yml/badge.svg)
  5. AI-powered WhatsApp bot that **joins any group, tracks conversations, and generates intelligent summaries**.
  6. ---
  7. ## Features
  8. - 🤖 Automated group chat responses (when mentioned)
  9. - 📝 Smart **LLM-based conversation summaries**
  10. - 📚 Knowledge base integration for context-aware answers
  11. - 📂 Persistent message history with PostgreSQL + `pgvector`
  12. - 🔗 Support for multiple message types (text, media, links)
  13. - 👥 Group management & customizable settings
  14. - 🔕 **Opt-out feature**: Users can opt-out of being tagged in summaries/answers via DM.
  15. - ⚡ REST API with Swagger docs (`localhost:8000/docs`)
  16. ---
  17. ## 🐳 Docker Compose Configurations
  18. This project includes multiple Docker Compose files for different environments:
  19. | File | Purpose | Usage |
  20. | ------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
  21. | `docker-compose.yml` | **Default/Development**. Builds the application from source code. | `docker compose up -d` |
  22. | `docker-compose.prod.yml` | **Production**. Uses pre-built images from GHCR. Recommended for deployment. | `docker compose -f docker-compose.prod.yml up -d` |
  23. | `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` |
  24. | `docker-compose.base.yml` | **Base Configuration**. Contains shared service definitions. | ❌ **Do not use directly** |
  25. ---
  26. ## 📋 Prerequisites
  27. - 🐳 Docker and Docker Compose
  28. - 🐍 Python 3.13+
  29. - 🗄️ PostgreSQL with `pgvector` extension
  30. - 🔑 Voyage AI API key
  31. - 📲 WhatsApp account for the bot
  32. ## Quick Start
  33. ### 1. Clone & Configure
  34. `git clone https://github.com/YOUR_USER/wa_llm.git
  35. cd wa_llm`
  36. ### 2. Create .env file
  37. - Copy `.env.example` to `.env` and fill in required values.
  38. ```
  39. cp .env.example .env
  40. ```
  41. #### Environment Variables
  42. <div style="font-size: 10px;">
  43. | Variable | Description | Default |
  44. | ------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------ |
  45. | `WHATSAPP_HOST` | WhatsApp Web API URL | `http://localhost:3000` |
  46. | `WHATSAPP_BASIC_AUTH_USER` | WhatsApp API user | `admin` |
  47. | `WHATSAPP_BASIC_AUTH_PASSWORD` | WhatsApp API password | `admin` |
  48. | `VOYAGE_API_KEY` | Voyage AI key | – |
  49. | `DB_URI` | PostgreSQL URI | `postgresql+asyncpg://user:password@localhost:5432/postgres` |
  50. | `LOG_LEVEL` | Log level (`DEBUG`, `INFO`, `ERROR`) | `INFO` |
  51. | `ANTHROPIC_API_KEY` | Anthropic API key. You need to have a real anthropic key here, starts with sk-.... | – |
  52. | `LOGFIRE_TOKEN` | Logfire monitoring key, You need to have a real logfire key here | – |
  53. | `DM_AUTOREPLY_ENABLED` | Enable auto-reply for direct messages | `False` |
  54. | `DM_AUTOREPLY_MESSAGE` | Message to send as auto-reply | `Hello, I am not designed to answer to personal messages.` |
  55. </div>
  56. ### 3. Starting the Services
  57. **Option A: Development (Build from source)**
  58. ```bash
  59. docker compose up -d
  60. ```
  61. **Option B: Production (Use pre-built images)**
  62. ```bash
  63. docker compose -f docker-compose.prod.yml up -d
  64. ```
  65. ### 4. Connect your device
  66. 1. Open http://localhost:3000
  67. 2. Scan the QR code with your WhatsApp mobile app.
  68. 3. Invite the bot device to any target groups you want to summarize.
  69. 4. Restart service: `docker compose restart wa_llm-web-server`
  70. ### 5. Activating the Bot for a Group
  71. 1. open pgAdmin or any other posgreSQL admin tool
  72. 2. connect using
  73. | Parameter | Value |
  74. | --------- | --------- |
  75. | Host | localhost |
  76. | Port | 5432 |
  77. | Database | postgres |
  78. | Username | user |
  79. | Password | password |
  80. 3. run the following update statement:
  81. ```
  82. UPDATE public."group"
  83. SET managed = true
  84. WHERE group_name = 'Your Group Name';
  85. ```
  86. 4. Restart the service: `docker compose restart wa_llm-web-server`
  87. ### 6. API usage
  88. Swagger docs available at: `http://localhost:8000/docs`
  89. #### Key Endpoints
  90. - <b>/load_new_kbtopic (POST)</b> Loads a new knowledge base topic, prepares content for summarization.
  91. - <b>/trigger_summarize_and_send_to_groups (POST)</b> Generates & dispatches summaries, Sends summaries to all managed groups
  92. ### 7. Opt-Out Feature
  93. Users can control whether they are tagged in bot-generated messages (summaries, answers) by sending Direct Messages (DMs) to the bot:
  94. | Command | Description |
  95. | :-------- | :--------------------------------------------------------------------------------- |
  96. | `opt-out` | Opt-out of being tagged. Your name will be displayed as text instead of a mention. |
  97. | `opt-in` | Opt-in to being tagged (default). |
  98. | `status` | Check your current opt-out status. |
  99. > **Note:** This only affects messages generated by the bot. It does not prevent other users from tagging you manually.
  100. ---
  101. ## 🚀 Production Deployment
  102. To deploy in a production environment using the optimized configuration:
  103. 1. **Create Production Environment File**:
  104. Copy `.env.example` to `.env.prod` and configure your production secrets.
  105. ```bash
  106. cp .env.example .env.prod
  107. ```
  108. 2. **Start Services**:
  109. ```bash
  110. docker compose -f docker-compose.prod.yml up -d
  111. ```
  112. This configuration includes:
  113. - Automatic restart policies (`restart: always`)
  114. ---
  115. ## Developing
  116. ### Setup
  117. Install dependencies using `uv`:
  118. ```bash
  119. uv sync --all-extras --dev
  120. ```
  121. ### Development Commands
  122. The project uses **Poe the Poet** for task automation with parallel execution:
  123. ```bash
  124. # Run all checks (format, then parallel lint/typecheck/test)
  125. uv run poe check
  126. # Individual tasks
  127. uv run poe format # Format code with ruff
  128. uv run poe lint # Lint code with ruff
  129. uv run poe typecheck # Type check with pyright
  130. uv run poe test # Run tests with pytest
  131. # List all available tasks
  132. uv run poe
  133. ```
  134. The `check` command runs formatting first, then executes linting, type checking, and testing **in parallel** for faster execution.
  135. ### Key Files
  136. - Main application: `app/main.py`
  137. - WhatsApp client: `src/whatsapp/client.py`
  138. - Message handler: `src/handler/__init__.py`
  139. - Database models: `src/models/`
  140. ---
  141. ## Architecture
  142. The project consists of several key components:
  143. - FastAPI backend for webhook handling
  144. - WhatsApp Web API client for message interaction
  145. - PostgreSQL database with vector storage for knowledge base
  146. - AI-powered message processing and response generation
  147. ---
  148. ## Contributing
  149. 1. Fork the repository
  150. 2. Create a feature branch
  151. 3. Submit a pull request
  152. ---
  153. ## License
  154. [LICENCE](CODE_OF_CONDUCT.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.