Skip to content

Credit Path Backup

A comprehensive WhatsApp-based credit recovery system that helps Kenyan small-business owners follow up on unpaid debts through intelligent conversation routing, AI-powered coaching, and automated scheduling.

Purpose

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

How It Works

This workflow processes WhatsApp messages from youth entrepreneurs managing credit recovery:

  1. Message Reception: Receives WhatsApp messages via Twilio webhook
  2. User Validation: Checks if the sender is enrolled in the credit recovery program
  3. Context Building: Looks up active debtor information and conversation state
  4. Intent Classification: Uses AI to classify the message intent (payment status, fear, forgot, etc.)
  5. Conversation Routing: Deterministic state machine handles most responses, with AI fallback for complex cases
  6. State Management: Updates conversation state and debtor information in the database
  7. Response Generation: Sends contextual replies with coaching, scripts, or next steps
  8. Safety Monitoring: Detects threats and alerts Community Engagement Advisors (CEAs)
  9. History Logging: Records outcomes and schedules follow-up reminders

The system supports multiple conversation flows including promised payments, partial payments, refusals, fear coaching, and reminder scheduling.

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[Route Conversation]
    I --> J{Handled By AI?}
    J -->|Yes| K[AI Agent]
    J -->|No| L[Merge]
    K --> L
    L --> M[Advance State]
    L --> N{Has Outcome?}
    M --> O[Activate Next Debtor]
    M --> P{Safety Triggered?}
    N -->|Yes| Q[Log History]
    P -->|Yes| R[Insert CEA Alert]
    R --> S{Has CEA Phone?}
    S -->|Yes| T[Send CEA WhatsApp]
    T --> U[Mark CEA Alert Sent]
    O --> V[Format Message]
    V --> W[Send WhatsApp Twilio API]
    W --> X[Respond OK]

Trigger

Webhook: POST endpoint at /credit-path that receives WhatsApp messages from Twilio with webhook ID sifa-creditpath-classifier-webhook

Nodes Used

Node Type Purpose
Webhook Receives incoming WhatsApp messages from Twilio
Set Extracts phone number and message content from Twilio payload
Postgres Database operations for user lookup, state management, and logging
If Conditional routing based on user type, AI handling, outcomes, and safety
Code Date computation, context merging, and conversation routing logic
LangChain Agent AI-powered intent classification and conversation handling
LangChain Chat Model OpenRouter integration for AI responses
LangChain Memory Conversation history storage for context-aware responses
Execute Workflow Message formatting for interactive content
HTTP Request Direct Twilio API calls for WhatsApp message sending
Twilio CEA alert notifications via WhatsApp
Respond to Webhook HTTP response acknowledgment

External Services & Credentials Required

  • Twilio API: WhatsApp messaging and webhook handling
    • Account SID and Auth Token for API access
    • Phone number: +12402623539
  • OpenRouter API: AI model access for intent classification and conversation handling
    • API key for GPT-4.1 and Gemini 2.5 Flash models
  • PostgreSQL Database: Data persistence
    • Connection to sifaV4Dev database
    • Tables: v4_youthEntrepreneurs, v4_creditpathFollowup, v4_creditpathHistory, v4_ceaalerts, v4_cea_contacts, v4_credit_chat_histories

Environment Variables

No explicit environment variables are referenced in the workflow configuration. Credentials are managed through n8n's credential system.

Data Flow

Input: - Twilio webhook payload containing WhatsApp message data (WaId, Body)

Processing: - User and debtor lookup from database - Intent classification of message content - State machine processing with AI fallback - Database updates for conversation state and history

Output: - WhatsApp response message (plain text or interactive buttons) - Updated database records for conversation state - Scheduled follow-up reminders - CEA safety alerts when threats are detected

Error Handling

  • Non-credit users: Silent OK response without processing
  • AI parsing failures: Fallback to deterministic templates
  • Database errors: Workflow continues with available data
  • Safety concerns: Automatic CEA alert generation and conversation pause
  • Invalid inputs: Graceful degradation with clarification requests

Known Limitations

Based on the workflow structure, potential limitations include: - Dependency on external AI services for complex conversation handling - Twilio rate limits for WhatsApp messaging - Database connection requirements for all operations - Manual CEA contact management for safety alerts

  • V4-Credit-MessageInterceptor (ID: 8pNZfAG0jWfYqqy4): Message formatting for interactive content
  • Additional credit recovery workflows may exist in the broader system

Setup Instructions

  1. Import Workflow: Import the JSON configuration into n8n
  2. Configure Credentials:
    • Set up Twilio API credentials with account details
    • Configure OpenRouter API key for AI services
    • Establish PostgreSQL database connection to sifaV4Dev
  3. Database Setup: Ensure required tables exist with proper schema
  4. Webhook Configuration:
    • Set webhook URL in Twilio to point to n8n instance
    • Configure webhook ID: sifa-creditpath-classifier-webhook
  5. Test Integration: Send test WhatsApp message to verify end-to-end flow
  6. Monitor Logs: Check n8n execution logs and database records for proper operation

The workflow is designed to be self-contained once credentials are configured, with automatic state management and conversation flow handling.