📱 Twilio SMS Tracker

Open-Source SMS Communication Management System

Track SMS delivery • Monitor performance • Manage customer communications

Live Demo • Documentation • Quick Start

🎥 Demo Video

Watch our comprehensive walkthrough demonstrating all features and setup process. Click the button above to play the video.

Note: To see the video embedded directly in this README, you can edit this file on GitHub and drag-drop the demo-video.mp4 file where you want it to appear. GitHub will automatically create an embedded player.

📸 Screenshots

Dashboard - Real-time SMS Metrics

Monitor delivery rates, track failed messages, and manage SMS campaigns from a centralized dashboard

Message Configuration

Customize SMS templates with dynamic variables and preview messages before sending

Analytics Dashboard

Track performance metrics, daily trends, and top-performing dealerships

Webhook Settings

Professional webhook documentation with live testing capabilities

Mobile Responsive Design

Fully responsive interface optimized for mobile devices

✨ Key Features

📊 Real-time Dashboard

• Live SMS delivery metrics
• Status tracking (delivered, failed, pending)
• Quick actions toolbar
• Export to CSV functionality
• Multiple view modes (Table/Card/List)

📝 Message Configuration

• Customizable SMS templates
• Dynamic variable support
• Real-time preview
• Review platform integration
• Character count validation

📈 Analytics & Reporting

• Performance metrics
• Daily activity charts
• Success/failure rates
• Top dealerships ranking
• Hourly distribution analysis

🔌 Webhook Integration

• RESTful API endpoints
• Secure authentication
• Request/response logging
• Live testing tools
• Professional documentation

🚀 Quick Start

Get up and running in under 5 minutes!

Option 1: One-Click Deploy (Recommended)

Option 2: Manual Setup

# Clone the repository
git clone https://github.com/rashidazarang/twilio-sms-tracker.git
cd twilio-sms-tracker

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# Run database migrations
npm run db:migrate

# Start development server
npm run dev

# Visit http://localhost:3000

🔧 Configuration

Environment Variables

Create a .env file with the following variables:

# Database (PostgreSQL) - Required
DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require

# Twilio - Optional (Required for SMS)
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_PHONE_NUMBER=+1234567890

# Security - Required
WEBHOOK_API_KEY=your-secure-api-key-here

# Application - Required
FEEDBACK_BASE_URL=https://your-domain.vercel.app
NODE_ENV=production

Database Setup

Using Neon (Recommended - Free Tier Available)

1. Sign up at neon.tech
2. Create a new project
3. Copy connection string
4. Run migrations in SQL editor

Using PostgreSQL

-- Run the migration script
psql -d your_database -f database/migrations/001_initial_schema.sql

📚 Documentation

API Reference

Webhook Endpoint

POST /webhook/transaction-complete
Content-Type: application/json
x-api-key: your-api-key

{
  "transactionId": "TXN-123456",
  "customerPhone": "+14155551234",
  "customerName": "John Doe",
  "dealershipName": "ABC Motors",
  "amount": 299.99
}

Dashboard API

GET /api/dashboard?page=1&limit=20

Retry Failed Messages

POST /api/retry/bulk
x-api-key: your-api-key

Project Structure

twilio-sms-tracker/
├── 📁 api/              # API endpoints & serverless functions
├── 📁 public/           # Frontend HTML files
│   ├── index.html       # Dashboard
│   ├── messages.html    # Message configuration
│   ├── analytics.html   # Analytics dashboard
│   └── settings.html    # Webhook settings
├── 📁 database/         # Database migrations
├── 📁 src/              # Source code
│   ├── services/        # Business logic
│   └── utils/           # Utilities
├── 📄 .env.example      # Environment template
├── 📄 vercel.json       # Deployment config
└── 📄 package.json      # Dependencies

🛠️ Technology Stack

| Frontend | Backend | Database | Deployment | |----------|---------|----------|------------| | | | | | | | | | | | | | | | | | | | |

🤝 Contributing

We love contributions! Please see our Contributing Guide for details.

How to Contribute

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Setup

# Install dependencies
npm install

# Run tests
npm test

# Run linter
npm run lint

# Build for production
npm run build

📈 Roadmap

• [x] Core dashboard functionality
• [x] Webhook integration
• [x] Message templates
• [x] Analytics dashboard
• [ ] Multi-user support
• [ ] Scheduled messaging
• [ ] A/B testing for templates
• [ ] Advanced reporting
• [ ] Email notifications
• [ ] Slack integration

💡 Use Cases

• 🚗 Automotive Dealerships - Track service follow-ups and customer satisfaction
• 🏥 Healthcare Providers - Appointment reminders and patient feedback
• 🏢 Service Businesses - Customer communication and review collection
• 🛍️ E-commerce - Order updates and delivery notifications
• 🏫 Educational Institutions - Student notifications and parent communications

🔒 Security

• API key authentication
• Environment variable protection
• SQL injection prevention
• XSS protection
• Rate limiting support
• Audit logging

📊 Performance

• Response Time: < 500ms API responses
• Throughput: 10,000+ messages/day
• Uptime: 99.9% availability target
• Scalability: Horizontal scaling ready

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Vercel serverless functions
• Database hosting by Neon
• SMS delivery by Twilio
• Icons from Heroicons

📞 Support

| Type | Link | |------|------| | 💬 Discussions | GitHub Discussions | | 🐛 Bug Reports | GitHub Issues | | 📧 Email | [email protected] | | 📖 Docs | Documentation |

Built with ❤️ for the business community

⭐ Star us on GitHub — it helps!

Website • Blog • Twitter