Profit Path¶

An intelligent WhatsApp coaching workflow that provides daily profit-building follow-up for Kenyan small-business owners. The system uses AI-powered intent classification and deterministic conversation routing to deliver personalized coaching through five distinct pathways (P1-P5) based on how youth entrepreneurs report on their assigned micro-actions.

Purpose¶

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

How It Works¶

Webhook Reception: Receives incoming WhatsApp messages via Twilio webhook
Field Extraction: Extracts phone number, message content, and message ID from Twilio payload
User Lookup: Queries database to find youth entrepreneur profile and active conversation state, with duplicate message detection
Eligibility Check: Verifies the user is enrolled in the profit coaching program (not credit path)
Date Computation: Calculates Kenya local time (EAT) and builds date reference table for AI context
Intent Classification: AI classifier analyzes the message to determine user intent (sold, tried_no_sale, afraid, forgot, no_time, etc.)
Context Merging: Combines user data, intent classification, and business type mapping
Coaching Library Lookup: Retrieves pre-written coaching content specific to the user's business type
Conversation Routing: Deterministic state machine routes to appropriate coaching pathway (P1-P5) or delegates to AI for edge cases
AI Fallback: For complex cases requiring personalized responses, AI agent generates contextual replies
Response Merging: Combines deterministic and AI outputs into final response
State Management: Updates conversation state and tracking data in database
History Logging: Records interaction details for completed outcomes
Points Award: Awards points for successful micro-action completion
WhatsApp Reply: Sends coaching response back to user via Twilio
Webhook Response: Returns OK status to Twilio

Mermaid Diagram¶

graph TD
    A[Twilio Webhook] --> B[Extract Twilio Fields]
    B --> C[Lookup User + Debtor]
    C --> D{Is Credit Path Youth?}
    D -->|No| E[Respond OK Silent]
    D -->|Yes| F[Compute Dates]
    F --> G[Intent Classifier]
    G --> H[Merge Context]
    H --> I[Lookup Coaching Library]
    I --> J[Lookup Coaching Item]
    J --> K[Route Conversation]
    K --> L{Handled By AI?}
    L -->|Yes| M[AI Agent]
    L -->|No| N[Merge]
    M --> N
    N --> O[Advance State]
    N --> P{Has Outcome?}
    O --> Q[Send WhatsApp Reply]
    P -->|Yes| R[Log History]
    Q --> S[Respond OK]
    R --> T[Award Points]

    U[Classifier Chat Model] -.-> G
    V[Fallback Chat Model] -.-> M

Trigger¶

Webhook: POST requests to /profit-path endpoint from Twilio WhatsApp integration. Triggered when users send WhatsApp messages to the SIFA bot number.

Nodes Used¶

Node Type	Node Name	Purpose
Webhook	Twilio Webhook	Receives incoming WhatsApp messages from Twilio
Set	Extract Twilio Fields	Extracts phone number, message content, and message ID
Postgres	Lookup User + Debtor	Queries user profile and conversation state with deduplication
If	Is Credit Path Youth?	Filters for profit program participants only
Code	Compute Dates	Calculates Kenya time and date references for AI context
LangChain Agent	Intent Classifier	AI classification of user message intent
Code	Merge Context	Combines user data with classification results
Postgres	Lookup Coaching Library	Retrieves business-specific coaching content
Code	Lookup Coaching Item	Attaches coaching library to context
Code	Route Conversation	Deterministic conversation routing and response generation
If	Handled By AI?	Determines if AI agent should handle the response
LangChain Agent	AI Agent	Generates personalized responses for edge cases
Code	Merge	Combines deterministic and AI outputs
Postgres	Advance State	Updates conversation state in database
If	Has Outcome?	Checks if interaction should be logged to history
Postgres	Log History	Records completed interactions
Postgres	Award Points	Awards points for successful actions
Twilio	Send WhatsApp Reply	Sends response back to user
Respond to Webhook	Respond OK	Returns success status to Twilio

External Services & Credentials Required¶

Twilio¶

Credential: twilioApi (Twilio WhatsApp kdp)
Purpose: WhatsApp message sending and receiving
Required: Account SID, Auth Token, WhatsApp-enabled phone number

OpenRouter API¶

Credential: openRouterApi (sifa_dev_env)
Purpose: AI model access for intent classification and response generation
Models Used:
- openai/gpt-4.1 (Intent Classifier)
- openai/gpt-5.2 (AI Agent)
Required: OpenRouter API key

PostgreSQL Database¶

Credential: postgres (sifaV4Dev)
Purpose: User data, conversation state, coaching content, and history storage
Required: Database connection string with read/write access

Environment Variables¶

No explicit environment variables are defined in this workflow. Configuration is handled through n8n credentials and node parameters.

Data Flow¶

Input¶

Twilio Webhook Payload: Contains WhatsApp message data including sender phone number, message content, and message ID
Database Records: User profiles, conversation states, coaching library content

Output¶

WhatsApp Response: Contextual coaching message sent back to user
Database Updates: Conversation state changes, interaction history, points awarded
Webhook Response: HTTP 200 OK status to Twilio

Key Data Transformations¶

Phone number normalization (adds + prefix)
Business type mapping (free text → enum: Kibanda, Salon, Mtumba, Other)
Intent classification (Sheng/Swahili → structured intent)
Coaching pathway routing (P1: sold, P2: tried_no_sale, P3: afraid, P4: forgot, P5: no_time)

Error Handling¶

Duplicate Message Detection: Prevents processing the same message twice using message SID tracking
Silent Rejection: Non-profit program users receive silent OK response without processing
AI Fallback: When deterministic routing fails or coaching library is incomplete, AI agent provides personalized responses
Graceful Degradation: Missing coaching content triggers AI generation rather than system failure
Attempt Limiting: Conversation loops are capped at 2 attempts before escalation to human support

Known Limitations¶

Based on the workflow implementation: - Only supports profit program participants (credit path users are filtered out) - Requires active conversation state in database for proper routing - Coaching library must be populated for optimal deterministic responses - AI models have temperature settings that may affect response consistency - Points are only awarded for specific successful outcomes (P1, P2, P3)

No related workflows are explicitly mentioned in the current implementation, though the code references suggest this is part of a larger SIFA coaching system with separate credit path workflows.

Setup Instructions¶

Import Workflow: Import the JSON workflow definition into your n8n instance
Configure Credentials:
- Set up Twilio API credentials with WhatsApp-enabled phone number
- Configure OpenRouter API credentials for AI model access
- Set up PostgreSQL database connection
Database Setup: Ensure the following tables exist:
- v4_youthEntrepreneurs (user profiles)
- v4_profitpathFollowup (conversation states)
- v4_profitpathHistory (interaction history)
- v4_profitCoachingLibrary (coaching content)
- v4_pointsledger (points tracking)
Webhook Configuration:
- Activate the workflow to generate webhook URL
- Configure Twilio WhatsApp webhook to POST to the generated URL path /profit-path
Coaching Library Population: Add coaching content to v4_profitCoachingLibrary table with appropriate business types and branches (P1-P5)
Testing: Send test WhatsApp messages to verify end-to-end functionality
Monitoring: Set up monitoring for webhook responses and database operations to ensure reliable operation