Sindbad~EG File Manager

# 📱 SMS Management System - Complete Guide

## Overview
Comprehensive SMS management system with support for multiple African SMS gateways, queue management, templates, and analytics.

---

## 🌍 Supported Gateways

### 1. Africa's Talking
- **Countries:** Kenya, Nigeria, Uganda, Tanzania, Rwanda, Malawi
- **Website:** https://africastalking.com
- **Features:** Reliable, affordable, dedicated African service
- **Configuration:**
  - API Key
  - Username (sandbox or production)
  - Sender ID (optional)

### 2. Twilio
- **Countries:** Global (200+ countries)
- **Website:** https://twilio.com
- **Features:** Global reach, excellent delivery rates
- **Configuration:**
  - Account SID
  - Auth Token
  - From Number

### 3. BulkSMS Nigeria
- **Countries:** Nigeria
- **Website:** https://bulksmsnigeria.com
- **Features:** Local Nigerian gateway, competitive pricing
- **Configuration:**
  - API Token
  - Sender ID

### 4. Hubtel
- **Countries:** Ghana
- **Website:** https://hubtel.com
- **Features:** Leading Ghanaian SMS provider
- **Configuration:**
  - Client ID
  - Client Secret
  - Sender ID

### 5. Clickatell
- **Countries:** Global
- **Website:** https://clickatell.com
- **Features:** Enterprise-grade, global coverage
- **Configuration:**
  - API Key

### 6. SMS Portal
- **Countries:** South Africa
- **Website:** https://smsportal.com
- **Features:** South African SMS specialist
- **Configuration:**
  - Client ID
  - Client Secret

### 7. Arkesel
- **Countries:** Ghana
- **Website:** https://sms.arkesel.com
- **Features:** Ghanaian SMS provider with excellent local delivery
- **Configuration:**
  - API Key
  - Sender ID

### 8. Custom Gateway
- **Countries:** Any
- **Features:** Connect to any SMS API
- **Configuration:**
  - API URL
  - API Key (optional)
  - HTTP Method (GET/POST)
  - Custom Headers (JSON)

---

## 📊 Features

### Core Features
✅ **Multiple Gateway Support** - Switch between 7 different gateways  
✅ **SMS Queue** - Queue messages for delayed or batch sending  
✅ **SMS Templates** - Pre-defined message templates with variables  
✅ **SMS Logs** - Complete audit trail of all SMS  
✅ **Test Mode** - Test without actually sending SMS  
✅ **Bulk SMS** - Send to multiple recipients at once  
✅ **Analytics** - Track sent, failed, and delivery rates  

### Admin Features
- Configure SMS gateways
- Manage SMS templates
- View SMS logs and statistics
- Send test messages
- Enable/disable service
- Set test mode

### User Features
- Send individual SMS
- Send bulk SMS
- Use templates
- View sent messages

---

## 🚀 Installation

### Step 1: Run Installer
```
http://localhost/copmadinaarea/install_sms_management.php
```

### Step 2: Database Tables Created
- `sms_settings` - Gateway configuration
- `sms_queue` - Pending SMS queue
- `sms_logs` - SMS history
- `sms_templates` - Message templates

### Step 3: Module Registration
SMS Management automatically added to:
- Dashboard quick access
- Sidebar under "Communication" category
- Module management

---

## ⚙️ Configuration

### Initial Setup

1. **Access SMS Settings**
   ```
   Dashboard → SMS Management → Settings
   ```

2. **Choose Your Gateway**
   - Select from 7 available gateways
   - Click on your preferred gateway

3. **Enter Credentials**
   - Fill in API keys and credentials
   - Set sender ID/name
   - Configure test mode

4. **Enable Service**
   - Check "Enable SMS Service"
   - Keep "Test Mode" ON for testing
   - Set default sender name

5. **Test Configuration**
   - Enter a test phone number
   - Send test SMS
   - Verify delivery

---

## 📝 Using SMS Templates

### Default Templates
1. **Welcome Message** - New member registration
2. **Event Reminder** - Event notifications
3. **Password Reset** - Password reset OTP
4. **2FA Code** - Two-factor authentication
5. **Custom Message** - Blank template

### Template Variables
Templates support dynamic variables:
- `{name}` - Recipient name
- `{church_name}` - Church name
- `{card_number}` - Membership card number
- `{event_name}` - Event name
- `{event_date}` - Event date
- `{event_time}` - Event time
- `{event_location}` - Event location
- `{code}` - OTP or verification code

### Example Template
```
Hi {name}, reminder: {event_name} on {event_date} at {event_time}. 
Location: {event_location}. See you there!
```

---

## 📤 Sending SMS

### Method 1: Via Web Interface
1. Go to SMS Management → Send SMS
2. Enter phone number(s)
3. Select template or write custom message
4. Click Send

### Method 2: Programmatically
```php
require_once 'classes/SMSService.php';

$smsService = new SMSService();

// Send instant SMS
$result = $smsService->sendInstantSMS(
    '+2348012345678',  // Phone number
    'Hello, this is a test message!',  // Message
    'John Doe',  // Recipient name (optional)
    'CHURCH'  // Sender ID (optional)
);

if ($result['success']) {
    echo 'SMS sent successfully!';
} else {
    echo 'Failed: ' . $result['error'];
}
```

### Method 3: Queue SMS
```php
// Queue for later sending
$smsService->queueSMS(
    '+2348012345678',
    'Your message here',
    'John Doe',
    'CHURCH',
    '2025-12-01 10:00:00'  // Scheduled time
);
```

---

## 📞 Phone Number Format

### Important: Always Use International Format

✅ **Correct:**
- `+2348012345678` (Nigeria)
- `+233241234567` (Ghana)
- `+254712345678` (Kenya)
- `+27821234567` (South Africa)

