bakery-ia/docs/whatsapp/implementation-summary.md

# WhatsApp Shared Account Implementation - Summary

## What Was Implemented

A **simplified WhatsApp notification system** using a **shared master account** model, perfect for your 10-bakery pilot program. This eliminates the need for non-technical bakery owners to configure Meta credentials.

---

## Key Changes Made

### ✅ Backend Changes

1. **Tenant Settings Model** - Removed per-tenant credentials, added display phone number
   - File: [tenant_settings.py](services/tenant/app/models/tenant_settings.py)
   - File: [tenant_settings.py](services/tenant/app/schemas/tenant_settings.py)

2. **Notification Service** - Always uses shared master credentials with tenant-specific phone numbers
   - File: [whatsapp_business_service.py](services/notification/app/services/whatsapp_business_service.py)

3. **Phone Number Management API** - New admin endpoints for assigning phone numbers
   - File: [whatsapp_admin.py](services/tenant/app/api/whatsapp_admin.py)
   - Registered in: [main.py](services/tenant/app/main.py)

### ✅ Frontend Changes

4. **Simplified Settings UI** - Removed credential inputs, shows assigned phone number only
   - File: [NotificationSettingsCard.tsx](frontend/src/pages/app/database/ajustes/cards/NotificationSettingsCard.tsx)
   - Types: [settings.ts](frontend/src/api/types/settings.ts)

5. **Admin Interface** - New page for assigning phone numbers to tenants
   - File: [WhatsAppAdminPage.tsx](frontend/src/pages/app/admin/WhatsAppAdminPage.tsx)

### ✅ Documentation

6. **Comprehensive Guides**
   - [WHATSAPP_SHARED_ACCOUNT_GUIDE.md](WHATSAPP_SHARED_ACCOUNT_GUIDE.md) - Full implementation details
   - [WHATSAPP_MASTER_ACCOUNT_SETUP.md](WHATSAPP_MASTER_ACCOUNT_SETUP.md) - Step-by-step setup

---

## Quick Start (For You - Platform Admin)

### Step 1: Set Up Master WhatsApp Account (One-Time)

Follow the detailed guide: [WHATSAPP_MASTER_ACCOUNT_SETUP.md](WHATSAPP_MASTER_ACCOUNT_SETUP.md)

**Summary:**
1. Create Meta Business Account
2. Add WhatsApp product
3. Verify business (1-3 days wait)
4. Add 10 phone numbers
5. Create message templates
6. Get credentials (WABA ID, Access Token, Phone Number IDs)

**Time:** 2-3 hours + verification wait

### Step 2: Configure Environment Variables

Edit `services/notification/.env`:

```bash
WHATSAPP_BUSINESS_ACCOUNT_ID=your-waba-id-here
WHATSAPP_ACCESS_TOKEN=your-access-token-here
WHATSAPP_PHONE_NUMBER_ID=default-phone-id-here
WHATSAPP_API_VERSION=v18.0
ENABLE_WHATSAPP_NOTIFICATIONS=true
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-secret-token-here
```

### Step 3: Restart Services

```bash
docker-compose restart notification-service tenant-service
```

### Step 4: Assign Phone Numbers to Bakeries

**Option A: Via Admin UI (Recommended)**

1. Open: `http://localhost:5173/app/admin/whatsapp`
2. For each bakery:
   - Select phone number from dropdown
   - Click assign

**Option B: Via API**

```bash
curl -X POST http://localhost:8001/api/v1/admin/whatsapp/tenants/{tenant_id}/assign-phone \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "123456789012345",
    "display_phone_number": "+34 612 345 678"
  }'
```

### Step 5: Test

1. Login as a bakery owner
2. Go to Settings → Notifications
3. Toggle WhatsApp ON
4. Verify phone number is displayed
5. Create a test purchase order
6. Supplier should receive WhatsApp message!

---

## For Bakery Owners (What They Need to Do)

### Before:
❌ Navigate Meta Business Suite
❌ Create WhatsApp Business Account
❌ Get 3 different credential IDs
❌ Copy/paste into settings
**Time:** 1-2 hours, high error rate

### After:
✅ Go to Settings → Notifications
✅ Toggle WhatsApp ON
✅ Done!
**Time:** 30 seconds

