## WhatsApp OTP Integration Guide

This guide explains how to set up WhatsApp OTP sending using Twilio.

### Prerequisites
- Twilio account (https://www.twilio.com)
- WhatsApp Business Account or use Twilio Sandbox for testing

### Step 1: Create Twilio Account

1. Go to https://www.twilio.com/console/signup
2. Sign up with your email and phone number
3. Complete phone verification
4. Create a project (select "Messaging")

### Step 2: Set Up WhatsApp

1. In Twilio Console, go to: Messaging → Try it out → Send WhatsApp message
2. Click "Enable WhatsApp Sandbox"
3. Follow the instructions to:
   - Opt-in to the Twilio WhatsApp Sandbox
   - Verify your phone number

### Step 3: Get WhatsApp Number

1. In Twilio Console, go to: Messaging → Send WhatsApp message
2. Your WhatsApp number will be displayed (format: +1234567890)
3. Note this number - you'll need it for `.env`

### Step 4: Get API Credentials

1. Go to Twilio Console → Account
2. Find and copy:
   - **Account SID** (starts with AC)
   - **Auth Token** (hidden, click to reveal)

### Step 5: Configure .env

In `backend/.env`, add:

```env
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_WHATSAPP_NUMBER=+1234567890
```

### Step 6: Test WhatsApp OTP

#### For Sandbox Testing:
1. Send test message from Twilio SandBox number to your phone
2. Your phone will receive approval code (e.g., "join glass-lake")
3. Send that code via WhatsApp to your Sandbox number
4. Now you can receive OTP messages

#### Code Example:
```javascript
import { sendWhatsAppOTP } from './config/whatsapp.js';

// Send OTP
const result = await sendWhatsAppOTP('9876543210', '123456');
console.log(result); // { success: true, messageId: '...' }
```

### Step 7: Go Live (Production)

1. Request WhatsApp Business Account verification
2. In Twilio Console, apply for production WhatsApp access
3. Twilio team will approve (1-3 days)
4. Once approved, use your business number instead of sandbox

### Pricing

- Twilio WhatsApp: ~₹0.50 per message (India)
- SMS costs vary by country
- Free trial credits: $15 (usually sufficient for testing)

### Troubleshooting

**"Message failed to send" error**
- Check Twilio Account SID and Auth Token
- Verify WhatsApp number format (+91 for India)
- Ensure phone is opted-in to sandbox

**"Rate limit exceeded"**
- Twilio limits: 60 messages per minute per recipient
- Implement message queue if needed

**"Invalid account"**
- Verify SID and Auth Token in .env
- Check account isn't suspended (https://twilio.com/console)

### Alternative: Using WhatsApp Business API

For production, consider using WhatsApp Official Business API:
- More reliable
- Better deliverability
- Official support

Setup:
1. Register Business Account
2. Get Phone Number ID
3. Create System User with Business Management permissions
4. Update backend code to use official API

### Sample WhatsApp Messages

**OTP Message Template:**
```
Your OTP for Trust Tax Advisor is: 123456
Valid for 10 minutes.
```

**Alert Message Template:**
```
Your order #12345 has been completed.
Commission: ₹5000
Status: Pending
```

### API Response Headers

```javascript
{
  "success": true,
  "messageId": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

### Testing Checklist
- [ ] Twilio account active
- [ ] WhatsApp Sandbox opted-in
- [ ] Phone number verified
- [ ] Account SID copied
- [ ] Auth Token copied
- [ ] WhatsApp number configured
- [ ] Test message sent successfully
- [ ] .env variables set correctly