bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d98fed0cd0ed120efe65fdcf9ab4655701a721eb
bakery-ia/services/notification/WHATSAPP_IMPLEMENTATION_SUMMARY.md
Urtzi Alfaro 9bc048d360 Add whatsapp feature
2025-11-13 16:01:08 +01:00

11 KiB
Raw Blame History

WhatsApp Business Cloud API Implementation Summary

Overview

Successfully implemented WhatsApp Business Cloud API integration for sending free template-based notifications to suppliers about purchase orders.

Implementation Details

🎯 Objectives Achieved

✅ Direct integration with Meta's WhatsApp Business Cloud API (no Twilio) ✅ Template-based messaging for proactive notifications ✅ Delivery tracking with webhooks ✅ Database persistence for message history ✅ Backward-compatible wrapper for existing code ✅ Complete setup documentation

Files Created

1. Database Layer

app/models/whatsapp_messages.py

  • WhatsAppMessage: Track sent messages and delivery status
  • WhatsAppTemplate: Store template metadata
  • Enums for message types and statuses

migrations/versions/20251113_add_whatsapp_business_tables.py

  • Creates whatsapp_messages table
  • Creates whatsapp_templates table
  • Adds indexes for performance

app/repositories/whatsapp_message_repository.py

  • WhatsAppMessageRepository: CRUD operations for messages
  • WhatsAppTemplateRepository: Template management
  • Delivery statistics and analytics

2. Service Layer

app/services/whatsapp_business_service.py

  • Direct WhatsApp Cloud API integration
  • Template message sending
  • Text message support
  • Bulk messaging with rate limiting
  • Health checks

app/schemas/whatsapp.py

  • Request/response schemas
  • Template message schemas
  • Webhook payload schemas
  • Delivery statistics schemas

3. API Layer

app/api/whatsapp_webhooks.py

  • Webhook verification endpoint (GET)
  • Webhook event handler (POST)
  • Status update processing
  • Incoming message handling

4. Documentation

WHATSAPP_SETUP_GUIDE.md

Complete step-by-step setup guide covering:

  • Meta Business Account creation
  • WhatsApp Business registration
  • API credential generation
  • Template creation and approval
  • Webhook configuration
  • Environment setup
  • Testing procedures
  • Troubleshooting

Files Modified

1. app/services/whatsapp_service.py

Changes:

  • Replaced Twilio integration with WhatsApp Business Cloud API
  • Created backward-compatible wrapper around new service
  • Maintains existing method signatures
  • Added tenant_id parameter support

Before:

# Twilio-based implementation
async def send_message(self, to_phone, message, template_name=None, template_params=None):
    # Twilio API calls

After:

# Wrapper around WhatsAppBusinessService
async def send_message(self, to_phone, message, template_name=None, template_params=None, tenant_id=None):
    # Delegates to WhatsAppBusinessService

2. app/core/config.py

Added:

# WhatsApp Business Cloud API Configuration
WHATSAPP_ACCESS_TOKEN: str
WHATSAPP_PHONE_NUMBER_ID: str
WHATSAPP_BUSINESS_ACCOUNT_ID: str
WHATSAPP_API_VERSION: str
WHATSAPP_WEBHOOK_VERIFY_TOKEN: str

Deprecated (kept for backward compatibility):

WHATSAPP_API_KEY: str  # Deprecated
WHATSAPP_BASE_URL: str  # Deprecated
WHATSAPP_FROM_NUMBER: str  # Deprecated

3. app/main.py

Changes:

  • Updated expected migration version to whatsapp001
  • Added whatsapp_messages and whatsapp_templates to expected tables
  • Imported and registered whatsapp_webhooks_router
  • Updated PO consumer initialization to include WhatsApp service

Added:

from app.api.whatsapp_webhooks import router as whatsapp_webhooks_router

service.add_router(whatsapp_webhooks_router, tags=["whatsapp-webhooks"])

4. app/consumers/po_event_consumer.py

Changes:

  • Added WhatsApp service dependency
  • Implemented send_po_approved_whatsapp() method
  • Integrated WhatsApp sending into event processing
  • Added template-based notification for PO events

New Method:

async def send_po_approved_whatsapp(self, event_data: Dict[str, Any]) -> bool:
    # Sends template message to supplier
    # Template: po_notification
    # Parameters: supplier_name, po_number, total_amount

API Endpoints Added

Webhook Endpoints

GET /api/v1/whatsapp/webhook

  • Purpose: Webhook verification by Meta
  • Parameters: hub.mode, hub.verify_token, hub.challenge
  • Response: Challenge token if verified

POST /api/v1/whatsapp/webhook

  • Purpose: Receive webhook events from WhatsApp
  • Events: Message status updates, incoming messages
  • Response: Success acknowledgment

GET /api/v1/whatsapp/health

  • Purpose: Health check for webhook endpoint
  • Response: Service status

Environment Variables

Required

