Chatbot Modules Specification

1. Purpose & Overview

The

chatbot

and

wa_chatbot

modules provide dual AI capabilities: the Platform AI Assistant (dashboard helper) and the WhatsApp AI Auto-Responder (automated customer response engine with vision support).

2. Responsibilities

Manage tenant knowledge base context files (
```
content.json
```
).
Prompt OpenRouter LLM text models (
```
stepfun/step-3.5-flash
```
) and vision models (
```
openai/gpt-4o
```
).
Automatically process inbound WhatsApp text and image attachments.

3. Directory Structure

text

services/api/
├── chatbot/               # Platform AI Assistant
│   ├── views.py
│   └── tests.py
└── wa_chatbot/            # WhatsApp Auto-Responder & Vision
    ├── services.py
    ├── views.py
    └── tests.py

4. Models & Database Schemas

Uses
```
tenants.TenantConfig
```
for prompt overrides and
```
messaging.Message
```
for history memory.

5. Services & Business Logic

```
WAChatbotService.process_inbound_message(tenant, conversation, message)
```
: Analyzes message, fetches context, prompts OpenRouter, and dispatches outbound WhatsApp reply.
```
WAChatbotService.analyze_image(image_url)
```
: Prompts vision model for image content understanding.

6. Serializers & Data Transfer Objects

```
ChatbotQuerySerializer
```
: Validates question input for platform assistant endpoint.

7. Views & API Endpoints

```
POST /api/chatbot/test/
```
: Test AI response generation.
```
GET /api/chatbot/check/
```
: Check AI engine health.

8. Permissions & Role Rules

```
AllowAny
```
for chatbot health checks;
```
IsAuthenticated
```
for assistant queries.

9. Signals & Event Listeners

Inbound WhatsApp message signals trigger
```
process_inbound_message
```
asynchronously.

10. Background Tasks & Celery Jobs

AI generation tasks executed in Celery background workers to keep webhooks responsive.

11. Data Flow & External Dependencies

Connects to OpenRouter REST API using
```
OPENROUTER_API_KEY
```
.

12. Business Rules & Validations

If no knowledge context is found or API times out, returns
```
WA_CHATBOT_FALLBACK_MESSAGE
```
.

13. Sequence Diagram (Mermaid)

Rendering diagram...

14. Known Limitations & Technical Debt

Local
```
content.json
```
file storage for knowledge base context in early version.

15. Future Improvements

Vector database Integration (pgvector / ChromaDB) for scalable Retrieval-Augmented Generation (RAG).

AI Chatbot Engine Module