V4 - OrganicKeepWarmHandler¶

This workflow manages conversational lead qualification for organic WhatsApp inquiries, guiding potential leads through a structured intake process that combines deterministic button responses with AI-powered natural language processing to collect business information and consent for future communications.

Purpose¶

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

How It Works¶

Message Reception: Receives incoming WhatsApp messages with user details and message content
Lead Lookup: Checks if the phone number exists in the organic leads database
Message Logging: Records the incoming user message in the chat history
Request Classification: Analyzes the message to determine the appropriate response flow:
- NEW: First-time contact, creates new lead
- DETERMINISTIC: Recognizes button clicks or exact text matches for structured responses
- AI: Requires natural language processing for complex or ambiguous responses
- CLOSED: Lead has already completed or exited the process
- OPTOUT: User wants to unsubscribe from communications
Response Generation: Based on classification, generates appropriate responses and database updates
Database Updates: Updates lead information and conversation state in the database
Message Sending: Sends responses via WhatsApp using either templates or plain text
Activity Logging: Records outbound messages in the chat history

The workflow guides leads through a multi-step qualification process covering business ownership, referral sources, business type, selling frequency, location, and communication preferences.

Workflow Diagram¶

graph TD
    A[When Executed by Another Workflow] --> B[getOrganicLead]
    B --> C[logUserInbound]
    C --> D[classifyRequest]
    D --> E[routeFlow]

    E --> F[buildNewLeadDecision]
    E --> G[buildDeterministicDecision]
    E --> H[callAIInterpreter]
    E --> I[buildClosedDecision]
    E --> J[buildOptOutDecision]

    G --> K[applyAIResult]
    H --> K

    F --> L[decisionPackage]
    K --> L
    I --> L
    J --> L

    L --> M[upsertLead]
    M --> N[splitSends]
    N --> O[isTemplate]

    O --> P[sendTemplate]
    O --> Q[sendText]

    P --> R[logBotOutbound]
    Q --> R

Trigger¶

Execute Workflow Trigger: This workflow is called by other workflows and expects the following input parameters: - phoneNumber: The user's phone number - userMessage: The incoming message content - buttonPayload: Button ID if user clicked a structured response - firstName: User's first name - twilioFromNumber: Twilio sender number - twilioToNumber: Twilio recipient number - channel: Communication channel (e.g., "whatsapp")

Nodes Used¶

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflows
PostgreSQL	getOrganicLead	Retrieves existing lead data from database
PostgreSQL	logUserInbound	Records incoming user messages
Code	classifyRequest	Analyzes message type and determines response flow
Switch	routeFlow	Routes execution based on message classification
Code	buildNewLeadDecision	Handles first-time contacts
Code	buildDeterministicDecision	Processes structured button responses
Execute Workflow	callAIInterpreter	Calls AI workflow for natural language processing
Code	applyAIResult	Validates and applies AI interpretation results
Code	buildClosedDecision	Handles completed/exited conversations
Code	buildOptOutDecision	Processes unsubscribe requests
Code	decisionPackage	Consolidates decision data for processing
PostgreSQL	upsertLead	Updates lead information in database
Code	splitSends	Prepares multiple messages for sending
If	isTemplate	Determines message type (template vs plain text)
HTTP Request	sendTemplate	Sends WhatsApp template messages via Twilio
HTTP Request	sendText	Sends plain text messages via Twilio
PostgreSQL	logBotOutbound	Records outbound bot messages

External Services & Credentials Required¶

Twilio API¶

Purpose: WhatsApp message sending
Credentials: HTTP Basic Auth (Waringa twilio auth)
Account: AC906ca9524b640bdad7d029fd565b6a02
Endpoints:
- Template messages: /2010-04-01/Accounts/{AccountSid}/Messages.json
- Text messages: /2010-04-01/Accounts/{AccountSid}/Messages.json

PostgreSQL Database¶

Purpose: Lead and chat history storage
Credentials: sifaV4Dev
Tables:
- v4_organic_leads: Lead information and conversation state
- v4_organic_chat_history: Message history logging

AI Interpreter Workflow¶

Purpose: Natural language processing for ambiguous responses
Workflow ID: kGRj9YnsWFWe63G3
Inputs: phoneNumber, currentStep, expectedShape, userMessage, firstName

Environment Variables¶

No explicit environment variables are defined in this workflow. Configuration is handled through: - Database connection credentials - Twilio API credentials - Hardcoded template SIDs and account information

Data Flow¶

Input Data¶

{
  "phoneNumber": "+254707060397",
  "userMessage": "User's message content",
  "buttonPayload": "btn_org_welcome_yes",
  "firstName": "John",
  "twilioFromNumber": "+12402623539",
  "twilioToNumber": "+254707060397",
  "channel": "whatsapp"
}

Output Data¶

Database updates to lead records
WhatsApp messages sent to users
Chat history logging
Lead progression through qualification steps

Key Data Transformations¶

Button payloads and text messages mapped to normalized values
Conversation state progression (awaiting_1.2 → awaiting_1.3 → ... → complete)
Boolean field conversion for business ownership and consent
Lead ID generation upon completion

Error Handling¶

The workflow includes several validation mechanisms:

Step Validation: Ensures next steps are from a whitelist of valid values
Forward Progression: Prevents users from moving backwards in the conversation flow
AI Validation Rejection: Handles cases where AI interpretation fails validation
Opt-out Detection: Recognizes unsubscribe requests in multiple languages
Closed Conversation Handling: Prevents responses to completed/exited leads
Database Conflict Resolution: Uses UPSERT operations to handle duplicate entries

Fallback responses are provided when validation fails or unexpected inputs are received.

Known Limitations¶

Based on the workflow structure, potential limitations include:

Language Support: Opt-out detection includes English and some Swahili terms but may not cover all local languages
Template Dependencies: Relies on specific Twilio template SIDs that must be pre-configured
AI Dependency: Natural language processing depends on external AI interpreter workflow availability
Single Channel: Currently designed specifically for WhatsApp via Twilio
Step Ordering: Enforces strict forward progression which may not accommodate all user conversation patterns

AI Interpreter Workflow (ID: kGRj9YnsWFWe63G3): Handles natural language processing for ambiguous user responses

Setup Instructions¶

Import Workflow: Import the workflow JSON into your n8n instance
Configure Database Connection:
- Set up PostgreSQL credential named sifaV4Dev
- Ensure database contains required tables:
  - v4_organic_leads
  - v4_organic_chat_history
- Verify generate_organic_lead_id() function exists
Configure Twilio Credentials:
- Create HTTP Basic Auth credential named Waringa twilio auth
- Use your Twilio Account SID and Auth Token
- Update Account SID in HTTP request URLs if different
Set Up WhatsApp Templates:
- Configure Twilio WhatsApp templates with the SIDs referenced in the workflow
- Ensure templates are approved and active
Configure AI Interpreter:
- Ensure the AI interpreter workflow (ID: kGRj9YnsWFWe63G3) is available
- Verify it accepts the required input parameters
Test the Workflow:
- Use the pinned test data or create your own test inputs
- Verify database connections and message sending functionality
- Test different conversation flows (new lead, existing lead, opt-out)
Activate Workflow: Enable the workflow to start processing incoming messages
Monitor Performance: Check logs and database entries to ensure proper operation