403 lines
11 KiB
Markdown
403 lines
11 KiB
Markdown
# 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
|