V4 - WhatsAppTrigger - Warenga

This workflow serves as the main entry point for WhatsApp messages in the Sifa V4 system, handling incoming messages from young entrepreneurs and routing them through various processing stages including sales tracking, message formatting, and response delivery via Twilio.

Purpose

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

This workflow appears to be part of a youth entrepreneurship coaching program, processing WhatsApp communications and providing automated responses through AI agents. It handles user onboarding, sales data collection, and provides fallback mechanisms for error scenarios.

How It Works

1. Message Reception: Receives WhatsApp messages via webhook from Twilio
2. User Lookup: Queries the database to find the user's record and current status
3. User Routing: Routes new users to an organic handler for onboarding, existing users continue to main flow
4. Activity Tracking: Updates the user's last inbound message timestamp
5. Message Processing: Extracts user phone number and message content for processing
6. AI Agent Processing: Sends the message to a Sales Tracking Agent for analysis and response generation
7. Response Validation: Checks if the agent produced valid output
8. Message Formatting: Processes the agent's response through a Message Interceptor for proper formatting
9. Response Delivery: Determines whether to send a template message or regular text response via Twilio
10. Error Handling: Logs errors and sends fallback messages when processing fails
11. Chat Logging: Records all interactions for audit and analysis purposes

Workflow Diagram

graph TD
    A[DevelopmentWebhook] --> B[getUserRecord]
    B --> C[ifUserNotFound]
    C -->|User Not Found| D[callOrganicHandler]
    C -->|User Found| E[updateLastInboundAt]
    E --> F[setUserPhoneNumnberAndQuery]
    F --> G["Call 'Francis - SalesTrackingAgent'"]
    G -->|Success| H[hasAgentOutput]
    G -->|Error| I[logError]
    H -->|Has Output| J["Call 'V4 - MessageInterceptor'"]
    H -->|No Output| I
    J --> K[isInteractive?]
    K -->|Interactive| L[Variables]
    K -->|Regular| M[Send WhatsApp response via Twilio]
    L --> N[sendTemplate]
    I --> O[setFallbackMessage]
    O --> P[sendFallbackWhatsApp]
    O --> Q[logChatFallback]

    %% Unused daytime message flow
    R[isDaytimeMessage] --> S[storeDaytimeMessage]
    S --> T[isWeeklyReport]
    T --> U[Set WR Input]
    U --> V[Call Weekly Report Handler]

Trigger

Webhook Trigger: Listens for POST requests at path 98ed6d7d-5af1-4500-878f-56b7f22cad75 from Twilio WhatsApp webhook notifications.

Nodes Used

Node Type	Node Name	Purpose
Webhook	DevelopmentWebhook	Receives incoming WhatsApp messages from Twilio
PostgreSQL	getUserRecord	Retrieves user information from the database
If	ifUserNotFound	Routes new vs existing users
Execute Workflow	callOrganicHandler	Handles new user onboarding
PostgreSQL	updateLastInboundAt	Updates user's last activity timestamp
Set	setUserPhoneNumnberAndQuery	Prepares data for agent processing
Execute Workflow	Call 'Francis - SalesTrackingAgent'	Processes messages through AI agent
If	hasAgentOutput	Validates agent response
Execute Workflow	Call 'V4 - MessageInterceptor'	Formats agent responses
If	isInteractive?	Determines message type (template vs text)
Set	Variables	Prepares template variables
HTTP Request	sendTemplate	Sends WhatsApp template messages
Twilio	Send WhatsApp response via Twilio	Sends regular text messages
PostgreSQL	logError	Records processing errors
Set	setFallbackMessage	Creates error fallback message
Twilio	sendFallbackWhatsApp	Sends fallback messages
PostgreSQL	logChatFallback	Logs fallback interactions

External Services & Credentials Required

Twilio

• Credential Name: "Twilio WhatsApp kdp"
• Purpose: Sending WhatsApp messages
• Required Fields: Account SID, Auth Token

Twilio HTTP Basic Auth

• Credential Name: "Waringa twilio auth"
• Purpose: Template message API calls
• Required Fields: Username, Password

PostgreSQL

• Credential Name: "sifaV4Dev"
• Purpose: Database operations for user records, chat logs, and error tracking
• Required Fields: Host, Database, Username, Password

Environment Variables

No explicit environment variables are configured in this workflow. All configuration is handled through n8n credentials and node parameters.

Data Flow

Input

• WhatsApp webhook payload containing:
  • WaId: User's WhatsApp ID
  • Body: Message content
  • To: Twilio WhatsApp number
  • From: User's WhatsApp number
  • ProfileName: User's display name
  • InteractiveData: Button/interactive responses
  • ButtonPayload: Button interaction data

Output

• WhatsApp messages sent to users via Twilio
• Database records updated in:
  • v4_youthEntrepreneurs: User activity tracking
  • v4_chatLog: Conversation logging
  • errorLog: Error tracking
  • v4_pendingDaytimeMessages: Unused daytime message storage

Error Handling

The workflow implements comprehensive error handling:

1. Agent Processing Errors: If the Sales Tracking Agent fails, errors are logged to the database and a fallback message is sent
2. Database Connection Issues: PostgreSQL nodes are configured to continue on error
3. Fallback Messaging: When processing fails, users receive a polite error message in Swahili: "Samahani, kuna tatizo kidogo. Tafadhali jaribu tena baadaye. 🙏"
4. Error Logging: All errors are recorded with user phone number, workflow name, error message, and raw input
5. Chat Logging: Even fallback interactions are logged for audit purposes

Known Limitations

Based on the sticky notes in the workflow: - Daytime message logic is noted as unnecessary for Sifa V4 (active throughout) - Error notifications to Slack channels are planned but not implemented - Call center integration is mentioned as not needed - Weekly report handler is disabled

Related Workflows

This workflow calls several other workflows: - V4 - OrganicKeepWarmHandler: Handles new user onboarding - V4 - WIP - Francis - SalesTrackingAgent: Processes messages through AI agent - V4 - MessageInterceptor: Formats agent responses for delivery - V4 - Weekly Report Handler: Disabled weekly report processing

Setup Instructions

1. Import the Workflow: Import the JSON into your n8n instance

2. Configure Credentials:

   • Set up Twilio credentials with your Account SID and Auth Token
   • Configure PostgreSQL connection to your Sifa V4 database
   • Set up Twilio HTTP Basic Auth for template messaging

3. Database Setup: Ensure these tables exist:

   • v4_youthEntrepreneurs
   • v4_chatLog
   • errorLog
   • v4_pendingDaytimeMessages

4. Webhook Configuration:

   • Note the webhook URL from the DevelopmentWebhook node
   • Configure your Twilio WhatsApp number to send webhooks to this URL

5. Related Workflows: Import and configure the dependent workflows mentioned in the Related Workflows section

6. Testing: Send a test WhatsApp message to verify the complete flow works

7. Monitoring: Monitor the error logs and chat logs to ensure proper operation