❌ **Incorrect:**
- `08012345678` (Missing country code)
- `2348012345678` (Missing +)
- `+234 801 234 5678` (Contains spaces)

### Country Codes
- Nigeria: +234
- Ghana: +233
- Kenya: +254
- South Africa: +27
- Uganda: +256
- Tanzania: +255

---

## 🔒 Security & Best Practices

### 1. Test Mode
- Always test in test mode first
- Test mode logs SMS without sending
- Disable test mode for production

### 2. Sender ID Guidelines
- Max 11 characters
- Letters and numbers only
- No spaces or special characters
- Must be registered with gateway

### 3. Message Length
- Standard SMS: 160 characters
- Unicode (with emojis): 70 characters
- Long messages split into multiple parts

### 4. Rate Limiting
- Don't send too many SMS at once
- Use queue for bulk sending
- Respect gateway limits

### 5. Credentials Security
- Keep API keys secure
- Don't share credentials
- Use environment variables in production

---

## 📊 Monitoring & Analytics

### Dashboard Statistics
- Total SMS sent
- Successful deliveries
- Failed messages
- Today's messages

### SMS Logs
View detailed logs including:
- Recipient details
- Message content
- Gateway used
- Delivery status
- Timestamps
- Error messages

### Queue Status
Monitor queued messages:
- Pending
- Sent
- Failed
- Scheduled

---

## 🔧 Troubleshooting

### SMS Not Sending

**Problem:** SMS service disabled  
**Solution:** Enable SMS service in settings

**Problem:** Invalid credentials  
**Solution:** Verify API keys and credentials

**Problem:** Invalid phone number  
**Solution:** Use international format (+234...)

**Problem:** Gateway error  
**Solution:** Check gateway status, try different gateway

**Problem:** Test mode enabled  
**Solution:** Disable test mode for real sending

### Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| Invalid API Key | Wrong credentials | Verify API key from gateway |
| Invalid phone number | Wrong format | Use +234... format |
| Insufficient balance | No gateway credit | Top up gateway account |
| Sender ID not registered | Unregistered sender | Register sender ID with gateway |
| Rate limit exceeded | Too many requests | Reduce sending rate |

---

## 💰 Cost Management

### Pay As You Go
Most gateways charge per SMS:
- Nigeria: ₦2 - ₦10 per SMS
- Ghana: GH₵ 0.05 - GH₵ 0.15 per SMS
- Kenya: KES 1 - KES 3 per SMS
- South Africa: R 0.20 - R 0.50 per SMS

### Cost Optimization Tips
1. Use concise messages
2. Batch similar messages
3. Use templates
4. Monitor failed SMS
5. Compare gateway rates
6. Use test mode for development

---

## 🔗 Integration Examples

### Member Registration
```php
// Send welcome SMS on member registration
$smsService = new SMSService();
$message = "Welcome to {church_name}, {name}! Your membership card is {card_number}.";

$smsService->sendInstantSMS(
    $memberPhone,
    $message,
    $memberName
);
```

### Event Reminders
```php
// Send event reminder
$template = "Hi {name}, reminder: {event_name} on {event_date} at {event_time}.";

foreach ($attendees as $attendee) {
    $message = str_replace(
        ['{name}', '{event_name}', '{event_date}', '{event_time}'],
        [$attendee['name'], $event['name'], $event['date'], $event['time']],
        $template
    );
    
    $smsService->queueSMS(
        $attendee['phone'],
        $message,
        $attendee['name']
    );
}
```

### Password Reset OTP
```php
// Send password reset OTP
$code = rand(100000, 999999);
$message = "Your password reset code is: {$code}. Valid for 15 minutes.";

$smsService->sendInstantSMS(
    $userPhone,
    $message,
    $userName
);
```

---

## 📱 Mobile App Integration

SMS service can be integrated with mobile apps via API endpoints.

### Send SMS API
```
POST /api/sms/send
Headers: Authorization: Bearer {token}
Body: {
    "phone": "+2348012345678",
    "message": "Your message here"
}
```

---

## 🆘 Support

### Documentation
- SMS Management Guide (this file)
- Gateway documentation links in settings
- Built-in help tooltips

### Getting Help
1. Check this guide first
2. Review gateway documentation
3. Test with test mode enabled
4. Check SMS logs for errors
5. Contact gateway support

---

## 📋 Checklist

### Before Going Live
- [ ] Gateway credentials configured
- [ ] Test SMS sent successfully
- [ ] Test mode disabled
- [ ] Sender ID registered (if required)
- [ ] Gateway account has sufficient balance
- [ ] Phone numbers in correct format
- [ ] Templates customized
- [ ] Team trained on system

### Regular Maintenance
- [ ] Monitor SMS logs weekly
- [ ] Check gateway balance
- [ ] Review failed messages
- [ ] Update templates as needed
- [ ] Test SMS monthly
- [ ] Review costs and optimize

---

## 🎉 Quick Start Summary

1. **Install**: Run `install_sms_management.php`
2. **Configure**: Go to SMS Settings
3. **Choose Gateway**: Select your preferred gateway
4. **Add Credentials**: Enter API keys
5. **Test**: Send test SMS with test mode ON
6. **Go Live**: Disable test mode
7. **Send**: Start sending SMS!

---

## 📞 Gateway Contact Information

- **Africa's Talking**: support@africastalking.com
- **Twilio**: https://support.twilio.com
- **BulkSMS Nigeria**: support@bulksmsnigeria.com
- **Hubtel**: support@hubtel.com
- **Clickatell**: support@clickatell.com
- **SMS Portal**: support@smsportal.com

---

**System Ready!** Start sending SMS to your church members! 🚀📱