[DEV-TEST] Credit Path — Hybrid (Webhook + AI Agent)¶

A WhatsApp-based credit recovery coaching system that helps Kenyan small business owners follow up on money owed by their customers. This hybrid workflow combines deterministic logic for common scenarios with AI assistance for ambiguous cases, providing personalized coaching in Sheng (Swahili-English mix) while maintaining safety guardrails and relationship-sensitive messaging.

Purpose¶

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

Based on the workflow implementation, this system serves Kenyan youth entrepreneurs who struggle with credit recovery from their customers. The workflow guides them through a structured 7-outcome credit follow-up process (C1-C7), from promises to payment to refusals and fears, providing appropriate coaching and scripts for each scenario while prioritizing safety and relationship preservation.

How It Works¶

Incoming Message: Youth sends WhatsApp message to Twilio webhook about their credit recovery attempt
User Lookup: System fetches youth profile and active debtor information from PostgreSQL database
Credit Path Filter: Only processes messages from users with "credit" as their primary pain point
Smart Processing: Deterministic logic analyzes the message and determines if AI assistance is needed
AI Agent (When Needed): For ambiguous cases, an AI agent with chat memory provides personalized responses using relationship-matched scripts
State Management: Updates credit follow-up progress and debtor information in database
History Logging: Records outcomes and schedules future nudges when appropriate
WhatsApp Response: Sends coaching message back to the youth via Twilio

Workflow Diagram¶

graph TD
    A[Twilio Webhook] --> B[Extract Twilio Fields]
    B --> C[Lookup User + Debtor]
    C --> D{Is Credit Path Youth?}
    D -->|Yes| E[processStep]
    D -->|No| F[Respond OK Silent]
    E --> G{Needs LLM?}
    G -->|Yes| H[AI Agent]
    G -->|No| I[Merge LLM/Deterministic]
    H --> I
    I --> J[Advance State]
    I --> K{Has Outcome?}
    J --> L[Send WhatsApp Reply]
    K -->|Yes| M[Log History]
    L --> N[Respond OK]

    %% AI Agent sub-components
    O[OpenRouter Chat Model] --> H
    P[Postgres Chat Memory] --> H
    Q[scheduleNudgeTool] --> H

Trigger¶

Webhook Trigger: Receives POST requests at /credit-path endpoint from Twilio when youth entrepreneurs send WhatsApp messages about their credit recovery efforts.

Nodes Used¶

Node Type	Purpose
Webhook	Receives incoming WhatsApp messages from Twilio
Set (Extract Fields)	Extracts phone number and message content from Twilio payload
Postgres	Looks up user profile and debtor information
If (Credit Path Filter)	Filters for users with credit recovery as primary focus
Code (processStep)	Deterministic logic for common credit recovery scenarios
If (Needs LLM)	Routes to AI agent for ambiguous cases
AI Agent	Handles complex scenarios with personalized coaching
OpenRouter Chat Model	Provides LLM capabilities via Anthropic Claude
Postgres Chat Memory	Maintains conversation history per phone number
Tool Workflow	Schedules future reminder nudges
Code (Merge)	Combines deterministic and AI outputs
Postgres (Advance State)	Updates credit follow-up progress
If (Has Outcome)	Determines if outcome logging is needed
Postgres (Log History)	Records outcomes and schedules follow-ups
Twilio	Sends WhatsApp responses back to youth
Respond to Webhook	Confirms message receipt to Twilio

External Services & Credentials Required¶

PostgreSQL Database: Stores user profiles, debtor information, and chat history
- Credential: sifaV4Dev (REPLACE_PG_V4_DEV)
Twilio API: WhatsApp messaging service
- Credential: Twilio account 3 (REPLACE_TWILIO)
OpenRouter API: AI model access (Anthropic Claude Haiku 4.5)
- Credential: sifa_dev_env (REPLACE_OPENROUTER)
Sub-workflow: Nudge scheduling tool
- Workflow ID: REPLACE_NUDGE_TOOL_WF_ID

Environment Variables¶

No explicit environment variables are used. Configuration is handled through n8n credentials and workflow settings.

Data Flow¶

Input: Twilio webhook payload containing: - WaId: Youth's WhatsApp phone number - Body: Message content about credit recovery attempt

Processing: - Fetches youth profile and active debtor details - Analyzes message for one of 7 credit outcomes (C1-C7) - Generates appropriate coaching response - Updates database state and logs history

Output: - WhatsApp message with personalized coaching in Sheng - Updated credit follow-up state in database - Scheduled future nudges when appropriate - HTTP 200 OK response to Twilio

Error Handling¶

Non-credit users: Silently responds OK without processing
Database errors: Workflow will fail and require manual intervention
AI parsing errors: Merge node includes robust JSON extraction with fallbacks
Safety concerns: Automatic detection pauses recovery and notifies support

Known Limitations¶

Requires manual credential replacement (REPLACE_* placeholders)
AI model costs accumulate with usage (currently using Claude Haiku for cost efficiency)
Limited to credit recovery use case only
Requires active PostgreSQL connection for all operations
Safety keyword detection is basic pattern matching

Nudge Scheduling Tool: Sub-workflow for scheduling future reminders (workflow ID needs configuration)

Setup Instructions¶

Import Workflow: Import the JSON into your n8n instance
Configure Credentials:
- Set up PostgreSQL connection for sifaV4Dev
- Configure Twilio API credentials
- Add OpenRouter API key for AI model access
Database Setup: Ensure these tables exist:
- v4_youthEntrepreneurs: User profiles
- v4_creditpathFollowup: Active credit cases
- v4_creditpathHistory: Outcome history
- v4_credit_n8n_chat_history: AI conversation memory
Replace Placeholders:
- Update REPLACE_NUDGE_TOOL_WF_ID with actual workflow ID
- Verify all credential references are correct
Webhook Configuration:
- Activate the workflow to generate webhook URL
- Configure Twilio to send WhatsApp messages to the webhook endpoint
Testing: Use the pinned test data to verify the workflow processes messages correctly