Skip to content

WhatsApp Trigger - Francis

This workflow handles incoming WhatsApp messages for the Francis sales tracking program, routing messages through user validation, time-based filtering, and AI-powered sales coaching responses. It operates in both development and production environments 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: The workflow receives WhatsApp messages via Twilio webhooks (separate endpoints for development and production)
  2. User Validation: Looks up the sender's phone number in the youthEntrepreneursReal database table
  3. Registration Check: 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 it's daytime (4 AM - 7 PM) and the user hasn't started an evening session
  6. Message Storage: For daytime messages, stores them in pendingDaytimeMessages for later processing
  7. AI Processing: Routes messages to the Francis SalesTrackingAgent workflow for intelligent response generation
  8. Response Validation: Checks if the AI agent returned a valid response
  9. Message Delivery: Sends the AI-generated response back via WhatsApp using Twilio
  10. Error Handling: Logs errors and sends fallback messages in Swahili when the AI fails

Workflow 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/Night| H[setUserPhoneNumnberAndQuery]
    F2 -->|Daytime| G2[storeDaytimeMessage1]
    F2 -->|Evening/Night| H2[setUserPhoneNumnberAndQuery1]

    G --> H
    G2 --> H2

    H --> I[Call Francis - SalesTrackingAgent]
    H2 --> I2[Call Francis - SalesTrackingAgent1]

    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 Trigger: Two webhook endpoints receive POST requests from Twilio when WhatsApp messages are sent to the configured phone number: - Development: 98ed6d7d-5af1-4500-878f-56b7f22cad75 - Production: 23dd4bb2-c037-4603-8483-d52e2faecf48

Nodes Used

Node Type Count Purpose
Webhook 2 Receive incoming WhatsApp messages from Twilio
PostgreSQL 8 Database operations for user lookup, activity tracking, message storage, and error logging
If (Conditional) 6 User validation, time-based routing, and response validation
Set 4 Data preparation and fallback message creation
Twilio 6 Send WhatsApp responses and error notifications
Execute Workflow 2 Call the Francis SalesTrackingAgent for AI responses
Sticky Note 3 Documentation and development notes

External Services & Credentials Required

Twilio API

  • Credential Name: "Iganga Coach"
  • Purpose: Send and receive WhatsApp messages
  • Required Fields: Account SID, Auth Token, Phone Number

PostgreSQL Database

  • Credential Name: "kdpTables"
  • Purpose: User management and data storage
  • Required Tables:
    • youthEntrepreneursReal: User profiles and status
    • pendingDaytimeMessages: Queued messages for later processing
    • 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 manager) - Twilio credentials (stored in n8n credential manager)

Data Flow

Input

  • WhatsApp Message Data: Phone number (WaId), message content (Body), sender/receiver info
  • Message Format: Twilio webhook payload with user message content

Output

  • Success: AI-generated response sent via WhatsApp
  • Failure: Swahili fallback message: "Samahani, kuna tatizo kidogo. Tafadhali jaribu tena baadaye. 🙏"
  • Unregistered User: "Sorry, your number was not found in our system. Please contact your programme coordinator."

Database Updates

  • User activity timestamps in youthEntrepreneursReal
  • Daytime message queue in pendingDaytimeMessages
  • Error logs in errorLog

Error Handling

The workflow includes comprehensive error handling:

  1. User Not Found: Sends registration error message via WhatsApp
  2. AI Agent Failures: Logs errors to database and sends Swahili fallback message
  3. Database Errors: Continues execution with error output to prevent workflow failure
  4. Empty AI Responses: Treated as errors, triggers fallback messaging
  5. Retry Logic: AI agent calls have retry enabled for transient failures

Known Limitations

Based on the sticky notes in the workflow: - Error notifications are not sent to Slack channels (noted as future enhancement) - Call center integration is mentioned but not implemented - The workflow duplicates logic between development and production paths

  • Francis - SalesTrackingAgent (vZMNjMq52ZzcJwAi): AI agent that processes user queries and generates contextual sales coaching responses

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance
  2. Configure Twilio Credentials:
    • Create "Iganga Coach" credential with your Twilio Account SID and Auth Token
    • Configure WhatsApp-enabled phone number
  3. Configure Database Credentials:
    • Create "kdpTables" PostgreSQL credential
    • Ensure required tables exist with proper schema
  4. Set Up Webhook URLs:
    • Configure Twilio webhook URLs to point to your n8n webhook endpoints
    • Development: https://your-n8n-instance/webhook/98ed6d7d-5af1-4500-878f-56b7f22cad75
    • Production: https://your-n8n-instance/webhook/23dd4bb2-c037-4603-8483-d52e2faecf48
  5. Deploy Francis SalesTrackingAgent: Ensure the dependent workflow is active and properly configured
  6. Test: Send a WhatsApp message to your configured number to verify the complete flow
  7. Monitor: Check error logs in the database and n8n execution history for any issues