**No configuration needed - phone number is already assigned by you (admin)!**

---

## Architecture Overview

```
┌─────────────────────────────────────────────┐
│   Master WhatsApp Business Account          │
│   - Admin manages centrally                 │
│   - Single set of credentials               │
│   - 10 phone numbers (one per bakery)       │
└─────────────────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
   Phone #1       Phone #2      Phone #3
    +34 612       +34 612       +34 612
    345 678       345 679       345 680
        │             │             │
   Bakery A       Bakery B      Bakery C
```

---

## API Endpoints Created

### Admin Endpoints (New)

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/admin/whatsapp/phone-numbers` | List available phone numbers |
| GET | `/api/v1/admin/whatsapp/tenants` | List tenants with WhatsApp status |
| POST | `/api/v1/admin/whatsapp/tenants/{id}/assign-phone` | Assign phone to tenant |
| DELETE | `/api/v1/admin/whatsapp/tenants/{id}/unassign-phone` | Unassign phone from tenant |

### Test Commands

```bash
# View available phone numbers
curl http://localhost:8001/api/v1/admin/whatsapp/phone-numbers | jq

# View tenant WhatsApp status
curl http://localhost:8001/api/v1/admin/whatsapp/tenants | jq

# Assign phone to tenant
curl -X POST http://localhost:8001/api/v1/admin/whatsapp/tenants/{tenant_id}/assign-phone \
  -H "Content-Type: application/json" \
  -d '{"phone_number_id": "XXX", "display_phone_number": "+34 612 345 678"}'
```

---

## Database Changes

### Tenant Settings Schema

**Before:**
```json
{
  "notification_settings": {
    "whatsapp_enabled": false,
    "whatsapp_phone_number_id": "",
    "whatsapp_access_token": "",           // REMOVED
    "whatsapp_business_account_id": "",    // REMOVED
    "whatsapp_api_version": "v18.0",       // REMOVED
    "whatsapp_default_language": "es"
  }
}
```

**After:**
```json
{
  "notification_settings": {
    "whatsapp_enabled": false,
    "whatsapp_phone_number_id": "",            // Phone from shared account
    "whatsapp_display_phone_number": "",       // NEW: Display format
    "whatsapp_default_language": "es"
  }
}
```

**Migration:** No SQL migration needed (JSONB is schema-less). Existing data will work with defaults.

---

## Cost Estimate

### WhatsApp Messaging Costs (Spain)

- **Per conversation:** €0.0319 - €0.0699
- **Conversation window:** 24 hours
- **User-initiated:** Free

### Monthly Estimate (10 Bakeries)

```
5 POs per bakery per day × 10 bakeries × 30 days = 1,500 messages/month
1,500 × €0.05 (avg) = €75/month
```

### Setup Cost Savings

**Old Model (Per-Tenant):**
- 10 bakeries × 1.5 hours × €50/hr = **€750 in setup time**

**New Model (Shared Account):**
- Admin: 2 hours setup (one time)
- Per bakery: 5 minutes × 10 = **€0 in bakery time**

**Savings:** €750 in bakery owner time + reduced support tickets

---

## Monitoring & Maintenance

### Check Quality Rating (Weekly)

```bash
curl -X GET "https://graph.facebook.com/v18.0/{PHONE_NUMBER_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  | jq '.quality_rating'
```

**Quality Ratings:**
- **GREEN** ✅ - All good
- **YELLOW** ⚠️ - Review messaging patterns
- **RED** ❌ - Fix immediately

### View Message Logs

```bash
# Docker logs
docker logs -f notification-service | grep whatsapp

# Database query
SELECT tenant_id, recipient_phone, status, created_at, error_message
FROM whatsapp_messages
WHERE created_at > NOW() - INTERVAL '24 hours'
ORDER BY created_at DESC;
```

### Rotate Access Token (Every 60 Days)

1. Generate new token in Meta Business Manager
2. Update `WHATSAPP_ACCESS_TOKEN` in `.env`
3. Restart notification service
4. Revoke old token

---

## Troubleshooting

### Bakery doesn't receive WhatsApp messages

**Checklist:**
1. ✅ WhatsApp enabled in tenant settings?
2. ✅ Phone number assigned to tenant?
3. ✅ Master credentials in environment variables?
4. ✅ Template approved by Meta?
5. ✅ Recipient phone in E.164 format (+34612345678)?

**Check logs:**
```bash
docker logs -f notification-service | grep -i "whatsapp\|error"
```

### Phone assignment fails: "Already assigned"

Find which tenant has it:
```bash
curl http://localhost:8001/api/v1/admin/whatsapp/tenants | \
  jq '.[] | select(.phone_number_id == "YOUR_PHONE_ID")'
