
- Set up FastAPI application structure - Implement SQLite database with SQLAlchemy - Create WhatsApp webhook endpoints - Implement message storage and analysis - Integrate Gemini 2.5 Pro for message analysis - Add email delivery of insights - Configure APScheduler for weekend analysis - Add linting with Ruff
WhatsApp Message Analytics Service
A FastAPI application that receives webhooks from WhatsApp Business API, stores messages in a SQLite database, and provides insights using Gemini 2.5 Pro LLM.
Features
- Webhook integration with WhatsApp Business API
- Message storage in SQLite database
- Weekly message analysis using Gemini 2.5 Pro LLM
- Email delivery of insights
- RESTful API for accessing messages
Tech Stack
- Framework: FastAPI
- Database: SQLite with SQLAlchemy ORM
- Migrations: Alembic
- AI Integration: Google Gemini 2.5 Pro
- Task Scheduling: APScheduler
- Email: SMTP with HTML templates
Setup and Installation
Prerequisites
- Python 3.9+
- Access to WhatsApp Business API
- Google AI Gemini API key
- SMTP server for sending emails
Installation
-
Clone the repository:
git clone https://github.com/yourusername/whatsapp-message-analytics-service.git cd whatsapp-message-analytics-service
-
Create a virtual environment and activate it:
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install dependencies:
pip install -r requirements.txt
-
Create a
.env
file in the project root with the following content:# WhatsApp API configuration WHATSAPP_VERIFY_TOKEN=your_verify_token # Email configuration SMTP_TLS=True SMTP_PORT=587 SMTP_HOST=smtp.gmail.com SMTP_USER=your_email@gmail.com SMTP_PASSWORD=your_app_password EMAILS_FROM_EMAIL=your_email@gmail.com EMAILS_FROM_NAME=WhatsApp Message Analytics EMAIL_RECIPIENTS=["recipient1@example.com", "recipient2@example.com"] # Gemini API configuration GEMINI_API_KEY=your_gemini_api_key # CORS configuration (optional) BACKEND_CORS_ORIGINS=["http://localhost", "http://localhost:8080"]
-
Initialize the database:
alembic upgrade head
Running the Application
Start the application with Uvicorn:
uvicorn main:app --reload
The API will be available at http://localhost:8000, and the documentation at http://localhost:8000/docs.
WhatsApp Webhook Setup
-
In your WhatsApp Business API dashboard, set up a webhook with the following URL:
https://your-domain.com/api/v1/webhooks/whatsapp
-
Set the Verify Token to match the
WHATSAPP_VERIFY_TOKEN
in your.env
file. -
Subscribe to the relevant webhook events (typically
messages
).
API Endpoints
GET /health
: Health check endpointGET /api/v1/webhooks/whatsapp
: Webhook verification endpoint for WhatsAppPOST /api/v1/webhooks/whatsapp
: Webhook endpoint for receiving WhatsApp messagesGET /api/v1/messages/
: Get all messages with paginationGET /api/v1/messages/{message_id}
: Get a specific message by ID
Message Analysis
The service is configured to run message analysis every Sunday at 6:00 AM by default. This can be configured through the following environment variables:
ANALYSIS_CRON_DAY_OF_WEEK
: Day of the week to run analysis (default: "sun")ANALYSIS_CRON_HOUR
: Hour to run analysis (default: 6)ANALYSIS_CRON_MINUTE
: Minute to run analysis (default: 0)
Development
Database Migrations
Create a new migration:
alembic revision --autogenerate -m "Description of changes"
Apply migrations:
alembic upgrade head
Code Linting
Lint code with Ruff:
ruff check .
Fix linting issues:
ruff check --fix .