diff --git a/.env.example b/.env.example index 177b70c..2385991 100644 --- a/.env.example +++ b/.env.example @@ -80,4 +80,21 @@ REDIS_DB=0 # Static token for external applications (e.g., Streamlit dashboards) # to access the /api/statistic/* endpoints # Generate with: openssl rand -hex 32 -STATISTIC_API_TOKEN=your_statistic_api_token_here \ No newline at end of file +STATISTIC_API_TOKEN=your_statistic_api_token_here + +# Facebook Messenger Configuration +# Facebook Page ID: From Facebook Page settings (About -> Page ID) or Meta App Dashboard +MESSENGER_PAGE_ID=your_facebook_page_id_here + +# Webhook Verify Token: Custom secret token you enter in Meta App Dashboard (Messenger -> Webhooks) +# Generate with: openssl rand -hex 32 +MESSENGER_VERIFY_TOKEN=agriconnect_messenger_verify_token + +# Page Access Token: Meta Developer Portal -> App Dashboard -> Messenger -> API Setup -> Generate Token +MESSENGER_PAGE_ACCESS_TOKEN=your_page_access_token_here + +# Meta App Secret: Meta Developer Portal -> App Dashboard -> App settings -> Basic -> App secret +MESSENGER_APP_SECRET=your_app_secret_here + +# Meta Graph API Version (default: v21.0) +MESSENGER_GRAPH_API_VERSION=v21.0 \ No newline at end of file diff --git a/README.md b/README.md index c4ea644..a5525d3 100644 --- a/README.md +++ b/README.md @@ -191,6 +191,14 @@ Create a `.env` file based on `.env.example` with the following key variables: - `BROADCAST_BATCH_SIZE` - Recipients per batch (default: 50) - `BROADCAST_RETRY_INTERVALS` - Retry intervals in minutes (default: 5,15,60) +**Facebook Messenger (Opt-in Channel):** +- `MESSENGER_PAGE_ID` - Facebook Page ID +- `MESSENGER_VERIFY_TOKEN` - Webhook verification token +- `MESSENGER_PAGE_ACCESS_TOKEN` - Meta Page Access Token +- `MESSENGER_APP_SECRET` - Meta App Secret for SHA-256 HMAC signature validation +- `MESSENGER_GRAPH_API_VERSION` - Meta Graph API version (default: `v21.0`) +- Channel toggle in `config.json` under `channels.messenger.enabled` (default: `false`) + **Weather Broadcast:** - `GOOGLEWEATHER` - Google Weather API key for weather forecasts - Enable in `config.json`: @@ -210,6 +218,7 @@ See `.env.example` for complete configuration options. Additional documentation is available in the `docs/` directory: +- **[Facebook Messenger Integration](docs/FACEBOOK_MESSENGER_INTEGRATION.md)**: Facebook Messenger webhook ingestion, HMAC validation, channel routing, and configuration guide - **[Broadcast API Core Implementation](docs/BROADCAST_API_CORE_IMPLEMENTATION.md)**: Broadcast messaging system architecture and implementation guide - **[Broadcast API Twilio Integration](docs/BROADCAST_API_TWILIO_INTEGRATION.md)**: Twilio WhatsApp integration and Celery task queue setup - **[Weather Subscription](docs/WEATHER_SUBSCRIPTION.md)**: Weather broadcast feature, subscription flow, and intent detection diff --git a/backend/config.py b/backend/config.py index 5ff2442..5a2480a 100644 --- a/backend/config.py +++ b/backend/config.py @@ -49,6 +49,19 @@ class Settings(BaseSettings): extra="ignore", ) + # Channels configuration + whatsapp_enabled: bool = ( + _config.get("channels", {}).get("whatsapp", {}).get("enabled", True) + ) + messenger_enabled: bool = ( + _config.get("channels", {}).get("messenger", {}).get("enabled", False) + ) + messenger_typing_indicator_enabled: bool = ( + _config.get("channels", {}) + .get("messenger", {}) + .get("typing_indicator_enabled", False) + ) + # Message limit message_limit: int = _config.get("message_limit") @@ -457,7 +470,20 @@ def admin_delimiter(self) -> str: "forecast_days", 6 ) - # Statistic API Token (for external applications like Streamlit dashboards) + # Facebook Messenger Configuration + messenger_page_id: str = os.getenv("MESSENGER_PAGE_ID", "") + messenger_verify_token: str = os.getenv( + "MESSENGER_VERIFY_TOKEN", "agriconnect_messenger_verify_token" + ) + messenger_page_access_token: str = os.getenv( + "MESSENGER_PAGE_ACCESS_TOKEN", "" + ) + messenger_app_secret: str = os.getenv("MESSENGER_APP_SECRET", "") + messenger_graph_api_version: str = os.getenv( + "MESSENGER_GRAPH_API_VERSION", "v21.0" + ) + + # Statistics API Token statistic_api_token: str = os.getenv("STATISTIC_API_TOKEN", "") @property diff --git a/backend/config.template.json b/backend/config.template.json index 7cc24c8..dd69e97 100644 --- a/backend/config.template.json +++ b/backend/config.template.json @@ -1,5 +1,16 @@ { "message_limit": 10, + "channels": { + "whatsapp": { + "enabled": true, + "description": "WhatsApp messaging channel via Twilio / Meta API" + }, + "messenger": { + "enabled": false, + "typing_indicator_enabled": false, + "description": "Facebook Messenger messaging channel (opt-in)" + } + }, "whatsapp": { "templates": { "confirmation": { @@ -73,6 +84,12 @@ "max_tokens": 500, "system_prompt": "You are a helpful agricultural assistant helping farmers get started with AgriConnect. Be friendly, concise, and practical." }, + "follow_up": { + "enabled": true, + "temperature": 0.7, + "max_tokens": 150, + "description": "Ask contextual follow-up question before routing to external AI" + }, "content_moderation": { "enabled": true, "auto_flag": true diff --git a/backend/config.test.template.json b/backend/config.test.template.json index adec254..01263dc 100644 --- a/backend/config.test.template.json +++ b/backend/config.test.template.json @@ -1,5 +1,16 @@ { "message_limit": 10, + "channels": { + "whatsapp": { + "enabled": true, + "description": "WhatsApp messaging channel via Twilio / Meta API" + }, + "messenger": { + "enabled": true, + "typing_indicator_enabled": false, + "description": "Facebook Messenger messaging channel" + } + }, "whatsapp": { "templates": { "confirmation": { @@ -73,6 +84,12 @@ "max_tokens": 500, "system_prompt": "You are a helpful agricultural assistant helping farmers get started with AgriConnect. Be friendly, concise, and practical." }, + "follow_up": { + "enabled": true, + "temperature": 0.7, + "max_tokens": 150, + "description": "Ask contextual follow-up question before routing to external AI" + }, "content_moderation": { "enabled": true, "auto_flag": true @@ -103,9 +120,21 @@ "delimiter": " > ", "levels": [ { "level_index": 0, "name": "country", "display": { "en": "Country" } }, - { "level_index": 1, "name": "region", "display": { "en": "Region", "sw": "Mkoa" } }, - { "level_index": 2, "name": "district", "display": { "en": "District", "sw": "Wilaya" } }, - { "level_index": 3, "name": "ward", "display": { "en": "Ward", "sw": "Kata" } } + { + "level_index": 1, + "name": "region", + "display": { "en": "Region", "sw": "Mkoa" } + }, + { + "level_index": 2, + "name": "district", + "display": { "en": "District", "sw": "Wilaya" } + }, + { + "level_index": 3, + "name": "ward", + "display": { "en": "Ward", "sw": "Kata" } + } ] }, "onboarding": { diff --git a/backend/locales/en.json b/backend/locales/en.json index aa963b4..e52691a 100644 --- a/backend/locales/en.json +++ b/backend/locales/en.json @@ -73,6 +73,8 @@ "deleted": "Your account and all associated data have been deleted. If you message us again, a new account will be created." }, "escalation": { + "question": "Would you like to speak with an extension officer about this?", + "button_escalate": "Talk to Officer", "confirmed": "Your issue has been transferred to extension service provider. Please wait for a response from them. For urgent issues please call:\n{eo_contacts}", "confirmed_no_contacts": "Your issue has been transferred to extension service provider. Please wait for a response from them." }, diff --git a/backend/locales/sw.json b/backend/locales/sw.json index 9f98f9d..24ff935 100644 --- a/backend/locales/sw.json +++ b/backend/locales/sw.json @@ -73,6 +73,8 @@ "deleted": "Akaunti yako na data zote zinazohusiana zimefutwa. Ukitutumia ujumbe tena, akaunti mpya itaundwa." }, "escalation": { + "question": "Je, ungependa kuunganishwa na afisa ugani kuhusu hili?", + "button_escalate": "Wasiliana na Afisa", "confirmed": "Tatizo lako limehamishwa kwa mtoa huduma wa ugani. Tafadhali subiri jibu kutoka kwao. Kwa masuala ya dharura tafadhali piga simu:\n{eo_contacts}", "confirmed_no_contacts": "Tatizo lako limehamishwa kwa mtoa huduma wa ugani. Tafadhali subiri jibu kutoka kwao." }, diff --git a/backend/main.py b/backend/main.py index 601efc9..e1aaa1d 100644 --- a/backend/main.py +++ b/backend/main.py @@ -16,6 +16,7 @@ devices, knowledge_base, messages, + messenger, service_tokens, whatsapp, tickets, @@ -112,6 +113,7 @@ async def lifespan(app: FastAPI): app.include_router(messages.router, prefix="/api") app.include_router(service_tokens.router, prefix="/api") app.include_router(whatsapp.router, prefix="/api") +app.include_router(messenger.router, prefix="/api") app.include_router(tickets.router, prefix="/api") app.include_router(storage.router) app.include_router(crop_types.router, prefix="/api") diff --git a/backend/routers/callbacks.py b/backend/routers/callbacks.py index 23698ff..e75c1c3 100644 --- a/backend/routers/callbacks.py +++ b/backend/routers/callbacks.py @@ -1,5 +1,6 @@ import asyncio import logging +import uuid from fastapi import APIRouter, Depends, HTTPException, status from sqlalchemy.orm import Session from sqlalchemy import func @@ -256,22 +257,52 @@ async def ai_callback( f"Sending AI answer to {ai_message.customer.phone_number}" ) - answer_response = whatsapp_service.send_message_with_tracking( - to_number=ai_message.customer.phone_number, - message_body=WhatsAppService.sanitize_whatsapp_content( - ai_response_text - ), - message_id=ai_message.id, - db=db, - ) + if ai_message.customer.phone_number.startswith( + "messenger:" + ): + psid = ( + ai_message.customer.phone_number.replace( + "messenger:", "" + ) + ) + from services.messenger_service import ( + MessengerService, + ) - # Update message with real Twilio SID - ai_message.message_sid = answer_response["sid"] - ai_message.delivery_status = DeliveryStatus.SENT + msgr_svc = MessengerService() + msgr_res = msgr_svc.send_message( + recipient_psid=psid, + text=ai_response_text, + ) + ai_message.message_sid = msgr_res.get( + "message_id", + f"mid.msgr.{uuid.uuid4().hex[:16]}", + ) + ai_message.delivery_status = ( + DeliveryStatus.SENT + ) + logger.info( + f"✓ AI answer sent via Messenger to {psid}" + ) + else: + answer_response = whatsapp_service.send_message_with_tracking( + to_number=ai_message.customer.phone_number, + message_body=WhatsAppService.sanitize_whatsapp_content( + ai_response_text + ), + message_id=ai_message.id, + db=db, + ) - logger.info( - f"✓ AI answer sent successfully: {answer_response['sid']}" - ) + # Update message with real Twilio SID + ai_message.message_sid = answer_response["sid"] + ai_message.delivery_status = ( + DeliveryStatus.SENT + ) + + logger.info( + f"✓ AI answer sent successfully: {answer_response['sid']}" + ) # Step 2: Send confirmation template only if citations exist and escalation is enabled # Citations indicate the response is from knowledge base @@ -282,7 +313,16 @@ async def ai_callback( and len(payload.output.citations) > 0 ) - if settings.escalation_enabled and has_citations: + is_messenger = ( + ai_message.customer.phone_number.startswith( + "messenger:" + ) + ) + if ( + not is_messenger + and settings.escalation_enabled + and has_citations + ): # Select template based on customer's language customer_lang = ( ai_message.customer.language_code @@ -308,13 +348,59 @@ async def ai_callback( f"Failed to send confirmation template (non-critical): {e}" ) # Template failure is non-fatal + elif ( + is_messenger + and settings.escalation_enabled + and has_citations + ): + customer_lang = ( + ai_message.customer.language_code + ) + escalate_question = t( + "escalation.question", customer_lang + ) + escalate_btn = t( + "escalation.button_escalate", customer_lang + ) + try: + from services.messenger_service import ( + MessengerService, + ) + + msgr_svc = MessengerService() + psid = ai_message.customer.phone_number.replace( + "messenger:", "" + ) + msgr_svc.send_quick_replies( + recipient_psid=psid, + text=escalate_question, + options=[ + { + "title": escalate_btn[:20], + "payload": ( + settings.whatsapp_escalate_button_payload + ), + } + ], + ) + logger.info( + "✓ Escalation quick reply sent via " + f"Messenger to {psid}" + ) + except Exception as e: + logger.warning( + "Failed to send Messenger escalation " + f"quick reply (non-critical): {e}" + ) elif not settings.escalation_enabled: logger.info( - "Skipping confirmation template: escalation is disabled in configuration" + "Skipping confirmation template: " + "escalation is disabled in configuration" ) else: logger.info( - "Skipping confirmation template: no citations in AI response" + "Skipping confirmation template: no " + "citations in AI response" ) # CRITICAL: Only commit if WhatsApp send succeeded @@ -331,15 +417,22 @@ async def ai_callback( f"✓ AI message {ai_message.id} delivered and committed" ) - except (TwilioRestException, ValueError) as e: - # CRITICAL: Rollback on Twilio/validation failure - logger.error(f"✗ WhatsApp delivery failed: {e}") + except ( + TwilioRestException, + ValueError, + Exception, + ) as e: + # CRITICAL: Rollback on channel delivery failure + logger.error( + f"✗ Outbound delivery failed: {e}", + exc_info=True, + ) message_service.rollback_message(ai_message) return { "status": "error", "job_id": payload.job_id, - "error": f"WhatsApp delivery failed: {str(e)}", + "error": f"Delivery failed: {str(e)}", } elif ( diff --git a/backend/routers/messages.py b/backend/routers/messages.py index c1385a6..4513c01 100644 --- a/backend/routers/messages.py +++ b/backend/routers/messages.py @@ -17,7 +17,7 @@ from services.whatsapp_service import WhatsAppService from services.socketio_service import ( emit_message_received, - emit_ticket_resolved + emit_ticket_resolved, ) router = APIRouter(prefix="/messages", tags=["messages"]) @@ -86,11 +86,7 @@ class MessageResponse(BaseModel): def _check_message_access(message: Message, user: User, db: Session) -> None: """Check if user has access to update the message. Raises 403 if not.""" # Get the ticket associated with this message - ticket = ( - db.query(Ticket) - .filter(Ticket.message_id == message.id) - .first() - ) + ticket = db.query(Ticket).filter(Ticket.message_id == message.id).first() if not ticket: raise HTTPException( @@ -223,11 +219,7 @@ async def update_message_status( _check_message_access(message, current_user, db) # Get associated ticket - ticket = ( - db.query(Ticket) - .filter(Ticket.message_id == message.id) - .first() - ) + ticket = db.query(Ticket).filter(Ticket.message_id == message.id).first() # Update message status message.status = status_update.status @@ -253,11 +245,7 @@ async def update_message_status( ) # Get media_type value as string - msg_media_type = ( - message.media_type.value - if message.media_type - else "TEXT" - ) + msg_media_type = message.media_type.value if message.media_type else "TEXT" return MessageResponse( id=message.id, @@ -294,9 +282,7 @@ async def create_message( """ # Get ticket ticket = ( - db.query(Ticket) - .filter(Ticket.id == message_data.ticket_id) - .first() + db.query(Ticket).filter(Ticket.id == message_data.ticket_id).first() ) if not ticket: raise HTTPException(status_code=404, detail="Ticket not found") @@ -386,47 +372,69 @@ async def create_message( f"{new_message.body}\n\n— _{current_user.full_name}_" ) - # Check if this is a media message - if message_data.media_url and message_data.media_type == "IMAGE": - # Build full public URL for the media - web_domain = os.getenv("WEBDOMAIN", "http://localhost:8000") - # Ensure web_domain has a scheme - if not web_domain.startswith(("http://", "https://")): - web_domain = f"https://{web_domain}" - # Ensure no double slashes when joining - media_path = message_data.media_url.lstrip("/") - full_media_url = f"{web_domain.rstrip('/')}/{media_path}" - - response = whatsapp_service.send_message_with_media( - to_number=customer_phone, - message_body=formatted_body, - media_url=full_media_url, + if customer_phone.startswith("messenger:"): + from services.messenger_service import MessengerService + + messenger_service = MessengerService() + psid = customer_phone.replace("messenger:", "") + response = messenger_service.send_message( + recipient_psid=psid, + text=formatted_body, ) print( - f"WhatsApp image sent to {customer_phone}: " - f"{response.get('sid')} (media: {full_media_url})" + f"Messenger reply sent to {customer_phone}: " + f"{response.get('message_id')}" ) + if response.get("message_id"): + new_message.message_sid = response.get("message_id") + db.commit() + db.refresh(new_message) else: - response = whatsapp_service.send_message( - to_number=customer_phone, - message_body=formatted_body, - ) - print( - f"WhatsApp reply sent to {customer_phone}: " - f"{response.get('sid')}" - ) - - # Optional: Update message_sid with Twilio SID for tracking - # This helps correlate backend messages with Twilio messages - if response.get("sid"): - new_message.message_sid = response.get("sid") - db.commit() - db.refresh(new_message) + # Check if this is a media message + if ( + message_data.media_url + and message_data.media_type == "IMAGE" + ): + # Build full public URL for the media + web_domain = os.getenv( + "WEBDOMAIN", "http://localhost:8000" + ) + # Ensure web_domain has a scheme + if not web_domain.startswith(("http://", "https://")): + web_domain = f"https://{web_domain}" + # Ensure no double slashes when joining + media_path = message_data.media_url.lstrip("/") + full_media_url = f"{web_domain.rstrip('/')}/{media_path}" + + response = whatsapp_service.send_message_with_media( + to_number=customer_phone, + message_body=formatted_body, + media_url=full_media_url, + ) + print( + f"WhatsApp image sent to {customer_phone}: " + f"{response.get('sid')} (media: {full_media_url})" + ) + else: + response = whatsapp_service.send_message( + to_number=customer_phone, + message_body=formatted_body, + ) + print( + f"WhatsApp reply sent to {customer_phone}: " + f"{response.get('sid')}" + ) + + # Optional: Update message_sid with Twilio SID for tracking + if response.get("sid"): + new_message.message_sid = response.get("sid") + db.commit() + db.refresh(new_message) except Exception as e: # Log error but don't fail the request # Message is already saved in DB and can be retried later - print(f"Failed to send WhatsApp reply: {e}") + print(f"Failed to send reply to {customer_phone}: {e}") # TODO: Implement retry queue or dead letter queue for failed sends # Emit WebSocket event for new message @@ -461,9 +469,7 @@ async def create_message( # Get media_type value as string media_type_value = ( - new_message.media_type.value - if new_message.media_type - else "TEXT" + new_message.media_type.value if new_message.media_type else "TEXT" ) return MessageResponse( diff --git a/backend/routers/messenger.py b/backend/routers/messenger.py new file mode 100644 index 0000000..a49379a --- /dev/null +++ b/backend/routers/messenger.py @@ -0,0 +1,757 @@ +""" +Facebook Messenger Webhook & Compliance Endpoints. + +Handles: +- Webhook verification handshake (GET /api/messenger/webhook) +- Inbound message processing & dispatching (POST /api/messenger/webhook) +- In-chat customer deletion +- Meta Platform User Data Deletion callback (POST /api/messenger/data-deletion) +- Deletion status lookup (GET /api/messenger/data-deletion/status) +""" + +import asyncio +import json +import logging +import os +import uuid +from typing import Optional + +from fastapi import APIRouter, Depends, HTTPException, Query, Request, status +from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse +from sqlalchemy.exc import IntegrityError +from sqlalchemy.orm import Session + +from config import settings +from database import get_db +from models.administrative import Administrative +from models.message import ( + MediaType, + Message, + MessageFrom, + MessageStatus, +) +from models.ticket import Ticket +from schemas.callback import MessageType +from services.administrative_service import AdministrativeService +from services.customer_service import CustomerService +from services.external_ai_service import get_external_ai_service +from services.follow_up_service import get_follow_up_service +from services.messenger_service import MessengerService +from services.onboarding_service import get_onboarding_service +from services.socketio_service import emit_message_received +from utils.i18n import t + +router = APIRouter(prefix="/messenger", tags=["messenger"]) +logger = logging.getLogger(__name__) + +# Standard deletion & confirmation keywords (EN & SW) +DELETE_KEYWORDS = [ + "delete", + "delete account", + "futa", + "futa akaunti", + "ondoa", + "ondoa akaunti", +] +CONFIRM_RESPONSES = [ + "yes", + "y", + "yeah", + "yep", + "sure", + "okay", + "ok", + "ndio", + "ndiyo", + "sawa", + "confirm", +] + + +@router.get("/webhook") +async def verify_webhook( + hub_mode: Optional[str] = Query(None, alias="hub.mode"), + hub_verify_token: Optional[str] = Query(None, alias="hub.verify_token"), + hub_challenge: Optional[str] = Query(None, alias="hub.challenge"), +): + """ + Handle Meta Messenger webhook verification handshake. + + Meta requires raw plain-text challenge return with HTTP 200. + """ + if not settings.messenger_enabled: + logger.warning("✗ Meta Messenger channel is disabled in configuration") + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="Messenger channel is disabled", + ) + + if hub_mode == "subscribe" and hub_verify_token: + configured_token = settings.messenger_verify_token + if hub_verify_token == configured_token: + logger.info("✓ Meta Messenger webhook verified successfully") + return PlainTextResponse( + content=str(hub_challenge), status_code=status.HTTP_200_OK + ) + + logger.warning("✗ Meta Messenger webhook verification failed") + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="Verification token mismatch or invalid mode", + ) + + +@router.post("/webhook") +async def handle_messenger_event( + request: Request, + db: Session = Depends(get_db), +): + """Handle incoming messages and events from Facebook Messenger.""" + if not settings.messenger_enabled: + logger.warning("✗ Meta Messenger channel is disabled in configuration") + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="Messenger channel is disabled", + ) + + raw_body = await request.body() + signature = request.headers.get("X-Hub-Signature-256") + + messenger_service = MessengerService() + + # Verify HMAC-SHA256 signature + if settings.messenger_app_secret and not ( + messenger_service.verify_signature(raw_body, signature) + ): + logger.warning( + "✗ Invalid Messenger webhook signature. " + f"Signature header present: {bool(signature)}" + ) + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="Invalid webhook signature", + ) + + try: + data = json.loads(raw_body.decode("utf-8")) + except Exception as e: + logger.error(f"Failed to parse Messenger JSON payload: {e}") + return JSONResponse( + content={"status": "invalid_json"}, status_code=200 + ) + + if data.get("object") != "page": + return JSONResponse(content={"status": "ignored"}, status_code=200) + + customer_service = CustomerService(db) + + entries = data.get("entry", []) + processed_count = 0 + + for entry in entries: + # Filter by Page ID if configured + if settings.messenger_page_id: + page_id = str(entry.get("id", "")) + if page_id and page_id != str(settings.messenger_page_id): + logger.info( + "Ignoring Messenger event for unconfigured page: " + f"{page_id}" + ) + continue + + messaging_events = entry.get("messaging", []) + for event in messaging_events: + # Filter by recipient ID if configured + if settings.messenger_page_id: + recipient_id = str(event.get("recipient", {}).get("id", "")) + if recipient_id and recipient_id != str( + settings.messenger_page_id + ): + logger.info( + "Ignoring event for unconfigured recipient: " + f"{recipient_id}" + ) + continue + + # Skip echo messages and delivery/read receipts + message_obj = event.get("message") + if not message_obj or message_obj.get("is_echo"): + continue + + if event.get("delivery") or event.get("read"): + continue + + sender_id = event.get("sender", {}).get("id") + if not sender_id: + continue + + # Extract message text or quick reply / postback payload + text_body = message_obj.get("text", "") + if message_obj.get("quick_reply"): + text_body = message_obj["quick_reply"].get( + "payload", text_body + ) + elif event.get("postback"): + text_body = event["postback"].get("payload", text_body) + + text_body = text_body.strip() + if not text_body: + continue + + # Extract message identifier & check deduplication + mid_val = message_obj.get( + "mid", f"mid.msgr.{uuid.uuid4().hex[:16]}" + ) + existing_message = ( + db.query(Message) + .filter(Message.message_sid == mid_val) + .first() + ) + if existing_message: + logger.info(f"Skipping duplicate Messenger message: {mid_val}") + continue + + processed_count += 1 + phone_identifier = f"messenger:{sender_id}" + + # Get or create customer for this PSID + customer = customer_service.get_or_create_customer( + phone_number=phone_identifier + ) + lang = customer.language_code or "sw" + body_lower = text_body.lower() + + # Record customer inbound message immediately for idempotency + inbound_message = Message( + message_sid=mid_val, + customer_id=customer.id, + body=text_body, + from_source=MessageFrom.CUSTOMER, + status=MessageStatus.PENDING, + media_type=MediaType.TEXT, + ) + db.add(inbound_message) + try: + db.commit() + db.refresh(inbound_message) + except IntegrityError: + db.rollback() + logger.info( + "Concurrent duplicate Messenger message ignored: " + f"{mid_val}" + ) + continue + + # Handle In-Chat Deletion Flow + if customer.delete_requested: + if body_lower in CONFIRM_RESPONSES: + # Notify user before deleting + messenger_service.send_message( + recipient_psid=sender_id, + text=t("account.deleted", lang), + ) + customer_service.delete_customer(customer.id) + logger.info( + f"Customer {phone_identifier} confirmed deletion" + ) + return JSONResponse( + content={"status": "deleted"}, status_code=200 + ) + else: + # Cancel deletion request + customer.delete_requested = False + db.commit() + + if body_lower in DELETE_KEYWORDS: + customer.delete_requested = True + db.commit() + messenger_service.send_message( + recipient_psid=sender_id, + text=t("account.delete_confirmation", lang), + ) + logger.info( + f"Customer {phone_identifier} initiated deletion request" + ) + return JSONResponse( + content={"status": "delete_requested"}, status_code=200 + ) + + # Check Onboarding Flow + onboarding_service = get_onboarding_service(db) + if onboarding_service.needs_onboarding(customer): + onboarding_response = ( + await onboarding_service.process_onboarding_message( + customer=customer, message=text_body + ) + ) + + if ( + onboarding_response.candidates + and len(onboarding_response.candidates) > 0 + ): + options = [ + {"title": c.name[:20], "payload": str(c.id)} + for c in onboarding_response.candidates[:10] + ] + messenger_service.send_quick_replies( + recipient_psid=sender_id, + text=onboarding_response.message, + options=options, + ) + else: + messenger_service.send_message( + recipient_psid=sender_id, + text=onboarding_response.message, + ) + continue + + # Handle Escalation Button / Quick Reply Response + escalate_payload = settings.whatsapp_escalate_button_payload + if text_body == escalate_payload or body_lower == "escalate": + if not settings.escalation_enabled: + logger.info( + f"Customer {phone_identifier} clicked 'escalate' " + "button, but escalation feature is disabled in " + "configuration" + ) + return JSONResponse( + content={ + "status": "ignored", + "message": "Escalation feature is disabled", + }, + status_code=200, + ) + + logger.info( + f"Customer {phone_identifier} clicked 'escalate' button" + ) + + # Find the previous question (latest customer message minus + # the current escalate message) + message = ( + db.query(Message) + .filter( + Message.customer_id == customer.id, + Message.from_source == MessageFrom.CUSTOMER, + Message.id != inbound_message.id, + ) + .order_by(Message.created_at.desc()) + .first() + ) + + if not message: + message = inbound_message + + # Update message status to ESCALATED + message.status = MessageStatus.ESCALATED + + # Find or create ticket + ticket = ( + db.query(Ticket) + .filter( + Ticket.customer_id == customer.id, + Ticket.resolved_at.is_(None), + ) + .first() + ) + + is_new_ticket = False + if not ticket: + ticket = customer_service.create_ticket_for_customer( + customer=customer, message_id=message.id + ) + is_new_ticket = True + + if ticket: + chat_history_limit = settings.escalation_chat_history_limit + chat_history = ( + db.query(Message) + .filter(Message.customer_id == customer.id) + .filter(Message.created_at <= message.created_at) + .order_by(Message.created_at.desc()) + .limit(chat_history_limit) + .all() + ) + + chats = [] + for msg in reversed(chat_history): + if msg.from_source == MessageFrom.CUSTOMER: + role = "user" + elif msg.from_source in ( + MessageFrom.USER, + MessageFrom.LLM, + ): + role = "assistant" + else: + continue + chats.append({"role": role, "content": msg.body}) + + chats.append( + { + "role": "user", + "content": ( + "Based on this conversation, " + "please give an answer with " + "the context we have provided" + ), + } + ) + + if not os.getenv("TESTING") and not is_new_ticket: + ai_service = get_external_ai_service(db) + asyncio.create_task( + ai_service.create_chat_job( + message_id=message.id, + message_type=MessageType.WHISPER.value, + customer_id=customer.id, + ticket_id=ticket.id, + administrative_id=ticket.administrative_id, + chats=chats, + trace_id=f"whisper_t{ticket.id}_m{message.id}", + ) + ) + + ward_id = None + national_adm = ( + db.query(Administrative) + .filter(Administrative.parent_id.is_(None)) + .first() + ) + if national_adm: + ward_id = national_adm.id + if ( + hasattr(customer, "customer_administrative") + and len(customer.customer_administrative) > 0 + ): + ward_id = customer.customer_administrative[ + 0 + ].administrative_id + + sender_name = customer.phone_number + if customer.full_name: + sender_name = customer.full_name + + asyncio.create_task( + emit_message_received( + ticket_id=ticket.id, + message_id=message.id, + phone_number=customer.phone_number, + body=message.body, + from_source=MessageFrom.CUSTOMER, + ts=message.created_at.isoformat(), + administrative_id=ward_id, + ticket_number=ticket.ticket_number, + sender_name=sender_name, + sender_user_id=None, + customer_id=customer.id, + media_url=message.media_url, + media_type=( + message.media_type.value + if message.media_type + else "TEXT" + ), + ) + ) + + ward_id = None + if ( + hasattr(customer, "customer_administrative") + and len(customer.customer_administrative) > 0 + ): + ward_id = customer.customer_administrative[ + 0 + ].administrative_id + + eo_list = ( + AdministrativeService.get_extension_officers_for_area( + db=db, + administrative_id=ward_id, + min_count=2, + randomize=True, + ) + ) + + if eo_list: + eo_contacts = "\n".join( + [ + f"- {eo.full_name}: {eo.phone_number}" + for eo in eo_list + ] + ) + confirmation_msg = t( + "escalation.confirmed", + lang, + eo_contacts=eo_contacts, + ) + else: + confirmation_msg = t( + "escalation.confirmed_no_contacts", + lang, + ) + + messenger_service.send_message( + recipient_psid=sender_id, + text=confirmation_msg, + ) + logger.info( + "Sent escalation confirmation via Messenger to " + f"{phone_identifier} with {len(eo_list)} EO contacts" + ) + return JSONResponse( + content={ + "status": "success", + "message": "Escalation processed", + }, + status_code=200, + ) + + # Handle Weather Subscription Responses + weather_yes_payload = settings.weather_yes_payload + weather_no_payload = settings.weather_no_payload + is_weather_yes = ( + text_body == weather_yes_payload + or body_lower in ["1", "yes", "ndio", "ndiyo"] + ) + is_weather_no = text_body == weather_no_payload or body_lower in [ + "2", + "no", + "hapana", + ] + + if ( + customer.weather_subscription_asked + and customer.weather_subscribed is not True + and (is_weather_yes or is_weather_no) + ): + logger.info( + f"Customer {phone_identifier} responded to weather " + f"subscription: {'yes' if is_weather_yes else 'no'}" + ) + from services.weather_subscription_service import ( + get_weather_subscription_service, + ) + + weather_service = get_weather_subscription_service(db) + if is_weather_yes: + weather_service.subscribe(customer) + response_msg = weather_service.get_confirmation_message( + customer, subscribed=True, lang=lang + ) + else: + weather_service.decline(customer) + response_msg = weather_service.get_confirmation_message( + customer, subscribed=False, lang=lang + ) + + messenger_service.send_message( + recipient_psid=sender_id, text=response_msg + ) + return JSONResponse( + content={ + "status": "success", + "message": "Weather subscription processed", + }, + status_code=200, + ) + + # Handle Weather Intent from Farmers + from services.weather_intent_service import ( + get_weather_intent_service, + ) + + weather_intent_service = get_weather_intent_service(db) + existing_ticket = ( + db.query(Ticket) + .filter( + Ticket.customer_id == customer.id, + Ticket.resolved_at.is_(None), + ) + .first() + ) + has_weather = weather_intent_service.has_weather_intent(text_body) + can_handle = weather_intent_service.can_handle( + customer, bool(existing_ticket) + ) + if has_weather and can_handle: + logger.info( + f"Weather intent detected from {phone_identifier}: " + f"{text_body[:50]}..." + ) + result = await weather_intent_service.handle_weather_intent( + customer=customer, + phone_number=phone_identifier, + ) + if result.handled: + return JSONResponse( + content={ + "status": "success", + "message": result.message, + }, + status_code=200, + ) + + # Send typing indicator while AI is processing (if enabled) + if settings.messenger_typing_indicator_enabled: + try: + messenger_service.send_typing_indicator( + recipient_psid=sender_id, is_typing=True + ) + except Exception as e: + logger.debug( + f"Typing indicator skipped (non-critical): {e}" + ) + + # Get recent chat history for context + reply_history_limit = settings.escalation_reply_history_limit + chat_history = ( + db.query(Message) + .filter(Message.customer_id == customer.id) + .filter(Message.created_at <= inbound_message.created_at) + .order_by(Message.created_at.desc()) + .limit(reply_history_limit) + .all() + ) + + # Check if we should ask a follow-up question first + if settings.follow_up_enabled and not os.getenv("TESTING"): + follow_up_service = get_follow_up_service(db) + should_ask = follow_up_service.should_ask_follow_up( + customer, chat_history + ) + if should_ask: + follow_up_message = await follow_up_service.ask_follow_up( + customer=customer, + original_message=inbound_message, + phone_number=phone_identifier, + ) + if follow_up_message: + continue + + # Format chat history for External AI Service + chats = [] + for msg in reversed(chat_history): + if msg.from_source == MessageFrom.CUSTOMER: + role = "user" + elif msg.from_source in (MessageFrom.USER, MessageFrom.LLM): + role = "assistant" + else: + continue + chats.append({"role": role, "content": msg.body}) + + # Create AI chat job if not in test environment + if not os.getenv("TESTING"): + ai_service = get_external_ai_service(db) + asyncio.create_task( + ai_service.create_chat_job( + message_id=inbound_message.id, + message_type=MessageType.REPLY.value, + customer_id=customer.id, + chats=chats, + trace_id=f"reply_c{customer.id}_m{inbound_message.id}", + ) + ) + + if processed_count == 0: + return JSONResponse(content={"status": "ignored"}, status_code=200) + + return JSONResponse(content={"status": "success"}, status_code=200) + + +@router.post("/data-deletion") +async def meta_data_deletion_callback( + request: Request, + db: Session = Depends(get_db), +): + """ + Handle Meta Platform User Data Deletion Callback. + + Parses signed_request, deletes user data, and returns tracking URL. + """ + if not settings.messenger_enabled: + logger.warning("✗ Meta Messenger channel is disabled in configuration") + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="Messenger channel is disabled", + ) + + form_data = {} + try: + form = await request.form() + form_data = dict(form) + except Exception: + pass + + if not form_data: + try: + form_data = await request.json() + except Exception: + pass + + signed_request = form_data.get("signed_request") + messenger_service = MessengerService() + + payload_data = messenger_service.parse_signed_request(signed_request) + if not payload_data or "user_id" not in payload_data: + logger.warning("✗ Meta data deletion request invalid or unauthorized") + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="Invalid signed_request in data deletion callback", + ) + + user_psid = payload_data["user_id"] + customer_service = CustomerService(db) + + # Find customer with phone_number = messenger: + customer = customer_service.get_customer_by_phone(f"messenger:{user_psid}") + if customer: + customer_service.delete_customer(customer.id) + logger.info( + f"✓ Purged data for Meta user {user_psid} on platform request" + ) + + confirmation_code = f"DEL-{uuid.uuid4().hex[:10].upper()}" + base_url = getattr(settings, "webdomain", "http://localhost:8000") + if not base_url.startswith("http"): + base_url = f"https://{base_url}" + + status_url = ( + f"{base_url}/api/messenger/data-deletion/status" + f"?code={confirmation_code}" + ) + + return JSONResponse( + content={ + "url": status_url, + "confirmation_code": confirmation_code, + }, + status_code=status.HTTP_200_OK, + ) + + +@router.get("/data-deletion/status") +async def meta_data_deletion_status( + code: str = Query(..., description="Confirmation Code"), +): + """Renders status check response for Meta Data Deletion compliance.""" + html_content = ( + "" + "Data Deletion Status - AgriConnect" + "
' + "

