# SMS Service Setup Guide

## Current Status

The SMS service is currently **simulated** (not sending real SMS). It will log messages to the console instead of sending actual SMS until you configure the credentials.

## SMS Provider: Text.lk

The system uses **Text.lk** API for sending SMS in Sri Lanka. This is a popular SMS gateway service in Sri Lanka.

## Step 1: Get Text.lk API Credentials

### Option A: Sign up for Text.lk

1. **Visit Text.lk website**: https://www.text.lk/
2. **Create an account** or log in if you already have one
3. **Navigate to API section** in your dashboard
4. **Get your credentials**:
   - Username
   - Password
   - API URL (usually: `https://www.text.lk/api/send`)
   - Sender ID (optional, but recommended)

### Option B: Contact Text.lk Support

If you need help setting up:
- **Email**: support@text.lk
- **Phone**: Check their website for contact details

## Step 2: Configure Environment Variables

1. **Open your `.env` file** in the `backend` directory

2. **Add these variables**:

```env
# SMS Configuration (Text.lk v3 API)
TEXT_LK_API_TOKEN=your_api_token_here
TEXT_LK_API_URL=https://app.text.lk/api/http/send
TEXT_LK_SENDER_ID=YOUR_SENDER_ID
```

### Environment Variables Explained:

- **TEXT_LK_API_TOKEN**: Your Text.lk API token (format: `2396|xxxxxxxxxxxxx`)
- **TEXT_LK_API_URL**: HTTP API endpoint (default: `https://app.text.lk/api/http/send`)
- **TEXT_LK_SENDER_ID**: Your registered sender ID (optional, but recommended for better delivery)

### Example Configuration:

```env
TEXT_LK_API_TOKEN=2396|Cabsm0McwWihFpWK6MXIcdDvnmvCXwTvu6aAMcIQ640a6ebd
TEXT_LK_API_URL=https://app.text.lk/api/http/send
TEXT_LK_SENDER_ID=YOUR_COMPANY
```

## Step 3: Restart Your Server

After adding the credentials:

1. **Stop your backend server** (Ctrl+C)
2. **Restart it**:
   ```bash
   npm run dev
   ```

## Step 4: Test SMS Service

### Test Method 1: Place an Order

1. Create a test order in the system
2. Check the backend console for SMS sending logs
3. The customer should receive an SMS notification

### Test Method 2: Check Logs

When SMS is sent, you should see in the console:
```
SMS sent via text.lk: { response data }
```

If there's an error, you'll see:
```
SMS sending failed: [error details]
Text.lk API error response: [error response]
```

## Alternative SMS Providers

If you want to use a different SMS provider, you'll need to modify `backend/services/smsService.js`. Here are some alternatives:

### Option 1: Twilio (International)

1. Sign up at https://www.twilio.com/
2. Get Account SID and Auth Token
3. Modify `smsService.js` to use Twilio SDK

### Option 2: Dialog SMS Gateway

1. Contact Dialog for SMS gateway access
2. Get API credentials
3. Modify `smsService.js` to use Dialog API

### Option 3: Mobitel SMS Gateway

1. Contact Mobitel for SMS gateway access
2. Get API credentials
3. Modify `smsService.js` to use Mobitel API

## Troubleshooting

### Issue: SMS not sending

**Check:**
1. ✅ Credentials are correct in `.env`
2. ✅ Server was restarted after adding credentials
3. ✅ Text.lk account has sufficient balance
4. ✅ Phone numbers are in correct format (Sri Lankan numbers: 94XXXXXXXXX or 0XXXXXXXXX)

### Issue: "SMS simulated" message

**Cause:** API token not configured or incorrect

**Solution:**
- Verify `TEXT_LK_API_TOKEN` is set in `.env`
- Make sure the token format is correct (should include the pipe character: `2396|xxxxx`)
- Restart the server

### Issue: API Error Response

**Common errors:**
- **401 Unauthorized**: Invalid or expired API token - check your token
- **403 Forbidden**: Token doesn't have permission - verify token in Text.lk dashboard
- **Insufficient balance**: Add credits to your Text.lk account
- **Invalid phone number**: Ensure numbers are in correct format (94XXXXXXXXX)
- **Sender ID not approved**: Contact Text.lk to approve your sender ID
- **400 Bad Request**: Check request format and parameters

### Issue: Phone number format

The system automatically formats phone numbers:
- `0712345678` → `94712345678`
- `+94712345678` → `94712345678`
- `94712345678` → `94712345678` (already correct)

## SMS Notifications Currently Active

Once configured, SMS will be sent for:

1. **Order Placed** - Customer receives confirmation
2. **Order Status Updates** - Customer notified of status changes
3. **New Order to Supplier** - Supplier notified of new orders
4. **Inquiry Bids** - Customer notified when bids are received
5. **Supplier Inquiry** - Supplier notified of new inquiries

## Cost Considerations

- Text.lk typically charges per SMS sent
- Check Text.lk pricing on their website
- Consider bulk SMS packages for better rates
- Monitor your account balance regularly

## Security Notes

⚠️ **Important:**
- Never commit `.env` file to version control
- Keep your SMS credentials secure
- Use environment variables, never hardcode credentials
- Rotate passwords periodically

## Verification Checklist

After setup, verify:

- [ ] Text.lk account created
- [ ] Credentials added to `.env` file
- [ ] Server restarted
- [ ] Test SMS sent successfully
- [ ] Console shows "SMS sent via text.lk" (not "simulated")
- [ ] Customer receives SMS notifications
- [ ] Supplier receives SMS notifications

## Need Help?

If you encounter issues:
1. Check the backend console for error messages
2. Verify Text.lk account status and balance
3. Test with a simple SMS first
4. Contact Text.lk support if API issues persist

---

**Note:** The system will continue to work without SMS configured - it will just log messages instead of sending real SMS. All other features remain functional.