🤖 FacilitBot

WhatsApp Customer Service Automation Bot powered by a multi-agent AI system

---

<p align="center"> <strong>Python 3.12+</strong> &nbsp;|&nbsp; <strong>Flask</strong> &nbsp;|&nbsp; <strong>CrewAI</strong> &nbsp;|&nbsp; <strong>Z-API</strong> &nbsp;|&nbsp; <strong>SSE Real-Time</strong> </p>

---

📋 Table of Contents

• Overview
• Features
• System Architecture
• Conversation Flow
• Tech Stack
• Project Structure
• Prerequisites
• Installation
• Configuration
• Usage
• REST API Reference
• SSE Real-Time Events
• Multi-Agent System
• Development Guide
• Troubleshooting
• License

---

🎯 Overview

FacilitBot is a production-grade WhatsApp automation server that handles customer service conversations end-to-end. It replaces manual chat operators with an intelligent multi-agent system built on CrewAI, capable of guiding customers through a 14-step sales funnel — from greeting to product quoting, promotional offers, and final handoff to a human attendant.

The system integrates with WhatsApp via the Z-API service, provides a fully-featured REST API for a companion React Native mobile dashboard, and streams real-time updates through Server-Sent Events (SSE). All conversation state is persisted to disk with thread-safe access, making it resilient across restarts and concurrent webhook processing.

Target Audience: Small-to-medium businesses that want to automate WhatsApp customer service, generate quotes for products/services, and provide a seamless bridge between automated bots and human operators.

---

✨ Features

Core Capabilities

| Feature | Description | |---|---| | Multi-Agent AI | 6 specialized agents (Orchestrator, Quote, Sales, Media, Alert, Retry) working in concert | | 14-Step Sales Funnel | Full conversation flow from greeting → product selection → quoting → promotion → human handoff | | WhatsApp Integration | Send/receive text messages, audio, images, and video via Z-API | | REST API | 10+ authenticated endpoints for a React Native companion app | | Real-Time SSE | Push events to mobile client on new messages, bot status changes, and alerts | | Inactivity Monitoring | Automatic 1-hour follow-up messages for abandoned conversations | | System Notifications | Desktop alerts (via plyer) when human attention is required | | Thread-Safe Persistence | All session state persisted to JSON with locking for concurrent access | | Flexible Product Catalog | Supports 9 product categories with configurable options | | Portuguese (pt-BR) | Native Brazilian Portuguese conversation flow and locale settings |

Technical Highlights

• Clean Architecture with clear separation of concerns: api/ → crews/ → agents/ → integrations/
• Single-process deployment — API server and webhook receiver run on the same Flask instance
• Factory pattern for crew and agent creation, enabling testability and dependency injection
• Pydantic schemas for request/response validation and API contract enforcement
• Daemon threading for background tasks (retry agent, notifications)
• Environment-driven configuration via .env — zero hardcoded secrets

---

🏗 System Architecture

                          ┌──────────────────────────┐
                          │     React Native App      │
                          │  (Companion Dashboard)    │
                          └────────────┬─────────────┘
                                       │ SSE Stream + REST API
                                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                        Flask Server (port 5000)                   │