AgriConnect Data Deletion

" + '
✓ Deletion Request Completed
' + "

Your user profile and associated conversational records " + "have been permanently purged.

" + f'

Confirmation Code: {code}

' + "
" + ) + return HTMLResponse(content=html_content, status_code=status.HTTP_200_OK) diff --git a/backend/routers/whatsapp.py b/backend/routers/whatsapp.py index 4747a6c..89bdea1 100644 --- a/backend/routers/whatsapp.py +++ b/backend/routers/whatsapp.py @@ -4,7 +4,7 @@ import uuid from typing import Annotated, Optional -from fastapi import APIRouter, Depends, Form, HTTPException +from fastapi import APIRouter, Depends, Form, HTTPException, status from sqlalchemy.orm import Session from config import settings @@ -60,6 +60,13 @@ async def whatsapp_webhook( Flow 2: Regular message → Process normally Flow 3: Button "escalate" → Create ticket + WHISPER job (AI suggests to EO) """ + if not settings.whatsapp_enabled: + logger.warning("✗ WhatsApp channel is disabled in configuration") + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="WhatsApp channel is disabled", + ) + try: phone_number = From.replace("whatsapp:", "") media_url = None diff --git a/backend/services/follow_up_service.py b/backend/services/follow_up_service.py index 8d88dfc..371adc3 100644 --- a/backend/services/follow_up_service.py +++ b/backend/services/follow_up_service.py @@ -70,6 +70,7 @@ @dataclass class FarmerContext: """Context information about the farmer for personalized follow-ups.""" + name: Optional[str] = None language: str = "en" crop_type: Optional[str] = None @@ -112,9 +113,7 @@ def _get_farmer_context(self, customer: Customer) -> FarmerContext: ) def should_ask_follow_up( - self, - customer: Customer, - chat_history: List[Message] + self, customer: Customer, chat_history: List[Message] ) -> bool: """ Determine if a follow-up question should be asked. @@ -131,6 +130,14 @@ def should_ask_follow_up( Returns: bool: True if follow-up should be asked """ + # Check if follow-up feature is enabled in configuration + if not settings.follow_up_enabled: + logger.info( + f"[FollowUp] Feature disabled in config for customer " + f"{customer.id}, skipping" + ) + return False + # Find last FOLLOW_UP in chat history last_follow_up = None for msg in chat_history: @@ -184,9 +191,7 @@ def should_ask_follow_up( return False async def generate_follow_up_question( - self, - customer: Customer, - original_question: str + self, customer: Customer, original_question: str ) -> Optional[str]: """ Generate a follow-up question using OpenAI. @@ -299,23 +304,41 @@ async def ask_follow_up( self.db.flush() try: - # Send via WhatsApp - result = self.whatsapp_service.send_message( - to_number=phone_number, - message_body=follow_up_text, - ) + if phone_number.startswith("messenger:"): + psid = phone_number.replace("messenger:", "") + from services.messenger_service import MessengerService + + msgr_svc = MessengerService() + result = msgr_svc.send_message( + recipient_psid=psid, + text=follow_up_text, + ) + follow_up_message.message_sid = result.get( + "message_id", message_sid + ) + follow_up_message.delivery_status = DeliveryStatus.SENT + logger.info( + f"[FollowUp] Sent follow-up via Messenger to {psid}: " + f"{follow_up_message.message_sid}" + ) + else: + # Send via WhatsApp + result = self.whatsapp_service.send_message( + to_number=phone_number, + message_body=follow_up_text, + ) + + # Update with real Twilio SID + follow_up_message.message_sid = result.get("sid", message_sid) + follow_up_message.delivery_status = DeliveryStatus.SENT - # Update with real Twilio SID - follow_up_message.message_sid = result.get("sid", message_sid) - follow_up_message.delivery_status = DeliveryStatus.SENT + logger.info( + f"[FollowUp] Sent follow-up to {phone_number}: " + f"{result.get('sid')}" + ) self.db.commit() self.db.refresh(follow_up_message) - - logger.info( - f"[FollowUp] Sent follow-up to {phone_number}: " - f"{result.get('sid')}" - ) return follow_up_message except Exception as e: diff --git a/backend/services/messenger_service.py b/backend/services/messenger_service.py new file mode 100644 index 0000000..20c527b --- /dev/null +++ b/backend/services/messenger_service.py @@ -0,0 +1,260 @@ +""" +Facebook Messenger Service. + +Provides outbound messaging, quick replies, typing indicators, +webhook HMAC-SHA256 signature verification, and Meta platform +signed_request data deletion decoding for Facebook Messenger. +""" + +import base64 +import hashlib +import hmac +import json +import logging +import os +import uuid +from typing import Any, Dict, List, Optional + +import requests + +from config import settings + +logger = logging.getLogger(__name__) + + +class MessengerService: + """Service for interacting with Meta Graph API for Facebook Messenger.""" + + def __init__( + self, + page_access_token: Optional[str] = None, + app_secret: Optional[str] = None, + api_version: Optional[str] = None, + is_testing: Optional[bool] = None, + ): + if is_testing is not None: + self.is_testing = is_testing + else: + self.is_testing = os.getenv("TEST", "").lower() in ( + "true", + "1", + ) or os.getenv("TESTING", "").lower() in ("true", "1") + + self.page_access_token = ( + page_access_token + if page_access_token is not None + else settings.messenger_page_access_token + ) + self.app_secret = ( + app_secret + if app_secret is not None + else settings.messenger_app_secret + ) + self.api_version = ( + api_version + if api_version is not None + else settings.messenger_graph_api_version + ) + self.base_url = f"https://graph.facebook.com/{self.api_version}" + + def verify_signature( + self, payload_bytes: bytes, signature_header: Optional[str] + ) -> bool: + """ + Verify incoming webhook X-Hub-Signature-256 header. + + Uses timing-attack safe comparison via hmac.compare_digest. + """ + if self.is_testing and not self.app_secret: + return True + + if not signature_header or not signature_header.startswith("sha256="): + logger.warning( + f"Missing or malformed signature header: {signature_header}" + ) + return False + + if not self.app_secret: + logger.warning( + "MESSENGER_APP_SECRET is not configured for signature check" + ) + return False + + expected_sig = hmac.new( + self.app_secret.encode("utf-8"), + payload_bytes, + hashlib.sha256, + ).hexdigest() + + provided_sig = signature_header.split("sha256=")[1] + matches = hmac.compare_digest(expected_sig, provided_sig) + if not matches: + logger.warning( + "HMAC-SHA256 signature mismatch. Please verify that " + "MESSENGER_APP_SECRET in .env exactly matches the App Secret " + "in your Meta App settings (Basic Settings -> App Secret)." + ) + return matches + + def parse_signed_request( + self, signed_request: Optional[str] + ) -> Optional[Dict[str, Any]]: + """ + Parse and verify Meta signed_request for platform data deletion. + + Format: . + """ + if not signed_request or "." not in signed_request: + return None + + try: + encoded_sig, encoded_payload = signed_request.split(".", 1) + + # Fix base64url padding + padded_payload = encoded_payload + "=" * ( + -len(encoded_payload) % 4 + ) + padded_sig = encoded_sig + "=" * (-len(encoded_sig) % 4) + + sig = base64.urlsafe_b64decode(padded_sig.encode("utf-8")) + payload_bytes = base64.urlsafe_b64decode( + padded_payload.encode("utf-8") + ) + data = json.loads(payload_bytes.decode("utf-8")) + + if self.is_testing and not self.app_secret: + return data + + if not self.app_secret: + logger.warning( + "MESSENGER_APP_SECRET is not configured for signed request" + ) + return None + + expected_sig = hmac.new( + self.app_secret.encode("utf-8"), + encoded_payload.encode("utf-8"), + hashlib.sha256, + ).digest() + + if not hmac.compare_digest(sig, expected_sig): + logger.warning( + "Invalid signature in Meta signed_request payload" + ) + return None + + return data + except Exception as e: + logger.error(f"Error parsing signed_request: {e}") + return None + + def send_message(self, recipient_psid: str, text: str) -> Dict[str, Any]: + """Send a standard text message to a Facebook Messenger user.""" + if self.is_testing: + mock_mid = f"mid.test.{uuid.uuid4().hex[:12]}" + logger.info( + f"[TEST MODE] Messenger sent to {recipient_psid}: {text[:50]}" + ) + return {"recipient_id": recipient_psid, "message_id": mock_mid} + + # Meta Messenger text length limit is 2000 characters + # Chunk text if necessary + chunks = [ + text[i : i + 2000] # noqa + for i in range(0, max(len(text), 1), 2000) + ] + last_response: Dict[str, Any] = {} + + for chunk in chunks: + url = ( + f"{self.base_url}/me/messages" + f"?access_token={self.page_access_token}" + ) + payload = { + "recipient": {"id": recipient_psid}, + "messaging_type": "RESPONSE", + "message": {"text": chunk}, + } + + response = requests.post(url, json=payload, timeout=10) + if response.status_code >= 400: + logger.error( + f"Meta Graph API error ({response.status_code}): " + f"{response.text}" + ) + response.raise_for_status() + last_response = response.json() + + return last_response + + def send_quick_replies( + self, + recipient_psid: str, + text: str, + options: List[Dict[str, str]], + ) -> Dict[str, Any]: + """Send a message with Quick Reply buttons.""" + if self.is_testing: + mock_mid = f"mid.test.{uuid.uuid4().hex[:12]}" + logger.info( + f"[TEST MODE] Messenger quick replies sent to {recipient_psid}" + ) + return {"recipient_id": recipient_psid, "message_id": mock_mid} + + quick_replies = [ + { + "content_type": "text", + "title": opt.get("title", "")[:20], + "payload": opt.get("payload", "")[:1000], + } + for opt in options + ] + + url = ( + f"{self.base_url}/me/messages" + f"?access_token={self.page_access_token}" + ) + payload = { + "recipient": {"id": recipient_psid}, + "messaging_type": "RESPONSE", + "message": { + "text": text[:2000], + "quick_replies": quick_replies, + }, + } + + response = requests.post(url, json=payload, timeout=10) + if response.status_code >= 400: + logger.error( + f"Meta Graph API error ({response.status_code}): " + f"{response.text}" + ) + response.raise_for_status() + return response.json() + + def send_typing_indicator( + self, recipient_psid: str, is_typing: bool = True + ) -> Dict[str, Any]: + """Send typing indicator (typing_on / typing_off).""" + action = "typing_on" if is_typing else "typing_off" + + if self.is_testing: + return {"recipient_id": recipient_psid} + + url = ( + f"{self.base_url}/me/messages" + f"?access_token={self.page_access_token}" + ) + payload = { + "recipient": {"id": recipient_psid}, + "sender_action": action, + } + + response = requests.post(url, json=payload, timeout=5) + if response.status_code >= 400: + logger.error( + f"Meta Graph API error ({response.status_code}): " + f"{response.text}" + ) + response.raise_for_status() + return response.json() diff --git a/backend/services/weather_intent_service.py b/backend/services/weather_intent_service.py index bee1b1f..0d78cfb 100644 --- a/backend/services/weather_intent_service.py +++ b/backend/services/weather_intent_service.py @@ -13,6 +13,7 @@ from config import settings from models.administrative import Administrative, AdministrativeLevel from models.customer import Customer +from services.messenger_service import MessengerService from services.weather_broadcast_service import get_weather_broadcast_service from services.weather_subscription_service import ( get_weather_subscription_service, @@ -44,6 +45,7 @@ class WeatherIntentService: def __init__(self, db: Session): self.db = db self.whatsapp_service = WhatsAppService() + self.messenger_service = MessengerService() self.weather_broadcast_service = get_weather_broadcast_service() self.weather_subscription_service = get_weather_subscription_service( db @@ -110,16 +112,20 @@ def _build_location_path(self, admin_area: Administrative) -> str: while current: # Skip country level - causes wrong weather API results - level = self.db.query(AdministrativeLevel).filter( - AdministrativeLevel.id == current.level_id - ).first() - if level and level.name != 'country': + level = ( + self.db.query(AdministrativeLevel) + .filter(AdministrativeLevel.id == current.level_id) + .first() + ) + if level and level.name != "country": path_parts.append(current.name) if not current.parent_id: break - current = self.db.query(Administrative).filter( - Administrative.id == current.parent_id - ).first() + current = ( + self.db.query(Administrative) + .filter(Administrative.id == current.parent_id) + .first() + ) # Keep bottom-up order (Ward, District, Region) # So farmer sees their local area first @@ -145,7 +151,7 @@ async def handle_weather_intent( if not settings.weather_intent_enabled: lang = customer.language_code unavailable_msg = t("weather.service_unavailable", lang) - self.whatsapp_service.send_message(phone_number, unavailable_msg) + self._send_channel_message(phone_number, unavailable_msg) logger.info( f"Weather intent disabled, sent unavailable message to " f"{phone_number}" @@ -204,10 +210,8 @@ async def handle_weather_intent( ) # Send weather message - self.whatsapp_service.send_message(phone_number, weather_message) - logger.info( - f"Weather message sent to {phone_number} for {location}" - ) + self._send_channel_message(phone_number, weather_message) + logger.info(f"Weather message sent to {phone_number} for {location}") # Show subscription buttons if broadcasts enabled and not subscribed if ( @@ -224,6 +228,16 @@ async def handle_weather_intent( weather_message=weather_message, ) + def _send_channel_message(self, phone_number: str, message: str) -> None: + """Send message via appropriate channel (WhatsApp or Messenger).""" + if phone_number.startswith("messenger:"): + psid = phone_number.replace("messenger:", "") + self.messenger_service.send_message( + recipient_psid=psid, text=message + ) + else: + self.whatsapp_service.send_message(phone_number, message) + def _send_subscription_buttons( self, customer: Customer, @@ -240,23 +254,42 @@ def _send_subscription_buttons( area_name: Name of the administrative area lang: Language code ("en" or "sw") """ - self.whatsapp_service.send_interactive_buttons( - to_number=phone_number, - body_text=t( - "weather_subscription.question", lang - ).replace("{area_name}", area_name), - buttons=[ - { - "id": settings.weather_yes_payload, - "title": t("weather_subscription.button_yes", lang), - }, - { - "id": settings.weather_no_payload, - "title": t("weather_subscription.button_no", lang), - }, - ], + question_text = t("weather_subscription.question", lang).replace( + "{area_name}", area_name ) + if phone_number.startswith("messenger:"): + psid = phone_number.replace("messenger:", "") + self.messenger_service.send_quick_replies( + recipient_psid=psid, + text=question_text, + options=[ + { + "title": t("weather_subscription.button_yes", lang), + "payload": settings.weather_yes_payload, + }, + { + "title": t("weather_subscription.button_no", lang), + "payload": settings.weather_no_payload, + }, + ], + ) + else: + self.whatsapp_service.send_interactive_buttons( + to_number=phone_number, + body_text=question_text, + buttons=[ + { + "id": settings.weather_yes_payload, + "title": t("weather_subscription.button_yes", lang), + }, + { + "id": settings.weather_no_payload, + "title": t("weather_subscription.button_no", lang), + }, + ], + ) + # Mark as asked so button responses work if not customer.weather_subscription_asked: self.weather_subscription_service.mark_as_asked(customer) diff --git a/backend/tests/test_follow_up_service.py b/backend/tests/test_follow_up_service.py index d90823d..7db22d6 100644 --- a/backend/tests/test_follow_up_service.py +++ b/backend/tests/test_follow_up_service.py @@ -253,6 +253,39 @@ def test_should_not_ask_when_follow_up_sent_after_ticket_resolved( # Should NOT ask because follow-up was sent AFTER ticket resolved assert result is False + def test_should_not_ask_when_follow_up_disabled_in_config( + self, db_session: Session + ): + """Test that follow-up is NOT asked when follow_up_enabled is False""" + from config import settings + + customer = Customer( + phone_number="+255712345689", + full_name="Test Farmer Disabled", + language=CustomerLanguage.EN, + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + # Regular message with no follow-up in history + msg1 = Message( + message_sid="msg_no_followup", + customer_id=customer.id, + body="Help me please", + from_source=MessageFrom.CUSTOMER, + message_type=None, + ) + db_session.add(msg1) + db_session.commit() + + chat_history = [msg1] + + service = FollowUpService(db_session) + with patch.object(settings, "follow_up_enabled", False): + result = service.should_ask_follow_up(customer, chat_history) + assert result is False + class TestFarmerContext: """Test farmer context extraction""" @@ -349,15 +382,13 @@ async def test_generates_english_follow_up(self, db_session: Session): mock_response.content = "What type of crop is affected by this issue?" with patch.object( - service.openai_service, - "is_configured", - return_value=True + service.openai_service, "is_configured", return_value=True ): with patch.object( service.openai_service, "chat_completion", new_callable=AsyncMock, - return_value=mock_response + return_value=mock_response, ): result = await service.generate_follow_up_question( customer=customer, @@ -385,15 +416,13 @@ async def test_generates_swahili_follow_up(self, db_session: Session): mock_response.content = "Ni zao gani limeathirika?" with patch.object( - service.openai_service, - "is_configured", - return_value=True + service.openai_service, "is_configured", return_value=True ): with patch.object( service.openai_service, "chat_completion", new_callable=AsyncMock, - return_value=mock_response + return_value=mock_response, ): result = await service.generate_follow_up_question( customer=customer, @@ -418,9 +447,7 @@ async def test_returns_none_when_openai_not_configured( service = FollowUpService(db_session) with patch.object( - service.openai_service, - "is_configured", - return_value=False + service.openai_service, "is_configured", return_value=False ): result = await service.generate_follow_up_question( customer=customer, @@ -465,20 +492,18 @@ async def test_sends_and_stores_follow_up(self, db_session: Session): mock_whatsapp_result = {"sid": "SM_FOLLOW_UP_123", "status": "sent"} with patch.object( - service.openai_service, - "is_configured", - return_value=True + service.openai_service, "is_configured", return_value=True ): with patch.object( service.openai_service, "chat_completion", new_callable=AsyncMock, - return_value=mock_response + return_value=mock_response, ): with patch.object( service.whatsapp_service, "send_message", - return_value=mock_whatsapp_result + return_value=mock_whatsapp_result, ): result = await service.ask_follow_up( customer=customer, @@ -528,15 +553,13 @@ async def test_returns_none_on_generation_failure( # Mock OpenAI to return None with patch.object( - service.openai_service, - "is_configured", - return_value=True + service.openai_service, "is_configured", return_value=True ): with patch.object( service.openai_service, "chat_completion", new_callable=AsyncMock, - return_value=None + return_value=None, ): result = await service.ask_follow_up( customer=customer, diff --git a/backend/tests/test_message_endpoint.py b/backend/tests/test_message_endpoint.py index d187bc9..0dc22d3 100644 --- a/backend/tests/test_message_endpoint.py +++ b/backend/tests/test_message_endpoint.py @@ -18,9 +18,7 @@ def setup(self, client, db_session): """Setup test data before each test""" self.db = db_session self.client = client - self.pwd_context = CryptContext( - schemes=["bcrypt"], deprecated="auto" - ) + self.pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto") # Seed administrative data rows = [ @@ -734,8 +732,10 @@ def test_create_message_emits_customer_name_for_customer_messages( # if it were to handle customer messages # The sender_name should be customer's full_name or phone_number - assert self.customer.full_name is not None or \ - self.customer.phone_number is not None + assert ( + self.customer.full_name is not None + or self.customer.phone_number is not None + ) # ============ Image Upload Tests ============ @@ -745,11 +745,11 @@ def test_upload_image_valid_jpeg(self): # Create a simple valid JPEG file (minimal JPEG header) jpeg_content = ( - b'\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01\x01' - b'\x00\x00\x01\x00\x01\x00\x00\xff\xdb\x00C' - + b'\x00' * 64 - + b'\xff\xc0\x00\x0b\x08\x00\x01\x00\x01\x01\x01\x11\x00' - + b'\xff\xd9' + b"\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01\x01" + b"\x00\x00\x01\x00\x01\x00\x00\xff\xdb\x00C" + + b"\x00" * 64 + + b"\xff\xc0\x00\x0b\x08\x00\x01\x00\x01\x01\x01\x11\x00" + + b"\xff\xd9" ) response = self.client.post( @@ -771,13 +771,13 @@ def test_upload_image_valid_png(self): # Minimal valid PNG png_content = ( - b'\x89PNG\r\n\x1a\n' - b'\x00\x00\x00\rIHDR' - b'\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02' - b'\x00\x00\x00\x90wS\xde' - b'\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05' - b'\x18\xd8N' - b'\x00\x00\x00\x00IEND\xaeB`\x82' + b"\x89PNG\r\n\x1a\n" + b"\x00\x00\x00\rIHDR" + b"\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02" + b"\x00\x00\x00\x90wS\xde" + b"\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05" + b"\x18\xd8N" + b"\x00\x00\x00\x00IEND\xaeB`\x82" ) response = self.client.post( @@ -808,7 +808,7 @@ def test_upload_image_too_large(self): headers = self._get_auth_headers(self.eo_user) # Create content larger than 16MB - large_content = b'\xff\xd8\xff\xe0' + (b'\x00' * (17 * 1024 * 1024)) + large_content = b"\xff\xd8\xff\xe0" + (b"\x00" * (17 * 1024 * 1024)) response = self.client.post( "/api/messages/upload-image", @@ -929,3 +929,35 @@ def test_create_message_invalid_media_type(self): assert response.status_code == 400 assert "Invalid media_type" in response.json()["detail"] + + def test_create_message_for_messenger_customer(self): + """Test sending message to Messenger customer routes to Messenger.""" + # Change customer phone to messenger format + self.customer.phone_number = "messenger:psid_eo_reply_123" + self.db.commit() + + headers = self._get_auth_headers(self.eo_user) + payload = { + "ticket_id": self.ticket.id, + "body": "Here is the advice from Extension Officer.", + "from_source": MessageFrom.USER, + } + + with patch( + "services.messenger_service.MessengerService.send_message" + ) as mock_msgr_send: + mock_msgr_send.return_value = { + "recipient_id": "psid_eo_reply_123", + "message_id": "mid.eo.reply.999", + } + response = self.client.post( + "/api/messages", + json=payload, + headers=headers, + ) + assert response.status_code == 201 + + assert mock_msgr_send.called + call_kwargs = mock_msgr_send.call_args[1] + assert call_kwargs["recipient_psid"] == "psid_eo_reply_123" + assert "Here is the advice" in call_kwargs["text"] diff --git a/backend/tests/test_messenger_router.py b/backend/tests/test_messenger_router.py new file mode 100644 index 0000000..e11609d --- /dev/null +++ b/backend/tests/test_messenger_router.py @@ -0,0 +1,985 @@ +import json +from unittest.mock import patch + +from fastapi.testclient import TestClient +import pytest +from sqlalchemy.orm import Session + +from config import settings +from models.customer import Customer, OnboardingStatus +from models.message import Message, MessageFrom +from tests.test_messenger_service import generate_signed_request + + +class TestMessengerRouter: + """Test suite for Facebook Messenger webhook and compliance endpoints.""" + + @pytest.fixture(autouse=True) + def setup_messenger_settings(self): + """Isolate tests from ambient environment variables.""" + with ( + patch.object(settings, "messenger_enabled", True), + patch.object(settings, "messenger_app_secret", ""), + patch.object(settings, "messenger_page_id", ""), + ): + yield + + def test_webhook_handshake_success(self, client: TestClient): + response = client.get( + "/api/messenger/webhook", + params={ + "hub.mode": "subscribe", + "hub.verify_token": settings.messenger_verify_token, + "hub.challenge": "1158201244", + }, + ) + assert response.status_code == 200 + assert response.text == "1158201244" + + def test_webhook_handshake_invalid_token(self, client: TestClient): + response = client.get( + "/api/messenger/webhook", + params={ + "hub.mode": "subscribe", + "hub.verify_token": "wrong_verify_token", + "hub.challenge": "1158201244", + }, + ) + assert response.status_code == 403 + + def test_webhook_handshake_invalid_mode(self, client: TestClient): + response = client.get( + "/api/messenger/webhook", + params={ + "hub.mode": "publish", + "hub.verify_token": settings.messenger_verify_token, + "hub.challenge": "1158201244", + }, + ) + assert response.status_code == 403 + + def test_webhook_post_invalid_signature(self, client: TestClient): + with patch.object(settings, "messenger_app_secret", "secret_123"): + body = json.dumps({"object": "page", "entry": []}).encode("utf-8") + response = client.post( + "/api/messenger/webhook", + content=body, + headers={ + "Content-Type": "application/json", + "X-Hub-Signature-256": "sha256=invalid_hash", + }, + ) + assert response.status_code == 403 + + def test_webhook_post_ignores_echo( + self, client: TestClient, db_session: Session + ): + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": "psid_echo_1"}, + "recipient": {"id": "page_id_1"}, + "message": { + "mid": "mid.12345", + "is_echo": True, + "text": "Echo message", + }, + } + ] + } + ], + } + body = json.dumps(payload).encode("utf-8") + with patch.object(settings, "messenger_app_secret", ""): + response = client.post( + "/api/messenger/webhook", + content=body, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + assert response.json()["status"] == "ignored" + + # Verify no customer was created + customer = ( + db_session.query(Customer) + .filter(Customer.phone_number == "messenger:psid_echo_1") + .first() + ) + assert customer is None + + def test_webhook_post_ignores_delivery_receipt( + self, client: TestClient, db_session: Session + ): + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": "psid_receipt_1"}, + "recipient": {"id": "page_id_1"}, + "delivery": {"mids": ["mid.12345"]}, + } + ] + } + ], + } + body = json.dumps(payload).encode("utf-8") + with patch.object(settings, "messenger_app_secret", ""): + response = client.post( + "/api/messenger/webhook", + content=body, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + assert response.json()["status"] == "ignored" + + def test_webhook_post_ignores_unconfigured_page_id( + self, client: TestClient, db_session: Session + ): + payload = { + "object": "page", + "entry": [ + { + "id": "other_page_id", + "messaging": [ + { + "sender": {"id": "psid_other_page_1"}, + "recipient": {"id": "other_page_id"}, + "message": { + "mid": "mid.12345", + "text": "Hello other page", + }, + } + ], + } + ], + } + body = json.dumps(payload).encode("utf-8") + with ( + patch.object(settings, "messenger_app_secret", ""), + patch.object( + settings, "messenger_page_id", "my_configured_page_id" + ), + ): + response = client.post( + "/api/messenger/webhook", + content=body, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + assert response.json()["status"] == "ignored" + + customer = ( + db_session.query(Customer) + .filter(Customer.phone_number == "messenger:psid_other_page_1") + .first() + ) + assert customer is None + + def test_webhook_post_accepts_configured_page_id( + self, client: TestClient, db_session: Session + ): + psid = "psid_configured_page_1" + payload = { + "object": "page", + "entry": [ + { + "id": "my_configured_page_id", + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "my_configured_page_id"}, + "message": { + "mid": "mid.configured.1", + "text": "Habari AgriConnect", + }, + } + ], + } + ], + } + body = json.dumps(payload).encode("utf-8") + with ( + patch.object(settings, "messenger_app_secret", ""), + patch.object( + settings, "messenger_page_id", "my_configured_page_id" + ), + ): + response = client.post( + "/api/messenger/webhook", + content=body, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + + customer = ( + db_session.query(Customer) + .filter(Customer.phone_number == f"messenger:{psid}") + .first() + ) + assert customer is not None + + def test_webhook_post_onboarding_message( + self, client: TestClient, db_session: Session + ): + psid = "psid_farmer_1001" + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_id_1"}, + "message": { + "mid": "mid.farmer.1", + "text": "Habari AgriConnect", + }, + } + ] + } + ], + } + body = json.dumps(payload).encode("utf-8") + with patch.object(settings, "messenger_app_secret", ""): + response = client.post( + "/api/messenger/webhook", + content=body, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + + # Verify customer was created with messenger prefix + customer = ( + db_session.query(Customer) + .filter(Customer.phone_number == f"messenger:{psid}") + .first() + ) + assert customer is not None + assert customer.onboarding_status == OnboardingStatus.IN_PROGRESS + + def test_webhook_post_ignores_duplicate_mid( + self, client: TestClient, db_session: Session + ): + psid = "psid_farmer_dup" + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_id_1"}, + "message": { + "mid": "mid.farmer.dup.1", + "text": "Habari", + }, + } + ] + } + ], + } + body = json.dumps(payload).encode("utf-8") + with patch.object(settings, "messenger_app_secret", ""): + # First delivery + resp1 = client.post( + "/api/messenger/webhook", + content=body, + headers={"Content-Type": "application/json"}, + ) + assert resp1.status_code == 200 + + # Second delivery (retry) + resp2 = client.post( + "/api/messenger/webhook", + content=body, + headers={"Content-Type": "application/json"}, + ) + assert resp2.status_code == 200 + + # Verify only 1 message recorded in database + messages = ( + db_session.query(Message) + .filter(Message.message_sid == "mid.farmer.dup.1") + .all() + ) + assert len(messages) == 1 + + def test_webhook_post_in_chat_deletion_flow( + self, client: TestClient, db_session: Session + ): + psid = "psid_del_user" + # 1. Create customer first + customer = Customer( + phone_number=f"messenger:{psid}", + full_name="Delete Farmer", + language="sw", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + customer_id = customer.id + + # 2. Send "futa" (delete request in Swahili) + delete_payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_id_1"}, + "message": {"mid": "mid.del.1", "text": "futa"}, + } + ] + } + ], + } + with patch.object(settings, "messenger_app_secret", ""): + resp1 = client.post( + "/api/messenger/webhook", + content=json.dumps(delete_payload).encode("utf-8"), + headers={"Content-Type": "application/json"}, + ) + assert resp1.status_code == 200 + + db_session.refresh(customer) + assert customer.delete_requested is True + + # 3. Send "ndio" (confirm in Swahili) + confirm_payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_id_1"}, + "message": { + "mid": "mid.del.2", + "text": "ndio", + }, + } + ] + } + ], + } + resp2 = client.post( + "/api/messenger/webhook", + content=json.dumps(confirm_payload).encode("utf-8"), + headers={"Content-Type": "application/json"}, + ) + assert resp2.status_code == 200 + + # 4. Verify customer is completely deleted + deleted_cust = ( + db_session.query(Customer) + .filter(Customer.id == customer_id) + .first() + ) + assert deleted_cust is None + + def test_meta_data_deletion_callback_success( + self, client: TestClient, db_session: Session + ): + secret = "test_meta_app_secret" + user_psid = "meta_user_999" + + # Create customer to delete + customer = Customer( + phone_number=f"messenger:{user_psid}", + full_name="Meta User", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + customer_id = customer.id + + signed_request = generate_signed_request( + {"user_id": user_psid, "algorithm": "HMAC-SHA256"}, secret + ) + + with patch.object(settings, "messenger_app_secret", secret): + response = client.post( + "/api/messenger/data-deletion", + data={"signed_request": signed_request}, + ) + assert response.status_code == 200 + data = response.json() + assert "url" in data + assert "confirmation_code" in data + assert "code=" in data["url"] + + # Verify customer was deleted + deleted = ( + db_session.query(Customer) + .filter(Customer.id == customer_id) + .first() + ) + assert deleted is None + + def test_meta_data_deletion_callback_invalid_signature( + self, client: TestClient + ): + with patch.object( + settings, "messenger_app_secret", "test_meta_app_secret" + ): + response = client.post( + "/api/messenger/data-deletion", + data={"signed_request": "invalid_sig.invalid_payload"}, + ) + assert response.status_code == 403 + + def test_meta_data_deletion_status_endpoint(self, client: TestClient): + response = client.get( + "/api/messenger/data-deletion/status", params={"code": "CONF12345"} + ) + assert response.status_code == 200 + assert "CONF12345" in response.text + + def test_callback_ai_dispatch_to_messenger( + self, client: TestClient, db_session: Session + ): + psid = "psid_callback_123" + customer = Customer( + phone_number=f"messenger:{psid}", + language="en", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + farmer_msg = Message( + message_sid="mid_initial_query", + customer_id=customer.id, + body="How to plant maize?", + from_source=MessageFrom.CUSTOMER, + ) + db_session.add(farmer_msg) + db_session.commit() + + callback_params = json.dumps( + { + "message_id": farmer_msg.id, + "message_type": 1, # MessageType.REPLY + "customer_id": customer.id, + } + ) + + payload = { + "job_id": "job_msgr_123", + "status": "completed", + "stage": "final", + "job": "chat", + "output": { + "answer": "Plant maize with 75cm x 25cm spacing.", + "citations": [], + }, + "error": None, + "callback_params": callback_params, + "trace_id": "trace_msgr_001", + "token_count": 50, + } + + with patch("services.messenger_service.requests.post") as mock_post: + mock_post.return_value.status_code = 200 + mock_post.return_value.json.return_value = { + "recipient_id": psid, + "message_id": "mid.real.from.callback", + } + + response = client.post("/api/callback/ai", json=payload) + assert response.status_code == 200 + + # Verify AI message was saved in DB + ai_msg = ( + db_session.query(Message) + .filter( + Message.customer_id == customer.id, + Message.from_source == MessageFrom.LLM, + ) + .first() + ) + assert ai_msg is not None + assert "Plant maize" in ai_msg.body + + def test_ai_callback_sends_escalation_quick_reply_with_citations( + self, client: TestClient, db_session: Session + ): + psid = "psid_citations_test" + customer = Customer( + phone_number=f"messenger:{psid}", + full_name="Farmer Citations", + language="en", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + farmer_msg = Message( + message_sid="mid_citations_query", + customer_id=customer.id, + body="How to treat avocado root rot?", + from_source=MessageFrom.CUSTOMER, + ) + db_session.add(farmer_msg) + db_session.commit() + + callback_params = json.dumps( + { + "message_id": farmer_msg.id, + "message_type": 1, + "customer_id": customer.id, + } + ) + + payload = { + "job_id": "job_msgr_citations", + "status": "completed", + "stage": "final", + "job": "chat", + "output": { + "answer": "Apply phosphonate fungicide.", + "citations": [{"source": "Avocado Manual", "page": "12"}], + }, + "error": None, + "callback_params": callback_params, + "trace_id": "trace_msgr_cit", + "token_count": 60, + } + + with ( + patch( + "services.messenger_service.MessengerService.send_message" + ) as mock_send_msg, + patch( + "services.messenger_service.MessengerService." + "send_quick_replies" + ) as mock_send_qr, + ): + mock_send_msg.return_value = { + "recipient_id": psid, + "message_id": "mid.msg.123", + } + mock_send_qr.return_value = { + "recipient_id": psid, + "message_id": "mid.qr.123", + } + + response = client.post("/api/callback/ai", json=payload) + assert response.status_code == 200 + + assert mock_send_msg.called + assert mock_send_qr.called + qr_kwargs = mock_send_qr.call_args[1] + assert qr_kwargs["recipient_psid"] == psid + assert qr_kwargs["options"][0]["payload"] == "escalate" + + def test_messenger_webhook_escalate_creates_ticket( + self, client: TestClient, db_session: Session + ): + from models.administrative import Administrative, AdministrativeLevel + from models.message import MessageStatus + from models.ticket import Ticket + + # Create root administrative area + level = AdministrativeLevel(name="Country", level_index=1) + db_session.add(level) + db_session.commit() + + root_adm = Administrative( + code="KEN", + name="Kenya", + level_id=level.id, + path="Kenya", + parent_id=None, + ) + db_session.add(root_adm) + db_session.commit() + + psid = "psid_escalate_test" + customer = Customer( + phone_number=f"messenger:{psid}", + full_name="Escalating Farmer", + language="en", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + # Original farmer question + prev_msg = Message( + message_sid="mid_orig_q", + customer_id=customer.id, + body="My crop has yellow leaves", + from_source=MessageFrom.CUSTOMER, + ) + db_session.add(prev_msg) + db_session.commit() + + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_123"}, + "message": { + "mid": "mid.btn.escalate", + "quick_reply": {"payload": "escalate"}, + "text": "Talk to Officer", + }, + } + ] + } + ], + } + + with ( + patch( + "services.messenger_service.MessengerService.send_message" + ) as mock_send, + patch("routers.messenger.emit_message_received") as mock_emit, + ): + mock_send.return_value = { + "recipient_id": psid, + "message_id": "mid.conf.123", + } + response = client.post( + "/api/messenger/webhook", + json=payload, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + + # Verify ticket created + ticket = ( + db_session.query(Ticket) + .filter(Ticket.customer_id == customer.id) + .first() + ) + assert ticket is not None + + # Verify message marked as ESCALATED + assert prev_msg.status == MessageStatus.ESCALATED + assert mock_emit.called + + # Verify confirmation sent + assert mock_send.called + confirmation_text = mock_send.call_args[1]["text"] + assert ( + "transferred to extension service provider" + in confirmation_text + ) + + def test_messenger_webhook_escalate_ignored_when_disabled( + self, client: TestClient, db_session: Session + ): + psid = "psid_escalate_disabled" + customer = Customer( + phone_number=f"messenger:{psid}", + full_name="Escalating Farmer Disabled", + language="en", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_123"}, + "message": { + "mid": "mid.btn.escalate.disabled", + "quick_reply": {"payload": "escalate"}, + "text": "Talk to Officer", + }, + } + ] + } + ], + } + + with patch.object(settings, "escalation_enabled", False): + response = client.post( + "/api/messenger/webhook", + json=payload, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + assert response.json()["status"] == "ignored" + + def test_messenger_webhook_weather_intent( + self, client: TestClient, db_session: Session + ): + from models.administrative import ( + Administrative, + AdministrativeLevel, + CustomerAdministrative, + ) + from services.weather_intent_service import WeatherIntentResult + + # Create root and ward administrative area + level = AdministrativeLevel(name="Ward", level_index=4) + db_session.add(level) + db_session.commit() + + ward_adm = Administrative( + code="W1", + name="Kiharu Ward", + level_id=level.id, + path="Kenya > Kiharu Ward", + parent_id=None, + lat=-0.71, + long=37.15, + ) + db_session.add(ward_adm) + db_session.commit() + + psid = "psid_weather_user" + customer = Customer( + phone_number=f"messenger:{psid}", + full_name="Weather Farmer", + language="en", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + cust_adm = CustomerAdministrative( + customer_id=customer.id, + administrative_id=ward_adm.id, + ) + db_session.add(cust_adm) + db_session.commit() + + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_123"}, + "message": { + "mid": "mid.weather.query", + "text": "weather today", + }, + } + ] + } + ], + } + + with patch( + "services.weather_intent_service.WeatherIntentService." + "handle_weather_intent" + ) as mock_handle: + mock_handle.return_value = WeatherIntentResult( + handled=True, + message="Weather intent handled", + weather_message="Sunny, 25°C", + ) + response = client.post( + "/api/messenger/webhook", + json=payload, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + assert mock_handle.called + + def test_messenger_webhook_weather_subscription_response( + self, client: TestClient, db_session: Session + ): + psid = "psid_sub_user" + customer = Customer( + phone_number=f"messenger:{psid}", + full_name="Subscribing Farmer", + language="en", + weather_subscription_asked=True, + weather_subscribed=None, + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_123"}, + "message": { + "mid": "mid.sub.yes", + "quick_reply": { + "payload": settings.weather_yes_payload + }, + "text": "Yes", + }, + } + ] + } + ], + } + + with patch( + "services.messenger_service.MessengerService.send_message" + ) as mock_send: + mock_send.return_value = { + "recipient_id": psid, + "message_id": "mid.conf.sub", + } + response = client.post( + "/api/messenger/webhook", + json=payload, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + assert response.json()["status"] == "success" + + db_session.refresh(customer) + assert customer.weather_subscribed is True + assert mock_send.called + + def test_webhook_handshake_disabled_channel(self, client: TestClient): + with patch.object(settings, "messenger_enabled", False): + response = client.get( + "/api/messenger/webhook", + params={ + "hub.mode": "subscribe", + "hub.verify_token": settings.messenger_verify_token, + "hub.challenge": "1158201244", + }, + ) + assert response.status_code == 403 + assert "disabled" in response.json()["detail"] + + def test_webhook_event_disabled_channel(self, client: TestClient): + with patch.object(settings, "messenger_enabled", False): + response = client.post( + "/api/messenger/webhook", + json={"object": "page", "entry": []}, + ) + assert response.status_code == 403 + assert "disabled" in response.json()["detail"] + + def test_data_deletion_disabled_channel(self, client: TestClient): + with patch.object(settings, "messenger_enabled", False): + response = client.post( + "/api/messenger/data-deletion", + json={"signed_request": "fake_signed_request"}, + ) + assert response.status_code == 403 + assert "disabled" in response.json()["detail"] + + def test_typing_indicator_disabled_by_default( + self, client: TestClient, db_session: Session + ): + psid = "psid_type_disabled" + customer = Customer( + phone_number=f"messenger:{psid}", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_123"}, + "message": { + "mid": "mid.type.dis", + "text": "How do I plant tomatoes?", + }, + } + ] + } + ], + } + + with ( + patch.object( + settings, "messenger_typing_indicator_enabled", False + ), + patch( + "services.onboarding_service.OnboardingService" + ".needs_onboarding", + return_value=False, + ), + patch( + "routers.messenger.MessengerService.send_typing_indicator" + ) as mock_typing, + ): + response = client.post( + "/api/messenger/webhook", + json=payload, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + assert mock_typing.call_count == 0 + + def test_typing_indicator_enabled_and_exception_safe( + self, client: TestClient, db_session: Session + ): + psid = "psid_type_enabled" + customer = Customer( + phone_number=f"messenger:{psid}", + onboarding_status=OnboardingStatus.COMPLETED, + ) + db_session.add(customer) + db_session.commit() + + payload = { + "object": "page", + "entry": [ + { + "messaging": [ + { + "sender": {"id": psid}, + "recipient": {"id": "page_123"}, + "message": { + "mid": "mid.type.en", + "text": "How do I plant tomatoes?", + }, + } + ] + } + ], + } + + with ( + patch.object( + settings, "messenger_typing_indicator_enabled", True + ), + patch( + "services.onboarding_service.OnboardingService" + ".needs_onboarding", + return_value=False, + ), + patch( + "routers.messenger.MessengerService.send_typing_indicator", + side_effect=Exception("Meta Rate Limit"), + ) as mock_typing, + ): + response = client.post( + "/api/messenger/webhook", + json=payload, + headers={"Content-Type": "application/json"}, + ) + assert response.status_code == 200 + assert mock_typing.call_count == 1 diff --git a/backend/tests/test_messenger_service.py b/backend/tests/test_messenger_service.py new file mode 100644 index 0000000..187ffa8 --- /dev/null +++ b/backend/tests/test_messenger_service.py @@ -0,0 +1,206 @@ +import base64 +import hashlib +import hmac +import json +from unittest.mock import Mock, patch + +from services.messenger_service import MessengerService + + +def generate_signed_request(payload_dict: dict, secret: str) -> str: + """Helper to generate a valid Meta signed_request string.""" + payload_json = json.dumps(payload_dict, separators=(",", ":")) + encoded_payload = ( + base64.urlsafe_b64encode(payload_json.encode("utf-8")) + .decode("utf-8") + .rstrip("=") + ) + + sig = hmac.new( + secret.encode("utf-8"), + encoded_payload.encode("utf-8"), + hashlib.sha256, + ).digest() + encoded_sig = base64.urlsafe_b64encode(sig).decode("utf-8").rstrip("=") + + return f"{encoded_sig}.{encoded_payload}" + + +class TestMessengerService: + """ + Test suite for MessengerService Graph API client + and cryptographic helpers. + """ + + def test_init_default_and_env(self): + service = MessengerService( + page_access_token="test_page_token", + app_secret="test_secret", + api_version="v21.0", + is_testing=True, + ) + assert service.page_access_token == "test_page_token" + assert service.app_secret == "test_secret" + assert service.api_version == "v21.0" + assert service.is_testing is True + + def test_verify_signature_valid(self): + secret = "my_app_secret_123" + payload = b'{"object":"page","entry":[]}' + expected_hash = hmac.new( + secret.encode("utf-8"), payload, hashlib.sha256 + ).hexdigest() + valid_header = f"sha256={expected_hash}" + + service = MessengerService(app_secret=secret, is_testing=False) + assert service.verify_signature(payload, valid_header) is True + + def test_verify_signature_invalid(self): + secret = "my_app_secret_123" + payload = b'{"object":"page","entry":[]}' + invalid_header = "sha256=invalidhash1234567890" + + service = MessengerService(app_secret=secret, is_testing=False) + assert service.verify_signature(payload, invalid_header) is False + + def test_verify_signature_malformed_header(self): + secret = "my_app_secret_123" + payload = b'{"object":"page","entry":[]}' + + service = MessengerService(app_secret=secret, is_testing=False) + assert service.verify_signature(payload, "") is False + assert service.verify_signature(payload, "invalid_no_prefix") is False + assert service.verify_signature(payload, None) is False + + def test_verify_signature_in_testing_mode(self): + # In testing mode without secret, verify_signature returns True + service = MessengerService(app_secret="", is_testing=True) + assert service.verify_signature(b"{}", "sha256=any") is True + + def test_parse_signed_request_valid(self): + secret = "test_app_secret" + payload = { + "algorithm": "HMAC-SHA256", + "issued_at": 1700000000, + "user_id": "psid_987654321", + } + signed_request = generate_signed_request(payload, secret) + + service = MessengerService(app_secret=secret, is_testing=False) + parsed = service.parse_signed_request(signed_request) + assert parsed is not None + assert parsed.get("user_id") == "psid_987654321" + + def test_parse_signed_request_tampered(self): + secret = "test_app_secret" + payload = { + "algorithm": "HMAC-SHA256", + "user_id": "psid_987654321", + } + signed_request = generate_signed_request(payload, secret) + tampered_request = signed_request[:-3] + "xyz" + + service = MessengerService(app_secret=secret, is_testing=False) + parsed = service.parse_signed_request(tampered_request) + assert parsed is None + + def test_parse_signed_request_invalid_format(self): + service = MessengerService(app_secret="test_secret", is_testing=False) + assert service.parse_signed_request("invalid_no_dot") is None + assert service.parse_signed_request("") is None + assert service.parse_signed_request(None) is None + + def test_send_message_testing_mode(self): + service = MessengerService(is_testing=True) + response = service.send_message( + recipient_psid="123456789", text="Hello Farmer!" + ) + assert response["recipient_id"] == "123456789" + assert "message_id" in response + assert response["message_id"].startswith("mid.test.") + + @patch("services.messenger_service.requests.post") + def test_send_message_production(self, mock_post): + mock_response = Mock() + mock_response.status_code = 200 + mock_response.json.return_value = { + "recipient_id": "123456789", + "message_id": "mid.real.12345", + } + mock_post.return_value = mock_response + + service = MessengerService( + page_access_token="real_token", + api_version="v21.0", + is_testing=False, + ) + response = service.send_message("123456789", "Habari!") + + assert response["message_id"] == "mid.real.12345" + mock_post.assert_called_once() + args, kwargs = mock_post.call_args + expected_url = ( + "https://graph.facebook.com/v21.0/me/messages" + "?access_token=real_token" + ) + assert args[0] == expected_url + assert kwargs["json"]["recipient"]["id"] == "123456789" + assert kwargs["json"]["message"]["text"] == "Habari!" + + def test_send_quick_replies_testing_mode(self): + service = MessengerService(is_testing=True) + options = [ + {"title": "Option A", "payload": "PAYLOAD_A"}, + {"title": "Option B", "payload": "PAYLOAD_B"}, + ] + response = service.send_quick_replies( + recipient_psid="123456789", + text="Please choose:", + options=options, + ) + assert response["recipient_id"] == "123456789" + assert "message_id" in response + + @patch("services.messenger_service.requests.post") + def test_send_quick_replies_production(self, mock_post): + mock_response = Mock() + mock_response.status_code = 200 + mock_response.json.return_value = { + "recipient_id": "123456789", + "message_id": "mid.real.qr.12345", + } + mock_post.return_value = mock_response + + service = MessengerService( + page_access_token="real_token", is_testing=False + ) + options = [ + {"title": "Mahindi", "payload": "CROP_MAIZE"}, + {"title": "Kahawa", "payload": "CROP_COFFEE"}, + ] + response = service.send_quick_replies( + "123456789", "Chagua zao:", options + ) + + assert response["message_id"] == "mid.real.qr.12345" + mock_post.assert_called_once() + _, kwargs = mock_post.call_args + quick_replies = kwargs["json"]["message"]["quick_replies"] + assert len(quick_replies) == 2 + assert quick_replies[0]["title"] == "Mahindi" + assert quick_replies[0]["payload"] == "CROP_MAIZE" + + @patch("services.messenger_service.requests.post") + def test_send_typing_indicator(self, mock_post): + mock_response = Mock() + mock_response.status_code = 200 + mock_response.json.return_value = {"recipient_id": "123456789"} + mock_post.return_value = mock_response + + service = MessengerService( + page_access_token="real_token", is_testing=False + ) + service.send_typing_indicator("123456789", is_typing=True) + + _, kwargs = mock_post.call_args + assert kwargs["json"]["sender_action"] == "typing_on" diff --git a/backend/tests/test_whatsapp.py b/backend/tests/test_whatsapp.py index 65ead0f..4b18ecd 100644 --- a/backend/tests/test_whatsapp.py +++ b/backend/tests/test_whatsapp.py @@ -26,6 +26,7 @@ def _create_admin_data_and_link_customer( # Get the created administrative area from models.administrative import Administrative + admin = ( db_session.query(Administrative) .filter(Administrative.code == "NATIONAL") @@ -325,3 +326,19 @@ def test_webhook_status_endpoint(self, client: TestClient): response = client.get("/api/whatsapp/status") assert response.status_code == 200 assert response.json()["status"] == "WhatsApp service is running" + + def test_webhook_disabled_channel(self, client: TestClient): + from unittest.mock import patch + from config import settings + + with patch.object(settings, "whatsapp_enabled", False): + response = client.post( + "/api/whatsapp/webhook", + data={ + "From": "whatsapp:+255123456789", + "Body": "Hello", + "MessageSid": "SM_TEST_DISABLED", + }, + ) + assert response.status_code == 403 + assert "disabled" in response.json()["detail"] diff --git a/docker-compose.yml b/docker-compose.yml index 4819e79..f2aaab4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -91,6 +91,11 @@ services: - REDIS_PORT=${REDIS_PORT:-6379} - REDIS_DB=${REDIS_DB:-0} - STATISTIC_API_TOKEN=${STATISTIC_API_TOKEN} + - MESSENGER_PAGE_ID=${MESSENGER_PAGE_ID} + - MESSENGER_VERIFY_TOKEN=${MESSENGER_VERIFY_TOKEN} + - MESSENGER_PAGE_ACCESS_TOKEN=${MESSENGER_PAGE_ACCESS_TOKEN} + - MESSENGER_APP_SECRET=${MESSENGER_APP_SECRET} + - MESSENGER_GRAPH_API_VERSION=${MESSENGER_GRAPH_API_VERSION} command: ["./dev.sh"] working_dir: /app volumes: diff --git a/docs/FACEBOOK_MESSENGER_INTEGRATION.md b/docs/FACEBOOK_MESSENGER_INTEGRATION.md new file mode 100644 index 0000000..747e3a8 --- /dev/null +++ b/docs/FACEBOOK_MESSENGER_INTEGRATION.md @@ -0,0 +1,268 @@ +# Facebook Messenger Integration (PoC) + +## Overview + +This specification details the Proof of Concept (PoC) for integrating **Facebook Messenger** into AgriConnect as an additional messaging channel alongside WhatsApp. It enables farmers/users to interact with AgriConnect via Facebook Messenger (for automated onboarding, AI knowledge base Q&A, follow-up clarification, and self-service account deletion) without impacting or regressing any existing WhatsApp, Twilio, Mobile App, or Admin Web workflows. + +Furthermore, it provides both: +1. **Self-Service Customer Deletion Flow**: User sends "delete" / "futa" over Messenger with confirmation handling. +2. **Meta Platform Data Deletion Callback Endpoint**: Mandatory Meta compliance endpoint (`POST /api/messenger/data-deletion`) satisfying Facebook Platform Data Deletion Request requirements. + +--- + +## Architecture & Data Model Analysis: Why Migration is Optional for PoC vs Future Multi-Channel + +### 1. The Core Question: Do We Need a Database Migration? +There are two architectural paths for handling Facebook Messenger user identifiers: + +#### **Option A: Non-Breaking PoC Approach (Zero Migration)** +* **How it works**: + - Facebook Messenger identifies users by Page-Scoped User IDs (`PSID`, e.g., `837192847291029`). + - In the current schema, `Customer.phone_number` is `String(unique=True, nullable=False)` and `Message.message_sid` is `String(unique=True, nullable=False)`. + - Storing the PSID in `Customer.phone_number` as `messenger:` (or directly ``) requires **zero database migrations** and **zero schema modifications**. + - **Why prefix `messenger:`?** It guarantees that a numerical PSID will never clash with an E.164 phone number (e.g. Tanzanian phone `+255...` or Kenyan phone `+254...`), making channel routing deterministic for services that look up customers. + +#### **Option B: Long-Term Multi-Channel Schema (Requires Migration)** +* **How it works**: + - Add `channel` column to `customers` (e.g. `Enum('WHATSAPP', 'MESSENGER', 'TELEGRAM')`, default `'WHATSAPP'`). + - Make `phone_number` nullable in `customers`. + - Add `channel_user_id` (String) with a unique composite index `(channel, channel_user_id)`. + - Create an Alembic migration script. +* **Trade-off**: + - **Pros**: Clean, normalized relational design; explicit channel field. + - **Cons**: Requires migration across all deployed tenant instances; touches queries in `CustomerService`, statistics, and admin listings. + +> [!NOTE] +> **Recommended Strategy**: For this **PoC**, we use **Option A** (`messenger:` in `Customer.phone_number`) so we can deploy and validate the Facebook Messenger bot immediately with **zero risk to existing database instances**. The spec is designed so transitioning to Option B later is an additive schema migration. + +--- + +## 5W1H Requirements Analysis + +- **Who**: Farmers and community users engaging with AgriConnect via Facebook Messenger; System Administrators; Meta Compliance Auditors. +- **What**: + - Webhook verification & incoming message ingestion (`GET` / `POST /api/messenger/webhook`). + - Outbound messaging via Meta Graph Send API (`MessengerService`). + - In-chat self-service account deletion trigger. + - Meta platform GDPR/Data Deletion callback (`POST /api/messenger/data-deletion`). +- **Where**: + - Backend router: `/backend/routers/messenger.py` + - Backend service: `/backend/services/messenger_service.py` + - Configuration: `/backend/config.py`, `.env.example` +- **When**: Triggered upon Facebook Messenger message events from Meta webhooks or platform deletion requests. +- **Why**: Broaden reach beyond WhatsApp to Facebook Messenger while maintaining strict data privacy compliance and zero regression for existing channels. +- **How**: Channel isolation using `messenger:` identifier mapped cleanly into existing `Customer` and `Message` models, reusing `OnboardingService`, `FollowUpService`, `CustomerService`, and `ExternalAIService`. + +--- + +## Architecture Overview + +```mermaid +sequenceDiagram + autonumber + actor User as Facebook User + participant Meta as Meta Messenger Platform + participant Router as /api/messenger/webhook + participant CustSvc as CustomerService + participant OnbSvc as OnboardingService / AISvc + participant MsgSvc as MessengerService + + %% Handshake Flow + Note over Meta,Router: Initial Webhook Handshake (GET /api/messenger/webhook) + Meta->>Router: GET hub.mode=subscribe&hub.verify_token=...&hub.challenge=... + Router-->>Meta: 200 OK (hub.challenge) + + %% Inbound Message Flow + Note over User,MsgSvc: Inbound Message / Conversation Flow (POST /api/messenger/webhook) + User->>Meta: Send message (Text / Quick Reply) + Meta->>Router: POST JSON entry[].messaging[] with X-Hub-Signature-256 + Router->>Router: Validate HMAC Signature & Deduplicate Message + Router->>CustSvc: get_or_create_customer(phone_number="messenger:") + + alt User requests "delete" / "futa" + Router->>CustSvc: Handle in-chat deletion confirmation / delete_customer() + Router->>MsgSvc: Send deletion confirmation / success via Graph API + MsgSvc-->>Meta: POST /v21.0/me/messages (Recipient PSID) + else Active Onboarding + Router->>OnbSvc: Process onboarding step + OnbSvc-->>Router: Next question / options + Router->>MsgSvc: Send next onboarding prompt / quick replies + MsgSvc-->>Meta: POST /v21.0/me/messages + else Escalation / Talk to Officer + User->>Router: Click "Talk to Officer" (payload="escalate") + Router->>CustSvc: Find/create open Ticket for farmer + Router->>Router: emit_message_received (WebSocket) & WHISPER AI job + Router->>MsgSvc: Send escalation confirmation with Extension Officer contacts + MsgSvc-->>Meta: POST /v21.0/me/messages + else Normal Q&A / AI Advisory + Router->>OnbSvc: Dispatch to FollowUpService / ExternalAIService + OnbSvc-->>Router: AI Answer (with citations) + Router->>MsgSvc: Send answer + disclaimer + Router->>MsgSvc: Send Escalation Quick Reply ("Talk to Officer") + MsgSvc-->>Meta: POST /v21.0/me/messages + end +``` + +--- + +## Zero-Regression Architecture Guardrails + +1. **Identifier Isolation**: + - WhatsApp uses E.164 phone numbers (e.g., `+254712345678`). + - Facebook Messenger uses Page-Scoped IDs (PSIDs). + - In `Customer.phone_number`, Messenger users are stored as `messenger:`. This prevents accidental collisions and keeps `routers/whatsapp.py` completely safe. +2. **Dedicated Router & Services**: + - `routers/whatsapp.py` remains 100% untouched. + - All Messenger logic lives in `routers/messenger.py` and `services/messenger_service.py`. +3. **Shared Core Engine**: + - `OnboardingService`, `CustomerService.delete_customer()`, `ExternalAIService`, and `t()` i18n are called modularly without channel coupling. + +--- + +## 1. Backend Implementation + +### 1.1 Configuration & Environment Variables + +**File**: `/backend/config.py` & `.env.example` + +```python +# Facebook Messenger Configuration +MESSENGER_PAGE_ID: str = os.getenv("MESSENGER_PAGE_ID", "") +MESSENGER_VERIFY_TOKEN: str = os.getenv("MESSENGER_VERIFY_TOKEN", "agriconnect_messenger_verify_token") +MESSENGER_PAGE_ACCESS_TOKEN: str = os.getenv("MESSENGER_PAGE_ACCESS_TOKEN", "") +MESSENGER_APP_SECRET: str = os.getenv("MESSENGER_APP_SECRET", "") +MESSENGER_GRAPH_API_VERSION: str = os.getenv("MESSENGER_GRAPH_API_VERSION", "v21.0") +``` + +### 1.2 Outbound Messenger Service + +**File**: `/backend/services/messenger_service.py` + +Responsible for communicating with Meta Graph API: +- `send_message(recipient_psid: str, text: str) -> Dict` +- `send_quick_replies(recipient_psid: str, text: str, options: List[Dict[str, str]]) -> Dict` +- `send_typing_indicator(recipient_psid: str, is_typing: bool = True) -> Dict` +- `verify_signature(payload_bytes: bytes, signature_header: str) -> bool` + +### 1.3 Messenger Webhook & Deletion Endpoints + +**File**: `/backend/routers/messenger.py` + +#### 1. Webhook Handshake +- **`GET /api/messenger/webhook`** + - Query Params: `hub.mode`, `hub.verify_token`, `hub.challenge` + - Validates `hub.mode == "subscribe"` and `hub.verify_token == settings.MESSENGER_VERIFY_TOKEN`. + - Returns `PlainTextResponse(content=str(hub_challenge))` with HTTP 200 OK on success (Meta requires raw plain text/integer string, not JSON) or 403 Forbidden on mismatch. + +#### 2. Inbound Message Processing +- **`POST /api/messenger/webhook`** + - Headers: `X-Hub-Signature-256` (HMAC-SHA256 signature prefixed with `sha256=`). + - Request Payload: Consumes raw bytes via `request.body()` first for HMAC validation using `hmac.compare_digest()`, then parses Meta Messenger JSON. + - Logic: + 1. Validate `X-Hub-Signature-256` HMAC signature against `settings.MESSENGER_APP_SECRET`. + 2. Check `object == "page"`. + 3. Loop through `entry[].messaging[]`. + 4. Ignore echo messages (`message.is_echo == True`) and read/delivery receipts (`delivery`, `read`). + 5. Extract `sender.id` (PSID) and `message.text` / `message.quick_reply.payload` / `postback.payload`. + 6. Identify/create customer via `phone_number = f"messenger:{psid}"`. + 7. Supports in-chat customer deletion trigger ("delete" / "futa" + confirmation). + 8. Handles onboarding flow (`OnboardingService`) or delegates to AI response pipeline (`ExternalAIService` / `FollowUpService`). + 9. Return immediate HTTP 200 OK to acknowledge Meta within the < 5s SLA. + +#### 3. Meta Platform User Data Deletion Callback +- **`POST /api/messenger/data-deletion`** + - Required by Meta Platform Policies for apps handling Messenger. + - Request Payload: Form-encoded (`signed_request: str`) or JSON (`{"signed_request": "..."}`). + - Parsing Algorithm: + 1. Split `signed_request` into `encoded_sig` and `payload`. + 2. Fix base64url padding (`payload += '=' * (-len(payload) % 4)`). + 3. Verify signature: `expected_sig = hmac.new(app_secret.encode(), payload.encode(), hashlib.sha256).digest()`. + 4. Compare decoded signature using `hmac.compare_digest(sig, expected_sig)`. + 5. Decode JSON payload to extract `user_id` (PSID). + 6. Call `customer_service.delete_customer(customer.id)` for `phone_number = f"messenger:{user_id}"`. + 7. Generate a unique confirmation code and status check URL. + 8. Return Meta JSON response: + ```json + { + "url": "https://agriconnect.org/api/messenger/data-deletion/status?code=", + "confirmation_code": "" + } + ``` +- **`GET /api/messenger/data-deletion/status`** + - Query Param: `code` + - Renders deletion confirmation status for user/compliance lookup. + +--- + +### 1.4 Multi-Channel Outbound Message Dispatching + +To prevent regression and eliminate Twilio errors when communicating with Messenger users across asynchronous callbacks, EO direct replies, and weather services: + +**Files**: `/backend/routers/callbacks.py`, `/backend/routers/messages.py`, `/backend/services/follow_up_service.py`, & `/backend/services/weather_intent_service.py` + +* **Channel-Aware Routing Strategy**: + When dispatching an AI response, EO manual reply, follow-up question, or weather alert/prompt to `customer.phone_number`: + ```python + if customer.phone_number.startswith("messenger:"): + psid = customer.phone_number.replace("messenger:", "") + messenger_service = MessengerService() + messenger_service.send_message(recipient_psid=psid, text=ai_response_text) + else: + # Default WhatsApp flow (E.164 phone numbers) + whatsapp_service = WhatsAppService() + whatsapp_service.send_message_with_tracking( + to_number=customer.phone_number, + message_body=WhatsAppService.sanitize_whatsapp_content(ai_response_text), + message_id=ai_message.id, + db=db, + ) + ``` + +--- + +## 2. Verification & Testing Strategy + +### 2.1 Automated Unit & Integration Tests + +**Files**: `/backend/tests/test_messenger_router.py` & `/backend/tests/test_messenger_service.py` + +Test Cases: +1. `test_webhook_verification_success()`: Validate `GET /api/messenger/webhook` with `hub.mode=subscribe` and valid token returns plain-text challenge. +2. `test_webhook_verification_forbidden()`: Validate invalid token returns HTTP 403. +3. `test_webhook_signature_verification()`: Verify valid HMAC-SHA256 vs invalid/missing `X-Hub-Signature-256`. +4. `test_inbound_message_ignores_echoes_and_receipts()`: Ensure `is_echo: true` and delivery receipts do not trigger message processing. +5. `test_onboarding_and_ai_message_flow()`: Ensure incoming text from new PSID triggers customer creation (`messenger:`) and onboarding response. +6. `test_in_chat_account_deletion()`: Verify sending "delete" and "yes" deletes the `messenger:` customer without leaving orphaned records. +7. `test_meta_signed_request_data_deletion()`: Verify `POST /api/messenger/data-deletion` parses signed request, purges customer, and returns status URL. +8. `test_meta_signed_request_invalid_signature()`: Verify tampered or invalid signature returns HTTP 400/403. +9. `test_channel_routing_in_callbacks()`: Verify asynchronous AI callback delivers via `MessengerService` for `messenger:` and `WhatsAppService` for standard phone numbers. +10. `test_regression_whatsapp_isolation()`: Verify WhatsApp webhook endpoints and services operate without side effects. + +### 2.2 Test Execution Commands + +```bash +# Run backend tests inside Docker +./dc.sh exec backend python -m pytest tests/test_messenger_router.py tests/test_messenger_service.py -v + +# Run full test suite with linting +./dc.sh exec backend flake8 --exclude=alembic,patches +./dc.sh exec backend tests +``` + +--- + +## 3. Epic & Ballpark Estimation + +> Ballpark estimates in developer hours. Break down complex tasks so no single task exceeds 16h. +- Confidence Level: **High** +- Dependencies: Meta Developer Account & Facebook Page Access Token for manual end-to-end verification. + +| Task ID | Component & Description | Est. Hours (Min - Max) | Priority | +|---------|-------------------------|------------------------|----------| +| T-001 | **Config & Settings**: Add Messenger environment variables and settings to `config.py` and `.env.example` | 1h - 2h | Must Have | +| T-002 | **Messenger Service**: Implement `MessengerService` with Meta Graph API client, HMAC signature verification, and typing/quick-reply helpers | 4h - 6h | Must Have | +| T-003 | **Messenger Router**: Implement `GET` & `POST /api/messenger/webhook` handling handshake, raw-body HMAC check, message ingestion, and routing to `OnboardingService` & `ExternalAIService` | 6h - 10h | Must Have | +| T-004 | **Deletion Endpoints**: Implement in-chat deletion handling and Meta compliance callback `POST /api/messenger/data-deletion` with base64url signed request parser | 3h - 5h | Must Have | +| T-005 | **Multi-Channel Dispatching**: Add channel-aware message routing to `callbacks.py` and `follow_up_service.py` | 2h - 3h | Must Have | +| T-006 | **Unit & Integration Tests**: Complete test suite for signature verification, echo filtering, webhook routing, callback dispatching, and deletion flows | 4h - 6h | Must Have | +| **Total** | | **20h - 32h** | |