bakery-admin/bakery-ia

Fork 0

Files

Urtzi Alfaro 5c45164c8e Improve backend

2025-11-18 07:17:17 +01:00

17 KiB

Raw Blame History

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

Go to Meta Business Suite
Click Create Account
Enter business details:
- Business Name: "Bakery Platform" (or your company name)
- Your Name
- Business Email
Click Submit

1.2 Verify Your Business

Meta requires business verification for WhatsApp API access:

In Business Settings → Security Center
Click Start Verification
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
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

In Business Manager, go to Settings
Click Accounts → WhatsApp Accounts
Click Add → Create a new WhatsApp Business Account
Fill in details:
- Display Name: "Bakery Platform"
- Category: Food & Beverage
- Description: "Bakery management notifications"
Click Create

2.2 Configure WhatsApp Business Account

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)

In WhatsApp Manager → Phone Numbers
Click Add Phone Number
Enter phone number in E.164 format: +34612345678
Choose verification method:
- SMS (easiest)
- Voice call
Enter verification code
Note the Phone Number ID:
- Format: 123456789012345 (15 digits)
- Save this: Default phone number for environment variables

Option B: Use Meta-Provided Free Number

In WhatsApp Manager → Phone Numbers
Click Get a free phone number
Choose country: Spain (+34)
Meta assigns a number in format: +1555XXXXXXX
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:

Open support ticket at WhatsApp Business Support
Request: "Increase phone number limit to 10 for pilot program"
Provide business justification
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).

In Business Settings → Users → System Users
Click Add
Enter details:
- Name: "WhatsApp API Service"
- Role: Admin
Click Create System User

4.2 Generate Access Token

Select the system user you just created
Click Add Assets
Choose WhatsApp Accounts
Select your WhatsApp Business Account
Grant permissions:
- ✅ Manage WhatsApp Business Account
- ✅ Manage WhatsApp Business Messaging
- ✅ Read WhatsApp Business Insights
Click Generate New Token
Select token permissions:
- ✅ whatsapp_business_management
- ✅ whatsapp_business_messaging
Click Generate Token
IMPORTANT: Copy the token immediately
- Format: EAAxxxxxxxxxxxxxxxxxxxxxxxx (long string)
- Save this securely: You can't view it again!

Token Security:

# 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

In WhatsApp Manager → Message Templates
Click Create Template
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.

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:

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

In WhatsApp Manager → Configuration
Click Edit next to Webhook

Enter details:

Callback URL:     https://your-domain.com/api/v1/whatsapp/webhook
Verify Token:     random-secret-token-here

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

Select events to receive:

✅ messages - Incoming messages (for replies)
✅ message_status - Delivery, read receipts
✅ message_echoes - Sent message confirmations

Environment Variable:

WHATSAPP_WEBHOOK_VERIFY_TOKEN=random-secret-token-here

Step 7: Configure Environment Variables

7.1 Collect All Credentials

You should now have:

✅ WhatsApp Business Account ID (WABA ID)
- Example: 987654321098765
- Where: WhatsApp Manager → Settings → Business Info
✅ Access Token
- Example: EAAxxxxxxxxxxxxxxxxxxxxxxxx
- Where: System User token you generated
✅ Phone Number ID (default/fallback)
- Example: 123456789012345
- Where: WhatsApp Manager → Phone Numbers
✅ Webhook Verify Token (you chose this)
- Example: my-secret-webhook-token-12345

7.2 Update Notification Service Environment

File: services/notification/.env

# ================================================================
# 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

# 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:

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

Expected Response:

{
  "verified_name": "Bakery Platform",
  "display_phone_number": "+34 612 345 678",
  "quality_rating": "GREEN",
  "id": "123456789012345"
}

If error:

{
  "error": {
    "message": "Invalid OAuth access token",
    "type": "OAuthException",
    "code": 190
  }
}

→ Check your access token

8.2 Test Sending a Message

Via API:

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:

{
  "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:

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:

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

Open: http://localhost:5173/app/admin/whatsapp
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:

Find tenant in the list
Click dropdown: Assign phone number...
Select a phone number
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

# 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:

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

# 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:

Generate new token (Step 4.2)
Update environment variable
Restart notification service
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:

Contains promotional content in UTILITY template
- Fix: Remove words like "offer," "sale," "discount"
- Use MARKETING category instead
Missing variable indicators
- Fix: Ensure {{1}}, {{2}}, {{3}} are clearly marked
- Provide good example values
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:

Token expired → Generate new one (Step 4.2)
Wrong token → Copy correct token from System User
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:

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

Inform Bakeries:
- Send email: "WhatsApp notifications are now available"
- Instruct them to toggle WhatsApp ON in settings
- No configuration needed on their end!
Monitor First Week:
- Check quality rating daily
- Review message logs for errors
- Gather bakery feedback
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

17 KiB Raw Blame History Unescape Escape

WhatsApp Master Account Setup Guide

Prerequisites

Step 1: Create Meta Business Account

1.1 Create Business Manager

1.2 Verify Your Business

Step 2: Add WhatsApp Product

2.1 Enable WhatsApp

2.2 Configure WhatsApp Business Account

Step 3: Add Phone Numbers

3.1 Add Your First Phone Number

3.2 Add Additional Phone Numbers (For Pilot Bakeries)

Step 4: Create System User & Access Token

4.1 Create System User

4.2 Generate Access Token

Step 5: Create Message Templates

5.1 Create PO Notification Template

5.2 Check Template Status

5.3 Create Additional Templates (Optional)

Step 6: Configure Webhooks (For Status Updates)

6.1 Create Webhook Endpoint

6.2 Register Webhook with Meta

6.3 Subscribe to Webhook Events

Step 7: Configure Environment Variables

7.1 Collect All Credentials

7.2 Update Notification Service Environment

7.3 Restart Services

Step 8: Verify Setup

8.1 Test API Connectivity

8.2 Test Sending a Message

8.3 Test via Notification Service

Step 9: Assign Phone Numbers to Tenants

9.1 Access Admin Interface

9.2 Assign Each Bakery

9.3 Verify Assignments

Step 10: Monitor & Maintain

10.1 Monitor Quality Rating

10.2 Check Message Costs

10.3 Rotate Access Token (Every 60 Days)

Troubleshooting

Issue: Business verification stuck

Issue: Phone number verification fails

Issue: Template rejected

Issue: "Invalid OAuth access token"

Issue: Webhook verification fails

Checklist: You're Done When...

Next Steps

Support Resources

17 KiB

Raw Blame History