ronnyouma/Bulk-sms-system

A Flask-based bulk SMS dashboard for Kenyan constituency offices — manage contacts, send campaigns to 10,000+ recipients across Safaricom, Airtel & Telkom, and track delivery via Africa's Talking API. # Constituency SMS Web Application A full-stack bulk SMS dashboard for constituency offices that need to send messages to members efficiently instead of texting people one by one. The system includes a contacts database, campaign management, delivery tracking, and Africa's Talking API integration. Built with Flask, Python, JavaScript, and SQLite locally, with PostgreSQL support for production. --- ## Project structure ```text sms_webapp/ |-- app.py # Flask backend + REST API |-- requirements.txt # Python dependencies |-- README.md |-- static/ |-- index.html # Full single-page frontend ``` The app uses SQLite locally by default. In production, set `DATABASE_URL` and it will use PostgreSQL automatically. --- ## Setup ### 1. Install dependencies ```bash pip install -r requirements.txt ``` ### 2. Set your credentials Option A - edit `app.py` directly: ```python AT_USERNAME = "your_username" AT_API_KEY = "your_api_key_here" SENDER_ID = "MP-NAIVASHA" SANDBOX = True SMS_COST_PER_SEGMENT = 0.80 MPESA_PAYBILL = "525900" MPESA_ACCOUNT = "your_africastalking_username" ``` Option B - use environment variables, recommended for production: ```bash export AT_USERNAME="your_username" export AT_API_KEY="your_api_key_here" export SENDER_ID="MP-NAIVASHA" export AT_SANDBOX="false" export SMS_COST_PER_SEGMENT="0.80" export MPESA_PAYBILL="525900" export MPESA_ACCOUNT="your_africastalking_username" ``` For Render, use the included `render.yaml` blueprint. It creates a free web service and a free PostgreSQL database, then passes the database connection string through `DATABASE_URL`. ### 3. Run ```bash python app.py ``` Open `localhost` in your browser. --- ## Features ### Contacts - Add contacts one by one via form - Import thousands from CSV with `phone_number`, `name`, `ward`, and `group` columns - Search, filter by ward or group - Opt-out management, with opted-out contacts excluded from campaigns - Automatic phone number normalis …