AI Payment Reminder Call System

Automated payment reminder calls for insurance agencies V1 Production System

Overview

The AI Payment Reminder Call System automatically calls insurance members who have missed a premium payment, delivers a professional reminder, captures payment commitments or follow-up needs, and documents outcomes for agency staff.

This system replaces repetitive outbound reminder calls, allowing staff to focus on complex cases while improving payment recovery and reducing policy lapses.

What This System Does (V1)

Automated outbound calls for overdue payments
Natural-sounding AI voice reminder
Payment commitment capture (date + amount)
Human transfer on request or confusion
Call logging, recordings, and transcripts
Simple campaign dashboard
CSV upload or single data source import
TCPA-safe calling hours & DNC checks

What''s NOT in V1

Live payment processing
Credit card collection
Advanced sentiment analysis
Predictive ML models
Multi-channel orchestration
White-label branding
Deep CRM bidirectional sync

(These are Phase 2+ features)

---

Tech Stack

Backend

• Python 3.11 + FastAPI
• PostgreSQL (primary database)
• Redis (call queue)
• SQLAlchemy 2.0 (async ORM)
• Alembic (migrations)

Frontend

• Next.js 14 + React 18
• TypeScript
• Tailwind CSS
• React Query (data fetching)

Voice AI

• Bland.ai or Vapi.ai (managed voice stack)

Notifications

• Twilio (SMS confirmations)
• SendGrid (email confirmations)

---

Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 20+ (for local frontend development)
• Python 3.11+ (for local backend development)
• Bland.ai or Vapi.ai API key
• Twilio account (for SMS)
• SendGrid account (for email)

1. Clone the Repository

git clone https://github.com/jesusr04/follow_up.git
cd follow_up

2. Set Up Environment Variables

Backend:

cd backend
cp .env.example .env
# Edit .env with your API keys

Frontend:

cd frontend
cp .env.example .env

3. Start with Docker Compose

docker-compose up --build

This will start:

• PostgreSQL (port 5432)
• Redis (port 6379)
• Backend API (port 8000)
• Frontend (port 3000)

4. Access the Application

• Frontend Dashboard: http://localhost:3000
• Backend API Docs: http://localhost:8000/api/docs
• Health Check: http://localhost:8000/health

---

Project Structure

follow_up/
 backend/              # FastAPI backend
    app/
       api/         # API endpoints
       core/        # Configuration
       db/          # Database setup
       models/      # SQLAlchemy models
       schemas/     # Pydantic schemas
       services/    # Business logic
    requirements.txt
    Dockerfile
    .env.example

 frontend/            # Next.js frontend
    app/            # App router pages
    lib/            # API client
    package.json
    Dockerfile
    .env.example

 docs/               # Documentation
    CSV_UPLOAD_GUIDE.md
    VOICE_AI_GUIDE.md
    example_members.csv

 docker-compose.yml
 README.md

---

Usage Guide

1. Upload Members

1. Go to Dashboard Upload Members
2. Upload a CSV with these columns:

   first_name, last_name, phone_number, email, timezone, 
   policy_number, policy_type, amount_due, due_date
   

3. Review imported members

2. Create a Campaign

1. Go to Campaigns New Campaign
2. Enter campaign name and description
3. Select members to call
4. Click Create Campaign

3. Start Calling

1. Open the campaign
2. Review member list
3. Click Start Campaign
4. Monitor dashboard for real-time metrics

4. Review Call Results

1. Go to Calls tab
2. View call details:
   • Outcome
   • Duration
   • Recording
   • Transcript
   • Commitment details

---

API Documentation

Full API documentation available at: http://localhost:8000/api/docs

Main Endpoints

Members

• GET /api/v1/members/ - List all members
• POST /api/v1/members/ - Create a member
• POST /api/v1/members/upload-csv - Upload CSV

Campaigns

• GET /api/v1/campaigns/ - List campaigns
• POST /api/v1/campaigns/ - Create campaign
• POST /api/v1/campaigns/{id}/start - Start campaign

Calls

• GET /api/v1/calls/ - List calls
• GET /api/v1/calls/{id} - Get call details

Dashboard

• GET /api/v1/dashboard/metrics - Get dashboard metrics

---

Configuration

Key Environment Variables

Backend (.env):

DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/payment_reminders
REDIS_URL=redis://localhost:6379/0
VOICE_AI_PROVIDER=bland
BLAND_API_KEY=your_key
TWILIO_ACCOUNT_SID=your_sid
TWILIO_AUTH_TOKEN=your_token
SENDGRID_API_KEY=your_key
CALLING_HOURS_START=8
CALLING_HOURS_END=21

Frontend (.env):

NEXT_PUBLIC_API_URL=http://localhost:8000

---

Compliance

TCPA Compliance

Calls only during allowed hours (8am-9pm local time)
DNC list enforcement before every call
Clear automated disclosure at call start
Call recording disclosure
Consent tracking per member

Data Privacy

No storage of payment card data
Secure database storage
Encrypted environment variables

---

Development

Backend Development

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend Development

cd frontend
npm install
npm run dev

Run Tests

cd backend
pytest

---

Deployment

Docker Compose (Production)

docker-compose -f docker-compose.prod.yml up -d

Railway / Heroku

1. Connect GitHub repo
2. Add PostgreSQL and Redis
3. Set environment variables
4. Deploy

---

Roadmap

Phase 2

• Live payment processing
• Advanced sentiment analysis
• Multi-channel orchestration
• White-label branding

Phase 3

• Predictive ML models
• Deep CRM integrations
• Multi-language support

---

Documentation

• CSV Upload Guide
• Voice AI Configuration

---

Support

• GitHub Issues: https://github.com/jesusr04/follow_up/issues
• Email: support@yourcompany.com

---

License

MIT License

---

Built for insurance agencies to automate payment reminders and reduce policy lapses.