│                                                                   │
│  ┌─────────────────┐  ┌──────────────────┐  ┌─────────────────┐  │
│  │   /api/v1/*     │  │   /webhook       │  │   /health       │  │
│  │  REST API       │  │  Z-API Callback  │  │  Health Check   │  │
│  │  + SSE Stream   │  │                  │  │                 │  │
│  └────────┬────────┘  └────────┬─────────┘  └─────────────────┘  │
│           │                    │                                   │
└───────────┼────────────────────┼───────────────────────────────────┘
            │                    │
            ▼                    ▼
┌───────────────────────────────────────────────────────────────────┐
│                      CrewAI Multi-Agent System                     │
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │                  AtendimentoCrew (Main Flow)                  │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │ │
│  │  │Orchestr. │  │  Quote   │  │  Sales   │  │  Media   │    │ │
│  │  │  Agent   │─▶│  Agent   │─▶│  Agent   │─▶│  Agent   │    │ │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
│  ┌──────────────────────────┐  ┌───────────────────────────────┐  │
│  │   InterfaceCrew (Status) │  │  NotificacaoCrew (Alerts)     │  │
│  │  ┌─────────┐ ┌────────┐ │  │  ┌──────────┐ ┌──────────┐   │  │
│  │  │  GUI    │ │ Status │ │  │  │  Alert   │ │  Retry   │   │  │
│  │  │  Agent  │ │ Agent  │ │  │  │  Agent   │ │  Agent   │   │  │
│  │  └─────────┘ └────────┘ │  │  └──────────┘ └──────────┘   │  │
│  └──────────────────────────┘  └───────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
            │
            ▼
┌──────────────────────┐    ┌──────────────────────┐
│    ZAPI Client       │    │   SessionManager     │
│  (HTTP → WhatsApp)   │    │  (Thread-Safe JSON)  │
└──────────────────────┘    └──────────────────────┘

Data Flow

1. Z-API pushes incoming WhatsApp messages to /webhook
2. Flask spawns a daemon thread for each message
3. AtendimentoCrew.process_message() routes to the correct step handler via OrchestratorAgent
4. Step handlers use QuoteAgent, SalesAgent, and MediaAgent to process data and send replies
5. MediaAgent calls ZAPIClient to dispatch messages/media through Z-API back to WhatsApp
6. Session state is persisted via SessionManager after every step
7. SSE events are broadcast to connected React Native clients for real-time dashboard updates

---

🔄 Conversation Flow

The bot follows a deterministic 14-step conversation funnel. Each step corresponds to a stage in the customer journey:

Step 0: WELCOME
  │  Sends audio greeting + prompts for name
  ▼
Step 1: COLLECT NAME
  │  Stores customer name + presents 9 product options
  ▼
Step 2: PRODUCT SELECTION
  │  Routes to product-specific step based on customer choice
  ▼
Step 3-6: PRODUCT QUOTING
  │  ┌─ Step 3: Fridge       → Type (1-door/duplex) + Rust detection
  │  ├─ Step 4: Stove        → Burner count (4/5/6)
  │  ├─ Step 5: Washing Mach → Type (front/top loader)
  │  └─ Step 6: Microwave    → Size (small/medium/large)
  ▼
Step 6.5: PROMOTION DECISION
  │  Presents promotional offer → Yes/No
  ▼
Step 6.6: OFFER SELECTION (if accepted)
  │  Two promotional bundles available
  ▼
Steps 7-9: YES/NO SERVICES
  │  ┌─ Step 7:  Window Film → Step 12 (measurement)
  │  ├─ Step 8:  Door Film   → Step 13 (measurement)
  │  └─ Step 9:  Box Sticker → Step 14 (measurement)
  ▼
Steps 10-11: DIRECT SERVICES
  │  ┌─ Step 10: Wallpaper → Media gallery + human alert
  │  └─ Step 11: Furniture → Media gallery + human alert
  ▼
Steps 12-14: MEASUREMENT
  │  Collects size in meters → Media gallery + human alert
  ▼
Step 99: COMPLETED
  │  Human attendant notified; session archived
  ▼
RETORNO_1H: FOLLOW-UP (after 60 min inactivity)
  │  Offers restart/new service/inquiry options

Product Catalog

| Code | Product | |---|---| | 01 | Plotagem Geladeira (Fridge Wrapping) | | 02 | Plotagem Fogão (Stove Wrapping) | | 03 | Plotagem Máquina de Lavar (Washing Machine Wrapping) | | 04 | Plotagem Micro-ondas (Microwave Wrapping) | | 05 | Película Janela (Window Film) | | 06 | Película Porta (Door Film) | | 07 | Adesivo Box (Box Sticker) | | 08 | Papel de Parede (Wallpaper) | | 09 | Plotagem de Móveis (Furniture Wrapping) |

---

🛠 Tech Stack

Backend

| Technology | Version | Purpose | |---|---|---| | Python | 3.12+ | Core language | | Flask | 3.0+ | Web framework (API + webhooks) | | Flask-CORS | 4.0+ | Cross-origin support for mobile app | | CrewAI | 0.80+ | Multi-agent AI orchestration framework | | Pydantic | 2.0+ | Data validation & API schemas | | Requests | 2.31+ | HTTP client for Z-API integration | | python-dotenv | 1.0+ | Environment variable management | | plyer | 2.1+ | System desktop notifications | | python-dateutil | 2.8+ | Date/time parsing utilities |

External Services

| Service | Purpose | |---|---| | Z-API | WhatsApp Business API gateway (message send/receive) | | React Native (companion app) | Mobile dashboard consuming REST API + SSE |

---

📁 Project Structure

Facilit_bot/
│
├── facilit_bot/                     # Main application package
│   │
│   ├── main.py                      # 🚀 Entry point: Flask app factory, startup orchestration
│   ├── config.py                    # ⚙️ Centralized configuration (env vars, media paths, constants)
│   ├── webhook_server.py            # 📥 Z-API webhook receiver (/webhook, /health)
│   │
│   ├── api/                         # 🌐 REST API layer
│   │   ├── __init__.py              #    Module exports
│   │   ├── routes.py                #    All REST endpoints + SSE stream
│   │   ├── schemas.py               #    Pydantic request/response models
│   │   └── middleware.py            #    CORS setup + token authentication decorator
│   │
│   ├── agents/                      # 🤖 Individual AI agents (single-responsibility)
│   │   ├── __init__.py              #    Agent exports
│   │   ├── orchestrator_agent.py    #    Routes messages based on conversation step
│   │   ├── quote_agent.py           #    Collects product-specific data (type, size, etc.)
│   │   ├── sales_agent.py           #    Manages promotions and offer selection
│   │   ├── media_agent.py           #    Sends text/audio/image/video via Z-API
│   │   ├── alert_agent.py           #    System notifications + SSE alerts
│   │   └── retry_agent.py           #    1-hour inactivity follow-up monitor
│   │
│   ├── crews/                       # 👥 CrewAI crew compositions
│   │   ├── __init__.py              #    Crew factory exports
│   │   ├── atendimento_crew.py      #    Main 14-step customer service crew
│   │   ├── interface_crew.py        #    Bot state management + SSE broadcasting
│   │   └── notificacao_crew.py      #    Alert + retry notification crew
│   │
│   ├── integrations/                # 🔌 External service clients
│   │   ├── __init__.py              #    Client exports
│   │   └── zapi_client.py           #    Z-API HTTP client (send text, media)
│   │
│   ├── state/                       # 💾 Session persistence
│   │   ├── __init__.py              #    Module exports
│   │   ├── models.py                #    SessionState dataclass with serialization
│   │   └── session_manager.py       #    Thread-safe JSON file persistence
│   │
│   ├── .env                         # 🔐 Environment variables (secrets — NOT committed)
│   ├── .env.example                 # 📋 Environment template with documentation
│   ├── requirements.txt             # 📦 pip dependency list
│   └── pyproject.toml               # 📦 Poetry project configuration
│
├── midia_facilit/                   # 🎬 Media assets (local only, gitignored)
│   ├── audio_boas_vindas.ogg        #    Welcome audio
│   ├── ploategm_uma_porta.ogg       #    1-door fridge audio
│   ├── plotagem_duplex.ogg          #    Duplex fridge audio
│   ├── tratamento_ferrugem.ogg      #    Rust treatment audio
│   ├── plotagem_fogão.ogg           #    Stove audio
│   ├── plotagem_máquina_lavar.ogg   #    Washing machine audio
│   ├── plotagem_microondas.ogg      #    Microwave audio
│   ├── promocao_*.ogg               #    Promotional audios (5 files)
│   ├── imagem_*.jpeg                #    Service images (5 files)
│   ├── video_facilit*.mp4           #    Demo videos (3 files)
│   ├── logo_facilit.jpg             #    Brand logo
│   └── fonts/                       #    Emoji font assets
│
├── venv/                            # 🐍 Python virtual environment (gitignored)
├── node_modules/                    # 📦 Node dependencies (gitignored)
├── package.json                     # 📦 Node.js config (expo-splash-screen)
├── package-lock.json                # 🔒 Node.js lockfile
├── .vscode/                         # 🖥️ VS Code workspace settings
├── .gitignore                       # 🚫 Git ignore rules
└── README.md                        # 📖 This documentation

---

📋 Prerequisites

Before installing FacilitBot, ensure you have:

| Requirement | Version | Notes | |---|---|---| | Python | 3.12 - 3.13 | Using match statements and modern type hints | | pip | 23+ | For dependency installation | | Z-API Account | — | app.z-api.io — Instance ID + Token required | | Media Files | — | Audio, images, and videos in midia_facilit/ (gitignored) | | Git | 2.x+ | For version control |

Optional

• Poetry (1.8+) — Alternative dependency manager
• React Native App — Companion mobile dashboard (separate repository)
• Ngrok — For exposing local webhook to Z-API during development

---

🚀 Installation

1. Clone the Repository

git clone https://github.com/your-org/facilit_bot.git
cd facilit_bot

2. Set Up Virtual Environment

# Create virtual environment inside facilit_bot/ directory
python -m venv facilit_bot/venv

# Activate (Windows PowerShell)
facilit_bot\venv\Scripts\Activate.ps1

# Activate (Linux/macOS)
source facilit_bot/venv/bin/activate

3. Install Dependencies

# Using pip
pip install -r facilit_bot/requirements.txt

# Or using Poetry
cd facilit_bot
poetry install

4. Configure Environment Variables

# Copy the example file
cp facilit_bot/.env.example facilit_bot/.env

# Edit with your actual values

Fill in the .env file:

# Z-API Credentials (REQUIRED)
ZAPI_INSTANCE_ID=inst-xxxxxxxx
ZAPI_TOKEN=your_zapi_token_here

# Server Settings
FLASK_HOST=0.0.0.0
FLASK_PORT=5000

# Security
BOT_API_TOKEN=facilit-dev-token        # Change in production!
ALLOWED_ORIGINS=*

5. Add Media Files

Place your media assets in the midia_facilit/ directory:

midia_facilit/
├── audio_boas_vindas.ogg
├── ploategm_uma_porta.ogg
├── plotagem_duplex.ogg
├── tratamento_ferrugem.ogg
├── plotagem_fogão.ogg
├── plotagem_máquina_lavar.ogg
├── plotagem_microondas.ogg
├── promocao_uma_porta.ogg
├── promocao_duplex.ogg
├── promocao_fogao.ogg
├── promocao_maquina_lavar.ogg
├── promocao_microondas.ogg
├── imagem_movel.jpeg
├── imagem_facilit_geladeira.jpeg
├── imagem_facilit_geladeira2.jpeg
├── imagem_porta.jpeg
├── video_facilit.mp4
├── video_facilit2.mp4
├── video_facilit3.mp4
├── logo_facilit.jpg
└── fonts/NotoEmoji-VariableFont_wght.ttf

Note: Media files are gitignored. The exact filenames must match those referenced in config.py.

6. Start the Server

cd facilit_bot
python main.py

Expected output:

============================================================
  FACILITBOT - WhatsApp Automation Server
============================================================

  Local IP:   http://192.168.1.100:5000
  Webhook:    http://192.168.1.100:5000/webhook
  API:        http://192.168.1.100:5000/api/v1
  SSE Stream: http://192.168.1.100:5000/api/v1/stream

------------------------------------------------------------
  React Native .env configuration:
    EXPO_PUBLIC_API_URL=http://192.168.1.100:5000/api/v1
    EXPO_PUBLIC_BOT_TOKEN=facilit-dev-token
------------------------------------------------------------

  Press Ctrl+C to stop the server

---

⚙️ Configuration

All configuration is managed through environment variables loaded from .env.

Z-API Settings

| Variable | Default | Description | |---|---|---| | ZAPI_INSTANCE_ID | instancia_id | Your Z-API instance ID from app.z-api.io | | ZAPI_TOKEN | token_id | Your Z-API authentication token |

Server Settings

| Variable | Default | Description | |---|---|---| | FLASK_HOST | 0.0.0.0 | Bind address (0.0.0.0 = all interfaces) | | FLASK_PORT | 5000 | Server port |

Security

| Variable | Default | Description | |---|---|---| | BOT_API_TOKEN | facilit-dev-token | API authentication token for mobile app | | ALLOWED_ORIGINS | * | CORS origins (* = development only, restrict in production) |

File Paths

| Variable | Default | Description | |---|---|---| | SESSIONS_FILE | conversas.json | Path to session persistence file | | MEDIA_DIR | midia_facilit | Directory containing audio/images/videos |

Business Logic

| Variable | Default | Description | |---|---|---| | INACTIVITY_TIMEOUT_MINUTES | 60 | Minutes before 1-hour follow-up (commented out in .env.example, hardcoded in config) |

Product Options

Product options are configured in config.py as a PRODUCT_OPTIONS dictionary. Each product maps a numeric code (string) to a name and conversation step:

PRODUCT_OPTIONS = {
    "01": {"name": "Plotagem Geladeira", "step": 3},
    "02": {"name": "Plotagem Fogão", "step": 4},
    # ... more options
}

Promotional Text

The promotional message (PROMOTIONAL_TEXT) and offer options (OFFER_1, OFFER_2) can be customized in config.py.

---

📖 Usage

Running the Server

cd facilit_bot
python main.py

The server starts with:

• Webhook listener on http://<local-ip>:5000/webhook — Z-API sends incoming messages here
• REST API on http://<local-ip>:5000/api/v1/ — Used by the React Native companion app
• SSE Stream on http://<local-ip>:5000/api/v1/stream — Real-time event push
• Health Check on http://<local-ip>:5000/health

Connecting Z-API Webhook

1. Log into your Z-API Dashboard
2. Go to your instance settings
3. Set the webhook URL to http://<your-server-ip>:5000/webhook
4. Z-API will POST incoming messages as:

{
  "phone": "5511999999999",
  "message": "Olá, quero plotar minha geladeira"
}

React Native App Configuration

Configure your mobile app's .env:

EXPO_PUBLIC_API_URL=http://<server-ip>:5000/api/v1
EXPO_PUBLIC_BOT_TOKEN=facilit-dev-token

Bot Control

The bot starts inactive. Activate it via the API:

# Activate
curl -X POST http://localhost:5000/api/v1/bot/activate \
  -H "X-Bot-Token: facilit-dev-token"

# Deactivate
curl -X POST http://localhost:5000/api/v1/bot/deactivate \
  -H "X-Bot-Token: facilit-dev-token"

# Check status
curl http://localhost:5000/api/v1/status \
  -H "X-Bot-Token: facilit-dev-token"

Restart Command

During conversation, customers can type "reiniciar" to restart their session from Step 1.

---

📡 REST API Reference

Base URL: http://<host>:5000/api/v1

Authentication: All endpoints require the X-Bot-Token header with the value of BOT_API_TOKEN.

Endpoints

| Method | Endpoint | Description | |---|---|---| | GET | /status | Bot status (active, uptime, version) | | POST | /bot/activate | Activate the bot | | POST | /bot/deactivate | Deactivate the bot | | GET | /sessions | List sessions (paginated, filterable) | | GET | /sessions/:number | Get session details | | DELETE | /sessions/:number | Delete a session | | PATCH | /sessions/:number/resolve | Mark session as resolved (step 99) | | GET | /metrics | System metrics (active/completed counts, messages today) | | GET | /stream | SSE real-time event stream |

Detailed Examples

GET /status

curl http://localhost:5000/api/v1/status \
  -H "X-Bot-Token: facilit-dev-token"

Response:

{
  "active": true,
  "uptime_seconds": 4238,
  "version": "1.0.0"
}

GET /sessions

curl "http://localhost:5000/api/v1/sessions?page=1&limit=10&status=active" \
  -H "X-Bot-Token: facilit-dev-token"

Query Parameters: | Parameter | Type | Default | Description | |---|---|---|---| | page | int | 1 | Page number | | limit | int | 20 (max 50) | Items per page | | status | string | all | Filter: active, completed, all |

Response:

{
  "sessions": [
    {
      "number": "5511999999999",
      "name": "João",
      "step": 3,
      "last_contact": "2026-06-30T14:30:00",
      "status": "active"
    }
  ],
  "total": 42,
  "page": 1
}

GET /sessions/:number (Session Detail)

curl http://localhost:5000/api/v1/sessions/5511999999999 \
  -H "X-Bot-Token: facilit-dev-token"

Response:

{
  "number": "5511999999999",
  "name": "João",
  "step": 6.5,
  "last_contact": "2026-06-30T14:30:00",
  "status": "active",
  "geladeira_ok": true,
  "fogao_ok": false,
  "maquina_ok": false,
  "micro_ok": false,
  "retorno_apos_1h": false,
  "tamanho_item": null
}

PATCH /sessions/:number/resolve

curl -X PATCH http://localhost:5000/api/v1/sessions/5511999999999/resolve \
  -H "X-Bot-Token: facilit-dev-token"

Response:

{ "success": true }

DELETE /sessions/:number

curl -X DELETE http://localhost:5000/api/v1/sessions/5511999999999 \
  -H "X-Bot-Token: facilit-dev-token"

Response:

{ "success": true }

GET /metrics

curl http://localhost:5000/api/v1/metrics \
  -H "X-Bot-Token: facilit-dev-token"

Response:

{
  "active_sessions": 15,
  "completed_sessions": 128,
  "last_message_at": "2026-06-30T14:30:00",
  "messages_today": 47
}

Error Responses

All errors follow a consistent format:

{
  "error": "Description of the error"
}

| Status Code | Meaning | |---|---| | 200 | Success | | 401 | Missing or invalid X-Bot-Token | | 404 | Session not found | | 500 | Internal server error |

---

📡 SSE Real-Time Events

The SSE stream at /api/v1/stream pushes real-time events to connected clients (e.g., the React Native companion app). No authentication is required for the SSE connection itself.

Connecting

// React Native / JavaScript
const eventSource = new EventSource('http://<server>:5000/api/v1/stream');

eventSource.addEventListener('bot_status', (e) => {
  const { active } = JSON.parse(e.data);
  console.log('Bot status:', active);
});

eventSource.addEventListener('alert', (e) => {
  const { name, number } = JSON.parse(e.data);
  console.log(`Alert: ${name} (${number}) needs attention!`);
});

Event Types

| Event Name | Payload | Trigger | |---|---|---| | connected | { request_id: string } | Client first connects | | bot_status | { active: bool } | Bot activated/deactivated | | new_message | { number: string, name: string, step: int } | New message processed | | session_update | { number: string, step: int } | Session state changed or deleted | | alert | { name: string, number: string } | Customer requires human attention |

Connection Lifecycle

• Client connects → receives connected event immediately
• Server sends keep-alive comments every 15 seconds
• On disconnect, client queue is automatically cleaned up
• No reconnection logic is built into the server — clients should implement exponential backoff

---

🤖 Multi-Agent System

FacilitBot uses CrewAI to orchestrate 6 specialized agents. Each agent has a distinct role, goal, and backstory defined using CrewAI's agent framework.

Agent Overview

| Agent | Role | Responsibility | |---|---|---| | OrchestratorAgent | Orquestrador de Atendimento | Analyzes session state + incoming message → determines next step | | QuoteAgent | Agente de Cotação | Collects product-specific data (fridge type, stove burners, machine type, microwave size) | | SalesAgent | Agente de Vendas | Presents promotions, handles yes/no decisions, processes offer selection | | MediaAgent | Agente de Mídia | Executes text/audio/image/video sends via Z-API | | AlertAgent | Agente de Alerta | Triggers system notifications + SSE alerts when human attention required | | RetryAgent | Agente de Retorno | Monitors inactivity; sends 1-hour follow-up messages |

Crew Compositions

AtendimentoCrew (Main Flow)

• Process: Sequential
• Agents: Orchestrator → Quote → Sales → Media
• Triggered by: Incoming webhook messages

InterfaceCrew (Status Management)

• Process: Sequential
• Agents: GUIAgent → StatusAgent
• Responsibility: Bot activation/deactivation + SSE broadcasting

NotificacaoCrew (Alerts & Follow-up)

• Process: Sequential
• Agents: AlertAgent → RetryAgent
• Responsibility: Local notifications + inactivity monitoring

Deterministic vs. LLM

While CrewAI agents are defined with roles/goals/backstories (LLM-ready), the current implementation is fully deterministic — all step routing logic is hardcoded in OrchestratorAgent.determine_next_step() and step handlers in AtendimentoCrew. This ensures:

• Predictable behavior without LLM costs
• Fast response times (no API latency)
• Reliable conversation flow that won't hallucinate

Extending with LLM

To enable LLM-powered conversations, add an OpenAI API key and configure the agents' llm parameter:

# In agent create() methods:
Agent(
    role="...",
    goal="...",
    backstory="...",
    llm="gpt-4o-mini",  # Add this line
    verbose=True,
)

---

🔧 Development Guide

Code Organization Principles

1. Single Responsibility: Each agent, crew, and module has exactly one purpose
2. Dependency Injection: SessionManager and config are passed into components rather than imported globally
3. Factory Functions: create_*_crew() functions enable testable component creation
4. Thread Safety: All shared state access goes through SessionManager with locking
5. Documented Modules: Every .py file has a module-level docstring explaining its responsibility

Adding a New Product

1. Add the product entry to PRODUCT_OPTIONS in config.py:

   PRODUCT_OPTIONS = {
       # ... existing ...
       "10": {"name": "Novo Serviço", "step": 15},
   }
   

2. Implement the step handler in atendimento_crew.py's process_message():

   elif current_step == 15:
       self._handle_new_service(phone, message, state)
   

3. Add the route mapping in orchestrator_agent.py's determine_next_step():

   step_map = {
       # ... existing ...
       15: "new_service",
   }
   

4. Add any new media files to config.py and midia_facilit/

Running Tests

# Run tests (when added)
pytest

# Type checking
mypy facilit_bot/

Code Style

• Follow PEP 8
• Use type hints throughout
• Keep functions under 50 lines
• Document public methods with Google-style docstrings
• Use descriptive variable names (avoid abbreviations like msg, prefer message)

Debug Logging

The application uses Python's logging module with DEBUG level by default:

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S"
)

Werkzeug's HTTP logs are suppressed to WARNING level to reduce noise.

---

🩺 Troubleshooting

Common Issues

"Z-API webhook not receiving messages"

1. Verify your ZAPI_INSTANCE_ID and ZAPI_TOKEN in .env
2. Check that Z-API webhook URL points to http://<server-ip>:5000/webhook
3. Ensure the bot is activated (X-Bot-Token API call or via companion app)
4. Verify the server is reachable from the internet (use ngrok for local dev)

"Bot not responding to messages"

• Check bot activation status: GET /api/v1/status
• Verify InterfaceCrew.get_bot_status() returns True
• Check logs for processing errors
• Ensure media files exist in midia_facilit/

"Module not found" errors

• Ensure you're running from the facilit_bot/ directory
• Verify the virtual environment is activated
• Run pip install -r requirements.txt to ensure all deps are installed

"ImportError: cannot import name 'X'"

The code uses sys.path.insert() to add the project root. If import errors persist:

# Install the package in development mode
cd facilit_bot
pip install -e .

"PermissionError: [Errno 13]" writing conversas.json

• Check file permissions on the working directory
• Ensure SESSIONS_FILE path is writable

"locale.Error: unsupported locale setting"

• The application attempts to set pt_BR.UTF-8. If unavailable, it falls back gracefully.
• On Windows, Brazilian Portuguese locale may not be available — this is non-critical.

Log Files

Logs are output to stdout. For persistent logging, redirect:

python main.py > facilit.log 2>&1

---

📄 License

This project is proprietary software. All rights reserved by the Facilit Team.

---

🤝 Contributing

Contributions are welcome! Please follow the development guide and ensure:

1. All new code includes type hints and docstrings
2. Thread safety is maintained for any shared state
3. New API endpoints include Pydantic schemas
4. Configuration is environment-driven (no hardcoded secrets)
5. The conversation flow is documented with step numbers

---

<p align="center"> _{Built with ❤️ by the Facilit_Visual Team} </p>