WhatsApp Trigger - Francis Testing

This workflow processes incoming WhatsApp messages from youth entrepreneurs, validates users against a database, handles time-based message routing, and responds via an AI sales tracking agent. It includes both development and production webhook endpoints with comprehensive error handling and fallback messaging.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

How It Works

1. Message Reception: Incoming WhatsApp messages are received via Twilio webhooks (separate endpoints for development and production)
2. User Validation: The system looks up the sender's phone number in the youthEntrepreneursReal database table
3. Unknown User Handling: If the user isn't found, sends an error message directing them to contact their program coordinator
4. Activity Tracking: Updates the user's lastInboundAt timestamp to track engagement
5. Time-Based Routing: Checks if the message was sent during daytime hours (4 AM - 7 PM Nairobi time) and if the user hasn't started an evening session
6. Daytime Message Storage: Messages sent during daytime are stored in pendingDaytimeMessages table for later processing
7. AI Agent Processing: Evening messages or processed daytime messages are sent to the "Francis - SalesTrackingAgent" workflow
8. Response Delivery: Valid AI responses are sent back via WhatsApp through Twilio
9. Error Handling: Failed processing attempts are logged and trigger fallback messages in Swahili

Mermaid Diagram

graph TD
    A[DevelopmentWebhook] --> B[getUserRecord]
    A2[productionWebhook] --> B2[getUserRecord1]

    B --> C[ifUserNotFound]
    B2 --> C2[ifUserNotFound1]

    C -->|User Not Found| D[userNotFound]
    C -->|User Found| E[updateLastInboundAt]
    C2 -->|User Not Found| D2[userNotFound1]
    C2 -->|User Found| E2[updateLastInboundAt1]

    E --> F[isDaytimeMessage]
    E2 --> F2[isDaytimeMessage1]

    F -->|Daytime| G[storeDaytimeMessage]
    F -->|Evening| H[setUserPhoneNumnberAndQuery]
    F2 -->|Daytime| G2[storeDaytimeMessage1]
    F2 -->|Evening| H2[setUserPhoneNumnberAndQuery1]

    G --> H
    G2 --> H2

    H --> I[Call 'Francis - SalesTrackingAgent']
    H2 --> I2[Call 'Francis - SalesTrackingAgent'1]

    I --> J[hasAgentOutput]
    I2 --> J2[hasAgentOutput1]

    J -->|Has Output| K[Send WhatsApp response via Twilio]
    J -->|No Output| L[logError]
    J2 -->|Has Output| K2[Send WhatsApp response via Twilio1]
    J2 -->|No Output| L2[logError1]

    L --> M[setFallbackMessage]
    L2 --> M2[setFallbackMessage1]

    M --> N[sendFallbackWhatsApp]
    M2 --> N2[sendFallbackWhatsApp1]

Trigger

Webhook Triggers: Two HTTP POST webhook endpoints receive incoming WhatsApp messages from Twilio: - Development: /98ed6d7d-5af1-4500-878f-56b7f22cad75 - Production: /23dd4bb2-c037-4603-8483-d52e2faecf48

Nodes Used

Node Type	Purpose
Webhook	Receives incoming WhatsApp messages from Twilio
PostgreSQL	Queries user records, updates timestamps, stores daytime messages, logs errors
If	Conditional logic for user validation, time checks, and output validation
Set	Prepares user data for agent processing and fallback messages
Execute Workflow	Calls the Francis SalesTrackingAgent workflow
Twilio	Sends WhatsApp responses and error messages
Sticky Note	Documentation and workflow organization

External Services & Credentials Required

Twilio

• Credential Name: "Iganga Coach"
• Purpose: Send and receive WhatsApp messages
• Required: Account SID, Auth Token, WhatsApp-enabled phone number

PostgreSQL Database

• Credential Name: "kdpTestEnv"
• Purpose: User management, message storage, error logging
• Required: Host, port, database name, username, password

Required Database Tables

• youthEntrepreneursReal: User records with phone numbers and session status
• pendingDaytimeMessages: Temporary storage for daytime messages
• errorLog: Error tracking and debugging

Environment Variables

No explicit environment variables are configured in this workflow. All configuration is handled through: - Webhook paths (hardcoded) - Database credentials (stored in n8n credential system) - Twilio credentials (stored in n8n credential system)

Data Flow

Input

• WhatsApp Message: JSON payload from Twilio containing:
  • body.WaId: Sender's WhatsApp ID (phone number)
  • body.Body: Message content
  • body.From: Sender's WhatsApp number with prefix
  • body.To: Recipient's WhatsApp number with prefix

Output

• WhatsApp Response: AI-generated response or error message sent via Twilio
• Database Updates: User activity timestamps, stored daytime messages, error logs

Internal Data

• User records with session status and onboarding information
• Processed user queries and phone numbers for agent workflow
• Error details and fallback messages

Error Handling

The workflow includes comprehensive error handling:

1. User Not Found: Sends message directing users to contact program coordinator
2. Agent Failures: Catches errors from the SalesTrackingAgent workflow and logs them
3. Empty Responses: Detects when the AI agent returns no output
4. Database Errors: Continues execution even if database operations fail
5. Fallback Messaging: Sends Swahili error message when processing fails: "Samahani, kuna tatizo kidogo. Tafadhali jaribu tena baadaye. 🙏"
6. Error Logging: All errors are stored in the errorLog table with phone number, workflow name, error message, and raw input

Known Limitations

Based on the sticky notes in the workflow: - Call center integration is not implemented (noted as "no call center people") - Slack error notifications are planned but not yet implemented - The workflow needs to distinguish between sales-related queries and advice-seeking messages

Related Workflows

• Francis - SalesTrackingAgent (ID: SGrZ4QpudpulAtLG): AI agent that processes user queries and generates responses

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Twilio Credentials:
   • Create Twilio credential named "Iganga Coach"
   • Add Account SID, Auth Token, and WhatsApp phone number
3. Configure Database Credentials:
   • Create PostgreSQL credential named "kdpTestEnv"
   • Ensure database contains required tables with proper schema
4. Set Up Twilio Webhook:
   • Configure Twilio WhatsApp webhook to point to your n8n webhook URLs
   • Use production webhook for live environment
5. Deploy SalesTrackingAgent:
   • Ensure the Francis - SalesTrackingAgent workflow is deployed and accessible
6. Test Integration:
   • Send test WhatsApp message to verify end-to-end functionality
   • Check database for proper user lookup and message storage
7. Monitor Errors:
   • Review errorLog table for any processing issues
   • Implement Slack notifications for error alerts (optional enhancement)