```

Unassign first:
```bash
curl -X DELETE http://localhost:8001/api/v1/admin/whatsapp/tenants/{tenant_id}/unassign-phone
```

### "WhatsApp master account not configured"

Ensure environment variables are set:
```bash
docker exec notification-service env | grep WHATSAPP
```

Should show all variables (WABA ID, Access Token, Phone Number ID).

---

## Next Steps

### Immediate (Before Pilot)

- [ ] Complete master account setup (follow [WHATSAPP_MASTER_ACCOUNT_SETUP.md](WHATSAPP_MASTER_ACCOUNT_SETUP.md))
- [ ] Assign phone numbers to all 10 pilot bakeries
- [ ] Send email to bakeries: "WhatsApp notifications are ready - just toggle ON in settings"
- [ ] Test with 2-3 bakeries first
- [ ] Monitor for first week

### Short-term (During Pilot)

- [ ] Collect bakery feedback
- [ ] Monitor quality rating daily
- [ ] Track message costs
- [ ] Document common support questions

### Long-term (After Pilot)

- [ ] Consider WhatsApp Embedded Signup for self-service (if scaling beyond 10)
- [ ] Create additional templates (inventory alerts, production alerts)
- [ ] Implement rich media messages (images, documents)
- [ ] Add interactive buttons (approve/reject PO via WhatsApp)

---

## Files Modified/Created

### Backend

**Modified:**
- `services/tenant/app/models/tenant_settings.py`
- `services/tenant/app/schemas/tenant_settings.py`
- `services/notification/app/services/whatsapp_business_service.py`
- `services/tenant/app/main.py`

**Created:**
- `services/tenant/app/api/whatsapp_admin.py`

### Frontend

**Modified:**
- `frontend/src/pages/app/database/ajustes/cards/NotificationSettingsCard.tsx`
- `frontend/src/api/types/settings.ts`

**Created:**
- `frontend/src/pages/app/admin/WhatsAppAdminPage.tsx`

### Documentation

**Created:**
- `WHATSAPP_SHARED_ACCOUNT_GUIDE.md` - Full implementation guide
- `WHATSAPP_MASTER_ACCOUNT_SETUP.md` - Admin setup instructions
- `WHATSAPP_IMPLEMENTATION_SUMMARY.md` - This file

---

## Support

**Questions?**
- Technical implementation: Review [WHATSAPP_SHARED_ACCOUNT_GUIDE.md](WHATSAPP_SHARED_ACCOUNT_GUIDE.md)
- Setup help: Follow [WHATSAPP_MASTER_ACCOUNT_SETUP.md](WHATSAPP_MASTER_ACCOUNT_SETUP.md)
- Meta documentation: https://developers.facebook.com/docs/whatsapp

**Common Issues:**
- Most problems are due to missing/incorrect environment variables
- Check logs: `docker logs -f notification-service`
- Verify Meta credentials haven't expired
- Ensure templates are APPROVED (not PENDING)

---

## Summary

✅ **Zero configuration** for bakery users
✅ **5-minute setup** per bakery (admin)
✅ **€750 saved** in setup costs
✅ **Lower support burden**
✅ **Perfect for 10-bakery pilot**
✅ **Can scale** to 120 bakeries with same model

**Next:** Set up your master WhatsApp account following [WHATSAPP_MASTER_ACCOUNT_SETUP.md](WHATSAPP_MASTER_ACCOUNT_SETUP.md)

---

**Implementation Date:** 2025-01-17
**Status:** ✅ Complete and Ready for Pilot
**Estimated Setup Time:** 2-3 hours (one-time)
**Per-Bakery Time:** 5 minutes