bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit - production deployment

Browse Source
This commit is contained in:
Bakery Admin
2026-01-21 17:17:16 +01:00
commit c23d00dd92
2289 changed files with 638440 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

691
docs/whatsapp/master-account-setup.md Normal file
View File

@@ -0,0 +1,691 @@
# WhatsApp Master Account Setup Guide
**Quick Setup Guide for Platform Admin**
This guide walks you through setting up the Master WhatsApp Business Account for the bakery-ia pilot program.
---
## Prerequisites
- [ ] Meta/Facebook Business account
- [ ] Business verification documents (tax ID, business registration)
- [ ] 10 phone numbers for pilot bakeries
- [ ] Credit card for WhatsApp Business API billing
**Time Required:** 2-3 hours (including verification wait time)
---
## Step 1: Create Meta Business Account
### 1.1 Create Business Manager
1. Go to [Meta Business Suite](https://business.facebook.com)
2. Click **Create Account**
3. Enter business details:
- Business Name: "Bakery Platform" (or your company name)
- Your Name
- Business Email
4. Click **Submit**
### 1.2 Verify Your Business
Meta requires business verification for WhatsApp API access:
1. In Business Settings → **Security Center**
2. Click **Start Verification**
3. Choose verification method:
- **Business Documents** (Recommended)
- Upload tax registration document
- Upload business license or registration
- **Domain Verification**
- Add DNS TXT record to your domain
- **Phone Verification**
- Receive call/SMS to business phone
4. Wait for verification (typically 1-3 business days)
**Status Check:**
```
Business Settings → Security Center → Verification Status
```
---
## Step 2: Add WhatsApp Product
### 2.1 Enable WhatsApp
1. In Business Manager, go to **Settings**
2. Click **Accounts** → **WhatsApp Accounts**
3. Click **Add** → **Create a new WhatsApp Business Account**
4. Fill in details:
- Display Name: "Bakery Platform"
- Category: Food & Beverage
- Description: "Bakery management notifications"
5. Click **Create**
### 2.2 Configure WhatsApp Business Account
1. After creation, note your **WhatsApp Business Account ID (WABA ID)**
- Found in: WhatsApp Manager → Settings → Business Info
- Format: `987654321098765` (15 digits)
- **Save this:** You'll need it for environment variables
---
## Step 3: Add Phone Numbers
### 3.1 Add Your First Phone Number
**Option A: Use Your Own Phone Number** (Recommended for testing)
1. In WhatsApp Manager → **Phone Numbers**
2. Click **Add Phone Number**
3. Enter phone number in E.164 format: `+34612345678`
4. Choose verification method:
- **SMS** (easiest)
- **Voice call**
5. Enter verification code
6. Note the **Phone Number ID**:
- Format: `123456789012345` (15 digits)
- **Save this:** Default phone number for environment variables
**Option B: Use Meta-Provided Free Number**
1. In WhatsApp Manager → **Phone Numbers**
2. Click **Get a free phone number**
3. Choose country: Spain (+34)
4. Meta assigns a number in format: `+1555XXXXXXX`
5. Note: Free numbers have limitations:
- Can't be ported to other accounts
- Limited to 1,000 conversations/day
- Good for pilot, not production
### 3.2 Add Additional Phone Numbers (For Pilot Bakeries)
Repeat the process to add 10 phone numbers total (one per bakery).
**Tips:**
- Use virtual phone number services (Twilio, Plivo, etc.)
- Cost: ~€5-10/month per number
- Alternative: Request Meta phone numbers (via support ticket)
**Request Phone Number Limit Increase:**
If you need more than 2 phone numbers:
1. Open support ticket at [WhatsApp Business Support](https://business.whatsapp.com/support)
2. Request: "Increase phone number limit to 10 for pilot program"
3. Provide business justification
4. Wait 1-2 days for approval
---
## Step 4: Create System User & Access Token
### 4.1 Create System User
**Why:** System Users provide permanent access tokens (don't expire every 60 days).
1. In Business Settings → **Users** → **System Users**
2. Click **Add**
3. Enter details:
- Name: "WhatsApp API Service"
- Role: **Admin**
4. Click **Create System User**
### 4.2 Generate Access Token
1. Select the system user you just created
2. Click **Add Assets**
3. Choose **WhatsApp Accounts**
4. Select your WhatsApp Business Account
5. Grant permissions:
- ✅ Manage WhatsApp Business Account
- ✅ Manage WhatsApp Business Messaging
- ✅ Read WhatsApp Business Insights
6. Click **Generate New Token**
7. Select token permissions:
- ✅ `whatsapp_business_management`
- ✅ `whatsapp_business_messaging`
8. Click **Generate Token**
9. **IMPORTANT:** Copy the token immediately
- Format: `EAAxxxxxxxxxxxxxxxxxxxxxxxx` (long string)
- **Save this securely:** You can't view it again!
**Token Security:**
```bash
# Good: Use environment variable
WHATSAPP_ACCESS_TOKEN=EAAxxxxxxxxxxxxx
# Bad: Hardcode in source code
# token = "EAAxxxxxxxxxxxxx" # DON'T DO THIS!
```
---
## Step 5: Create Message Templates
WhatsApp requires pre-approved templates for business-initiated messages.
### 5.1 Create PO Notification Template
1. In WhatsApp Manager → **Message Templates**
2. Click **Create Template**
3. Fill in template details:
```
Template Name: po_notification
Category: UTILITY
Languages: Spanish (es)
Message Body:
Hola {{1}}, has recibido una nueva orden de compra {{2}} por un total de {{3}}.
Parameters:
1. Supplier Name (text)
2. PO Number (text)
3. Total Amount (text)
Example:
Hola Juan García, has recibido una nueva orden de compra PO-12345 por un total de €250.50.
```
4. Click **Submit for Approval**
**Approval Time:**
- Typical: 15 minutes to 2 hours
- Complex templates: Up to 24 hours
- If rejected: Review feedback and resubmit
### 5.2 Check Template Status
**Via UI:**
```
WhatsApp Manager → Message Templates → Filter by Status
```
**Via API:**
```bash
curl "https://graph.facebook.com/v18.0/{WABA_ID}/message_templates?fields=name,status,language" \
-H "Authorization: Bearer {ACCESS_TOKEN}" | jq
```
**Template Statuses:**
- `PENDING` - Under review
- `APPROVED` - Ready to use
- `REJECTED` - Review feedback and fix
- `DISABLED` - Paused due to quality issues
### 5.3 Create Additional Templates (Optional)
For inventory alerts, production alerts, etc.:
```
Template Name: low_stock_alert
Category: UTILITY
Language: Spanish (es)
Message:
⚠️ Alerta: El ingrediente {{1}} tiene stock bajo.
Cantidad actual: {{2}} {{3}}.
Punto de reorden: {{4}} {{5}}.
```
---
## Step 6: Configure Webhooks (For Status Updates)
### 6.1 Create Webhook Endpoint
Webhooks notify you of message delivery status, read receipts, etc.
**Your webhook endpoint:**
```
https://your-domain.com/api/v1/whatsapp/webhook
```
**Implemented in:** `services/notification/app/api/whatsapp_webhooks.py`
### 6.2 Register Webhook with Meta
1. In WhatsApp Manager → **Configuration**
2. Click **Edit** next to Webhook
3. Enter details:
```
Callback URL: https://your-domain.com/api/v1/whatsapp/webhook
Verify Token: random-secret-token-here
```
4. Click **Verify and Save**
**Meta will send GET request to verify:**
```
GET /api/v1/whatsapp/webhook?hub.verify_token=YOUR_TOKEN&hub.challenge=XXXXX
```
**Your endpoint must respond with:** `hub.challenge` value
### 6.3 Subscribe to Webhook Events
Select events to receive:
- ✅ `messages` - Incoming messages (for replies)
- ✅ `message_status` - Delivery, read receipts
- ✅ `message_echoes` - Sent message confirmations
**Environment Variable:**
```bash
WHATSAPP_WEBHOOK_VERIFY_TOKEN=random-secret-token-here
```
---
## Step 7: Configure Environment Variables
### 7.1 Collect All Credentials
You should now have:
1. ✅ **WhatsApp Business Account ID (WABA ID)**
- Example: `987654321098765`
- Where: WhatsApp Manager → Settings → Business Info
2. ✅ **Access Token**
- Example: `EAAxxxxxxxxxxxxxxxxxxxxxxxx`
- Where: System User token you generated
3. ✅ **Phone Number ID** (default/fallback)
- Example: `123456789012345`
- Where: WhatsApp Manager → Phone Numbers
4. ✅ **Webhook Verify Token** (you chose this)
- Example: `my-secret-webhook-token-12345`
### 7.2 Update Notification Service Environment
**File:** `services/notification/.env`
```bash
# ================================================================
# WhatsApp Business Cloud API Configuration
# ================================================================
# Master WhatsApp Business Account ID (15 digits)
WHATSAPP_BUSINESS_ACCOUNT_ID=987654321098765
# System User Access Token (starts with EAA)
WHATSAPP_ACCESS_TOKEN=EAAxxxxxxxxxxxxxxxxxxxxxxxx
# Default Phone Number ID (15 digits) - fallback if tenant has none assigned
WHATSAPP_PHONE_NUMBER_ID=123456789012345
# WhatsApp Cloud API Version
WHATSAPP_API_VERSION=v18.0
# Enable/disable WhatsApp notifications globally
ENABLE_WHATSAPP_NOTIFICATIONS=true
# Webhook verification token (random secret you chose)
WHATSAPP_WEBHOOK_VERIFY_TOKEN=my-secret-webhook-token-12345
```
### 7.3 Restart Services
```bash
# Docker Compose
docker-compose restart notification-service
# Kubernetes
kubectl rollout restart deployment/notification-service
# Or rebuild
docker-compose up -d --build notification-service
```
---
## Step 8: Verify Setup
### 8.1 Test API Connectivity
**Check if credentials work:**
```bash
curl -X GET "https://graph.facebook.com/v18.0/{PHONE_NUMBER_ID}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
| jq
```
**Expected Response:**
```json
{
"verified_name": "Bakery Platform",
"display_phone_number": "+34 612 345 678",
"quality_rating": "GREEN",
"id": "123456789012345"
}
```
**If error:**
```json
{
"error": {
"message": "Invalid OAuth access token",
"type": "OAuthException",
"code": 190
}
}
```
→ Check your access token
### 8.2 Test Sending a Message
**Via API:**
```bash
curl -X POST "https://graph.facebook.com/v18.0/{PHONE_NUMBER_ID}/messages" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "+34612345678",
"type": "template",
"template": {
"name": "po_notification",
"language": {
"code": "es"
},
"components": [
{
"type": "body",
"parameters": [
{"type": "text", "text": "Juan García"},
{"type": "text", "text": "PO-12345"},
{"type": "text", "text": "€250.50"}
]
}
]
}
}'
```
**Expected Response:**
```json
{
"messaging_product": "whatsapp",
"contacts": [
{
"input": "+34612345678",
"wa_id": "34612345678"
}
],
"messages": [
{
"id": "wamid.XXXxxxXXXxxxXXX"
}
]
}
```
**Check WhatsApp on recipient's phone!**
### 8.3 Test via Notification Service
**Trigger PO notification:**
```bash
curl -X POST http://localhost:8002/api/v1/whatsapp/send \
-H "Content-Type: application/json" \
-d '{
"tenant_id": "uuid-here",
"recipient_phone": "+34612345678",
"recipient_name": "Juan García",
"message_type": "template",
"template": {
"template_name": "po_notification",
"language": "es",
"components": [
{
"type": "body",
"parameters": [
{"type": "text", "text": "Juan García"},
{"type": "text", "text": "PO-TEST-001"},
{"type": "text", "text": "€150.00"}
]
}
]
}
}'
```
**Check logs:**
```bash
docker logs -f notification-service | grep whatsapp
```
**Expected log output:**
```
[INFO] Using shared WhatsApp account tenant_id=xxx phone_number_id=123456789012345
[INFO] WhatsApp template message sent successfully message_id=xxx whatsapp_message_id=wamid.XXX
```
---
## Step 9: Assign Phone Numbers to Tenants
Now that the master account is configured, assign phone numbers to each bakery.
### 9.1 Access Admin Interface
1. Open: `http://localhost:5173/app/admin/whatsapp`
2. You should see:
- **Available Phone Numbers:** List of your 10 numbers
- **Bakery Tenants:** List of all bakeries
### 9.2 Assign Each Bakery
For each of the 10 pilot bakeries:
1. Find tenant in the list
2. Click dropdown: **Assign phone number...**
3. Select a phone number
4. Verify green checkmark appears
**Example:**
```
Panadería San Juan → +34 612 345 678
Panadería Goiko → +34 612 345 679
Bakery Artesano → +34 612 345 680
... (7 more)
```
### 9.3 Verify Assignments
```bash
# Check all assignments
curl http://localhost:8001/api/v1/admin/whatsapp/tenants | jq
# Should show each tenant with assigned phone
```
---
## Step 10: Monitor & Maintain
### 10.1 Monitor Quality Rating
WhatsApp penalizes low-quality messaging. Check your 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, no restrictions
- **YELLOW** ⚠️ - Warning, review messaging patterns
- **RED** ❌ - Restricted, fix issues immediately
**Common Issues Leading to Low Quality:**
- High block rate (users blocking your number)
- Sending to invalid phone numbers
- Template violations (sending promotional content in UTILITY templates)
- User reports (spam complaints)
### 10.2 Check Message Costs
```bash
# View billing in Meta Business Manager
Business Settings → Payments → WhatsApp Business API
```
**Cost per Conversation (Spain):**
- Business-initiated: €0.0319 - €0.0699
- User-initiated: Free (24hr window)
**Monthly Estimate (10 Bakeries):**
- 5 POs per day per bakery = 50 messages/day
- 50 × 30 days = 1,500 messages/month
- 1,500 × €0.05 = **~€75/month**
### 10.3 Rotate Access Token (Every 60 Days)
Even though system user tokens are "permanent," rotate for security:
1. Generate new token (Step 4.2)
2. Update environment variable
3. Restart notification service
4. Revoke old token
**Set reminder:** Calendar alert every 60 days
---
## Troubleshooting
### Issue: Business verification stuck
**Solution:**
- Check Business Manager → Security Center
- Common reasons:
- Documents unclear/incomplete
- Business name mismatch with documents
- Banned domain/business
- Contact Meta Business Support if > 5 days
### Issue: Phone number verification fails
**Error:** "This phone number is already registered with WhatsApp"
**Solution:**
- Number is used for personal WhatsApp
- You must use a different number OR
- Delete personal WhatsApp account (this is permanent!)
### Issue: Template rejected
**Common Rejection Reasons:**
1. **Contains promotional content in UTILITY template**
- Fix: Remove words like "offer," "sale," "discount"
- Use MARKETING category instead
2. **Missing variable indicators**
- Fix: Ensure {{1}}, {{2}}, {{3}} are clearly marked
- Provide good example values
3. **Unclear purpose**
- Fix: Add context in template description
- Explain use case clearly
**Resubmit:** Edit template and click "Submit for Review" again
### Issue: "Invalid OAuth access token"
**Solutions:**
1. Token expired → Generate new one (Step 4.2)
2. Wrong token → Copy correct token from System User
3. Token doesn't have permissions → Regenerate with correct scopes
### Issue: Webhook verification fails
**Error:** "The URL couldn't be validated. Callback verification failed"
**Checklist:**
- [ ] Endpoint is publicly accessible (not localhost)
- [ ] Returns `200 OK` status
- [ ] Returns the `hub.challenge` value exactly
- [ ] HTTPS enabled (not HTTP)
- [ ] Verify token matches environment variable
**Test webhook manually:**
```bash
curl "https://your-domain.com/api/v1/whatsapp/webhook?hub.verify_token=YOUR_TOKEN&hub.challenge=12345"
# Should return: 12345
```
---
## Checklist: You're Done When...
- [ ] Meta Business Account created and verified
- [ ] WhatsApp Business Account created (WABA ID saved)
- [ ] 10 phone numbers added and verified
- [ ] System User created
- [ ] Access Token generated and saved securely
- [ ] Message template `po_notification` approved
- [ ] Webhook configured and verified
- [ ] Environment variables set in `.env`
- [ ] Notification service restarted
- [ ] Test message sent successfully
- [ ] All 10 bakeries assigned phone numbers
- [ ] Quality rating is GREEN
- [ ] Billing configured in Meta Business Manager
**Estimated Total Time:** 2-3 hours (plus 1-3 days for business verification)
---
## Next Steps
1. **Inform Bakeries:**
- Send email: "WhatsApp notifications are now available"
- Instruct them to toggle WhatsApp ON in settings
- No configuration needed on their end!
2. **Monitor First Week:**
- Check quality rating daily
- Review message logs for errors
- Gather bakery feedback
3. **Scale Beyond Pilot:**
- Request phone number limit increase (up to 120)
- Consider WhatsApp Embedded Signup for self-service
- Evaluate tiered pricing (Standard vs. Enterprise)
---
## Support Resources
**Meta Documentation:**
- WhatsApp Cloud API: https://developers.facebook.com/docs/whatsapp/cloud-api
- Getting Started Guide: https://developers.facebook.com/docs/whatsapp/cloud-api/get-started
- Template Guidelines: https://developers.facebook.com/docs/whatsapp/message-templates/guidelines
**Meta Support:**
- Business Support: https://business.whatsapp.com/support
- Developer Community: https://developers.facebook.com/community/
**Internal:**
- Full Implementation Guide: `WHATSAPP_SHARED_ACCOUNT_GUIDE.md`
- Admin Interface: `http://localhost:5173/app/admin/whatsapp`
- API Documentation: `http://localhost:8001/docs#/whatsapp-admin`
---
**Document Version:** 1.0
**Last Updated:** 2025-01-17
**Author:** Platform Engineering Team
**Estimated Setup Time:** 2-3 hours
**Difficulty:** Intermediate