# Sinch SMS Configuration

## Configuration Complete ✅

Sinch SMS has been successfully configured with your credentials.

### Credentials Added

- **Project ID (Service Plan)**: `52c2fb52-256c-4b72-8822-9aa37fffcf00`
- **Access ID**: `992a86b3-2e9a-40f6-ab4b-4313ff024297`
- **Key Secret (API Token)**: `aNpffoUdGAfR_l-QLoarYYNyXU`
- **From Number**: Not configured (using Sinch shared pool)

### Configuration Files Updated

1. **[api/config/sinch.php](api/config/sinch.php)** - Credentials configured
2. **[includes/SinchSMS.php](includes/SinchSMS.php)** - SMS sending logic updated

### How SMS Sending Works Now

**Phone Authentication Flow:**
1. User enters phone number on login screen
2. Backend generates 6-digit verification code
3. Code is saved to `verification_codes` table in database
4. Sinch SMS API is called to send SMS
5. User receives SMS on their phone
6. User enters code and logs in

### Testing SMS Delivery

**Test with a real phone number:**

1. Go to `https://localhost` or `http://localhost`
2. Enter a valid US phone number:
   - Format: `(555) 123-4567` or `5551234567` or `+15551234567`
   - Use your actual mobile number for testing
3. Click "Send Code"
4. Check your phone for SMS message
5. SMS will say: *"Your Fellowship Housing verification code is: 123456. This code expires in 10 minutes."*
6. Enter the code and click "Login"

### Phone Number Format

The app accepts phone numbers in multiple formats:
- `1234567890` → Converted to `+11234567890`
- `(123) 456-7890` → Converted to `+11234567890`
- `+1-123-456-7890` → Converted to `+11234567890`
- `+15551234567` → Used as-is

All phone numbers are sanitized and formatted before sending to Sinch.

### Checking SMS Logs

**Success logs:**
```bash
# Check PHP error log for successful sends
tail -f /tmp/php_errors.log | grep "Sinch SMS"
```

You should see:
```
Sinch SMS sent successfully to +15551234567
```

**Error logs:**
If SMS fails to send, you'll see:
```
Sinch SMS Error: HTTP 401 - Response: {"error":"unauthorized"}
```

Common HTTP error codes:
- `401` - Authentication failed (check API token)
- `400` - Bad request (check phone number format)
- `402` - Insufficient credits
- `403` - Forbidden (check project permissions)
- `500` - Sinch server error

### Sinch Dashboard Access

To monitor SMS delivery and check credits:

**Dashboard URL**: https://dashboard.sinch.com/
**Login Email**: developers+fhc@projectworldimpact.com
**Password**: HklLW1dBzlctxZ%k

In the dashboard you can:
- View SMS delivery status
- Check remaining credits
- View usage reports
- Configure from number (optional)
- Monitor API calls

### Optional: Configure Dedicated From Number

If you want to use a dedicated phone number instead of Sinch's shared pool:

1. Login to Sinch dashboard
2. Purchase or configure a phone number
3. Update [api/config/sinch.php](api/config/sinch.php):
   ```php
   define('SINCH_FROM_NUMBER', '+15551234567'); // Your Sinch number
   ```

**Benefits of dedicated number:**
- Branded sender identity
- Better deliverability in some regions
- Users can reply to SMS

**Shared pool (current setup):**
- No additional cost
- Works immediately
- Shows a generic Sinch number
- Sufficient for verification codes

### Rate Limits

The app has built-in rate limiting:
- **Max 3 verification codes** per phone number per hour
- Prevents abuse and reduces SMS costs
- Configurable in [api/config/constants.php](api/config/constants.php)

### SMS Cost Estimation

Typical costs (varies by region):
- **US/Canada**: ~$0.0075 per SMS
- **International**: Varies by country

Monitor usage in Sinch dashboard to track costs.

### Troubleshooting

**Problem: SMS not received**

1. Check phone number format:
   ```sql
   SELECT * FROM verification_codes ORDER BY created_at DESC LIMIT 5;
   ```
   Verify phone column has correct format: `+1XXXXXXXXXX`

2. Check PHP error log:
   ```bash
   tail -f /tmp/php_errors.log
   ```
   Look for Sinch API errors

3. Verify credentials are correct:
   ```bash
   curl -X POST "https://us.sms.api.sinch.com/xms/v1/52c2fb52-256c-4b72-8822-9aa37fffcf00/batches" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer aNpffoUdGAfR_l-QLoarYYNyXU" \
     -d '{"to":["+15551234567"],"body":"Test message"}'
   ```

4. Check Sinch dashboard for:
   - Account status (active/suspended)
   - Remaining credits
   - API call logs

**Problem: HTTP 401 Unauthorized**

This means the API token is incorrect. Verify:
1. Key Secret is exactly: `aNpffoUdGAfR_l-QLoarYYNyXU`
2. No extra spaces or characters
3. Project ID matches: `52c2fb52-256c-4b72-8822-9aa37fffcf00`

**Problem: HTTP 402 Payment Required**

Your Sinch account needs credits:
1. Login to Sinch dashboard
2. Go to Billing section
3. Add credits to account

### Fallback to Email

If SMS is not working or too expensive, users can still authenticate via email:
1. User enters email address instead of phone
2. Verification code sent via email
3. Same login flow

Email requires SMTP configuration - see [TESTING_GUIDE.md](TESTING_GUIDE.md) for details.

### Next Steps

1. **Test SMS delivery** with your own phone number
2. **Monitor Sinch dashboard** for delivery status
3. **Check PHP error logs** for any API errors
4. **Consider dedicated number** if you want branded SMS

The SMS service is now fully functional and ready for testing!