# WhatsApp Business Cloud API
WHATSAPP_ACCESS_TOKEN=EAAxxxxxxxxxxxxx
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_BUSINESS_ACCOUNT_ID=987654321098765
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-random-token

# Feature Flag
ENABLE_WHATSAPP_NOTIFICATIONS=true

Optional

WHATSAPP_API_VERSION=v18.0  # Default: v18.0

Database Schema

whatsapp_messages Table

Column Type Description
id UUID Primary key
tenant_id UUID Tenant identifier
notification_id UUID Link to notification
whatsapp_message_id String WhatsApp's message ID
recipient_phone String E.164 phone number
message_type Enum TEMPLATE, TEXT, IMAGE, etc.
status Enum PENDING, SENT, DELIVERED, READ, FAILED
template_name String Template name used
template_parameters JSON Template parameter values
sent_at DateTime When sent
delivered_at DateTime When delivered
read_at DateTime When read
error_message Text Error if failed
provider_response JSON Full API response
metadata JSON Additional context
created_at DateTime Record created
updated_at DateTime Record updated

whatsapp_templates Table

Column Type Description
id UUID Primary key
template_name String WhatsApp template name
template_key String Internal identifier
category String MARKETING, UTILITY, etc.
language String Language code
status String PENDING, APPROVED, REJECTED
body_text Text Template body
parameter_count Integer Number of parameters
sent_count Integer Usage counter
is_active Boolean Active status

Message Flow

Outgoing Message (PO Notification)

1. Purchase Order Approved
   ↓
2. RabbitMQ Event Published
   ↓
3. PO Event Consumer Receives Event
   ↓
4. Extract supplier phone & data
   ↓
5. Build template parameters
   ↓
6. WhatsAppService.send_message()
   ↓
7. WhatsAppBusinessService.send_message()
   ↓
8. Create DB record (PENDING)
   ↓
9. Send to WhatsApp Cloud API
   ↓
10. Update DB record (SENT)
    ↓
11. Return success

Status Updates (Webhook)

1. WhatsApp delivers message
   ↓
2. Meta sends webhook event
   ↓
3. POST /api/v1/whatsapp/webhook
   ↓
4. Parse status update
   ↓
5. Find message in DB
   ↓
6. Update status & timestamps
   ↓
7. Record metrics
   ↓
8. Return 200 OK

Testing Checklist

✅ Before Going Live

  • Meta Business Account created and verified
  • WhatsApp Business phone number registered
  • Permanent access token generated (not temporary)
  • Template po_notification created and APPROVED
  • Webhook URL configured and verified
  • Environment variables set in production
  • Database migration applied
  • Test message sent successfully
  • Webhook events received and processed
  • Supplier phone numbers in correct format (+34...)
  • Monitoring and alerting configured

🧪 Test Commands

# 1. Verify webhook
curl "https://your-domain.com/api/v1/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test"

# 2. Check health
curl https://your-domain.com/api/v1/whatsapp/health

# 3. Check migration
kubectl exec -it deployment/notification-service -- alembic current

# 4. View logs
kubectl logs -f deployment/notification-service | grep WhatsApp

# 5. Check database
psql -U notification_user -d notification_db -c "SELECT * FROM whatsapp_messages LIMIT 5;"

Pricing Summary

Free Tier

  • 1,000 business-initiated conversations/month (FREE)
  • 1,000 user-initiated conversations/month (FREE)

Paid Tier

  • After free tier: €0.01-0.10 per conversation (varies by country)
  • Conversation = 24-hour window
  • Multiple messages in 24h = 1 conversation charge

Cost Example

  • 50 PO notifications/month: FREE
  • 1,500 PO notifications/month: €5-50/month

Backward Compatibility

The implementation maintains full backward compatibility with existing code:

# Existing code still works
whatsapp_service = WhatsAppService()
await whatsapp_service.send_message(
    to_phone="+34612345678",
    message="Test",
    template_name="po_notification",
    template_params=["Supplier", "PO-001", "€100"]
)

New code can use additional features:

# New functionality
from app.services.whatsapp_business_service import WhatsAppBusinessService
from app.schemas.whatsapp import SendWhatsAppMessageRequest

service = WhatsAppBusinessService(session)
request = SendWhatsAppMessageRequest(...)
response = await service.send_message(request)

Next Steps

  1. Follow Setup Guide: Complete all steps in WHATSAPP_SETUP_GUIDE.md
  2. Add Supplier Phones: Ensure supplier records include phone numbers
  3. Create More Templates: Design templates for other notification types
  4. Monitor Usage: Track conversation usage in Meta Business Suite
  5. Set Up Alerts: Configure alerts for failed messages

Support & Resources

Summary

✅ Complete WhatsApp Business Cloud API integration ✅ Free tier: 1,000 messages/month ✅ Template-based notifications ready ✅ PO notifications automated ✅ Delivery tracking enabled ✅ Production-ready documentation

Status: Ready for deployment after Meta account setup