WhatsApp Message Queue API

A production-ready, highly scalable RESTful API for managing WhatsApp Business message workflows. Built with Flask and PostgreSQL, this system is designed to handle webhook events, message processing, and analytics for customer communication platforms.

🎯 Overview

This API serves as the backend infrastructure for WhatsApp Business integrations, enabling businesses to receive, process, track, and analyze customer messages at scale. It was developed to solve real-world problems involving high-volume message processing for a WhatsApp Business automation platform.

Built during my Software Development Internship at Yashas AI, a company specializing in WhatsApp Business API automation and AI chatbots.

Business Problem Solved

When businesses use the WhatsApp Business API, they require a robust system to:

• Receive incoming messages reliably via webhooks.
• Persist messages securely and track their lifecycle (pending/processed/failed).
• Filter and search through vast amounts of conversation history.
• Perform batch operations to process or fail multiple messages instantly.
• Monitor team performance, message volume, and peak operational hours.

🚀 Features

• Enterprise Database: Backed by PostgreSQL using SQLAlchemy ORM for reliable data persistence and ACID compliance.
• Message Lifecycle Management: Strict state machine logic ensuring messages transition correctly between pending, processed, and failed states.
• Bulk Processing Engine: "Selective" and "Blanket" modes to process or fail thousands of messages with a single HTTP request.
• Real-time Analytics: Aggregates queue health, unique sender metrics, and busiest hour calculations natively via PostgreSQL functions.
• Strict Validation Layer: Built-in safeguards ensuring correct Indian phone number formats and payload integrity.
• Modular Architecture: Clean separation of concerns across Routes, Services, Models, and Utilities for maximum maintainability.
• Secure Configuration: Environment variables (.env) protect sensitive database credentials.

🛠️ Tech Stack

• Framework: Flask (Python 3.9+)
• Database: PostgreSQL
• ORM: SQLAlchemy
• Environment Management: python-dotenv
• Testing: Automated testing via pytest and pytest-flask
• CI/CD: Automated deployment via Render, Continuous Integration via GitHub Actions
• Containerization: Docker & Docker Compose

📁 Architecture

The codebase follows a professional modular structure:

whatsapp-message-queue-api/
│
├── .github/
│   └── workflows/
│       └── ci.yml             # GitHub Actions CI/CD Pipeline
│
├── app.py                     # Application Factory & Database Initialization
├── run.py                     # Server Entry Point
├── config.py                  # Environment & Configuration Variables
├── .env                       # Secret Database Credentials (Git Ignored)
├── .gitignore                 # Excludes Python cache and environments from Git
├── requirements.txt           # Python Dependencies
├── Dockerfile                 # Container Blueprint for the API
├── docker-compose.yml         # Container Orchestration (API + PostgreSQL)
├── .dockerignore              # Excludes unnecessary files from the container
│
├── models/
│   └── message_model.py       # SQLAlchemy Models & Schema Definitions
├── routes/
│   └── message_routes.py      # HTTP Endpoint Definitions
├── services/
│   └── message_service.py     # Core Business Logic & Database Transactions
├── tests/
│   ├── conftest.py            # Pytest Configuration & Fake Database
│   └── test_app.py            # Automated Gatekeeper Test Suite
└── utils/
    ├── helpers.py             # Reusable Helper Functions
    └── validators.py          # Strict Payload Validation Logic

---

🔧 Installation & Setup

🐳 Quick Start (Using Docker - Recommended)

The fastest way to run this API is using Docker. You do not need to install Python or PostgreSQL on your machine.

1. Clone the repository

git clone https://github.com/yourusername/whatsapp-message-queue-api.git
cd whatsapp-message-queue-api

2. Run the application

docker-compose up --build

The API will start at http://localhost:5000 and a PostgreSQL database will be automatically provisioned.

---

💻 Manual Setup (Without Docker)

Prerequisites

• Python 3.9 or higher
• PostgreSQL installed and running locally
• Git

1. Clone the repository

git clone https://github.com/yourusername/whatsapp-message-queue-api.git
cd whatsapp-message-queue-api

2. Environment Setup

Create a .env file in the root directory to store your PostgreSQL credentials:

touch .env

Inside the .env file, add your database connection string:

DATABASE_URI="postgresql://username:password@localhost/whatsapp_queue"

3. Install dependencies

pip install -r requirements.txt

4. Run the server

python run.py

The API will start locally at http://localhost:5000

---

📋 API Endpoints

Message Ingestion

Method	Endpoint	Description
POST	/api/messages	Ingest a new incoming message (Webhook target)

Retrieval & Search

Method	Endpoint	Description
GET	/api/messages	Retrieve all messages (Supports ?status= and ?phone= filters)
GET	/api/messages/<id>	Fetch a specific message by its ID
GET	/api/messages/search?query=	Full-text substring search across all messages

Lifecycle Management

Method	Endpoint	Description
PATCH	/api/messages/<id>/process	Mark a specific message as processed
PATCH	/api/messages/<id>/fail	Mark a specific message as failed
DELETE	/api/messages/delete/<id>	Permanently remove a message from the database

Bulk Operations

Method	Endpoint	Description
PATCH	/api/messages/bulk-process	Process multiple messages (Send message_ids array, or leave blank to process all)
PATCH	/api/messages/bulk-fail	Fail multiple messages (Send message_ids array, or leave blank to fail all)

Analytics

Method	Endpoint	Description
GET	/api/messages/stats	Retrieve queue metrics, sender counts, and peak hours

---

📊 Error Handling

The API returns descriptive JSON errors with standardized HTTP status codes:

• 400 Bad Request: Validation failures (e.g., "Phone number must be 10 digits").
• 404 Not Found: Resource does not exist.
• 415 Unsupported Media Type: Invalid Content-Type headers.
• 500 Internal Server Error: Unexpected database transaction failures (triggers automatic rollback).

---

👨‍💻 About This Project

Key Learnings & Implementations

• Database Migrations: Transitioning from an in-memory SQLite prototype to a production PostgreSQL database.
• Separation of Concerns: Abstracting business logic away from the routing layer into dedicated service modules.
• Continuous Integration: Implemented a robust automated testing pipeline using pytest and GitHub Actions to act as a gatekeeper against regression bugs.
• UTC Time Standardization: Implementing professional timezone architecture by storing raw UTC numbers in the database and calculating local offsets (IST) only at the serialization layer.
• Transaction Safety: Enforcing db.session.commit() and db.session.rollback() to prevent database corruption during failed requests.

🚀 System Scaling Considerations

(If this MVP were to be scaled to a massive production level, these are the architectural improvements I would implement next)

• Caching Layer: Redis caching for the /stats endpoint to reduce database load during high-traffic periods.
• Throttling: Rate limiting (e.g., 100 messages per hour per sender) using Flask-Limiter to prevent spam.
• Intelligent Routing: Priority assignment based on NLP sentiment analysis of the message content.

---

🤝 Contributing

This is a professional portfolio project, but suggestions are always welcome! Feel free to:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

📄 License

MIT License - feel free to use for learning purposes.

---

🔗 Connect With Me

Author: Riya Chaleria
LinkedIn: Riya Chaleria
Email: riyachaleria@gmail.com

Built with ❤️ during my Software Development Internship at Yashas AI