Skip to content

[DEV-TEST] Credit Path — Twilio Webhook

This is a development testing workflow that handles WhatsApp messages for a credit recovery coaching program. It implements a conversational state machine that guides young entrepreneurs through a 7-outcome daily follow-up process for debt collection, helping them track and recover money owed by their customers.

Purpose

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

Based on the workflow implementation, this appears to serve young entrepreneurs in a credit coaching program by: - Providing structured daily follow-up conversations about debt recovery - Tracking outcomes of debt collection attempts (promises, partial payments, refusals, etc.) - Offering emotional support and guidance through the challenging process of asking for money - Maintaining safety protocols when threats or conflicts arise - Scheduling appropriate follow-up reminders based on debtor responses

How It Works

  1. Incoming Message: Twilio receives a WhatsApp message and posts it to the webhook
  2. Data Extraction: The workflow extracts the phone number and message content from Twilio's payload
  3. User Lookup: Queries the database to find the youth entrepreneur and any active debt recovery cases
  4. Eligibility Check: Verifies the user is enrolled in the credit path program
  5. State Processing: Runs the conversational state machine based on the current follow-up step and user's response
  6. Database Updates: Updates the follow-up state, debtor information, and conversation status
  7. History Logging: Records outcomes and schedules future follow-ups when a conversation concludes
  8. Response: Sends an appropriate WhatsApp reply back to the user
  9. Webhook Response: Returns HTTP 200 to Twilio to acknowledge receipt

The state machine handles 7 different outcomes: - Promise to pay → Captures relationship and commitment date - Partial payment → Records amount and new balance - Full payment → Celebrates success and closes case - Refusal → Provides emotional support and schedules buffer period - Forgot → Offers reminder options - Fear/Anxiety → Provides reassurance and gentler approach - No time → Offers scheduling flexibility

Mermaid 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[Advance State]
    E --> H{Has Outcome?}
    G --> I[Send WhatsApp Reply]
    H -->|Yes| J[Log History]
    I --> K[Respond OK]

Trigger

Webhook: Twilio posts incoming WhatsApp messages to the endpoint /deterministic-test

The webhook expects Twilio's standard WhatsApp message format with fields like WaId, Body, From, and To.

Nodes Used

Node Type Node Name Purpose
Webhook Twilio Webhook1 Receives incoming WhatsApp messages from Twilio
Set Extract Twilio Fields1 Extracts phone number and message content from Twilio payload
Postgres Lookup User + Debtor1 Queries database for youth entrepreneur and active debt cases
If Is Credit Path Youth?1 Checks if user is enrolled in credit path program
Code processStep1 Implements the conversational state machine logic
Postgres Advance State1 Updates follow-up state and debtor information
If Has Outcome? Determines if conversation reached a conclusion
Postgres Log History Records outcomes and schedules future follow-ups
Twilio Send WhatsApp Reply1 Sends response message back to user
Respond to Webhook Respond OK1 Returns HTTP 200 to Twilio
Respond to Webhook Respond OK (Silent)1 Returns HTTP 200 for non-credit-path users

External Services & Credentials Required

Twilio

  • Purpose: WhatsApp messaging service
  • Credentials: Twilio API credentials for account with WhatsApp sandbox or approved number
  • Phone Number: +12402623539 (configured in the workflow)

PostgreSQL Database

  • Purpose: Stores youth entrepreneur data and credit follow-up records
  • Credentials: Database connection for "sifaV4Dev"
  • Tables Used:
    • v4_youthEntrepreneurs: User profiles and program enrollment
    • v4_creditpathFollowup: Active debt recovery cases and conversation state
    • v4_creditpathHistory: Historical outcomes and scheduled follow-ups

Environment Variables

No explicit environment variables are used. Configuration is handled through: - Twilio webhook URL configuration - Database credentials stored in n8n credential manager - Phone numbers and messaging content hardcoded in nodes

Data Flow

Input

  • Twilio Webhook Payload: Standard WhatsApp message format including:
    • WaId: User's WhatsApp ID (phone number)
    • Body: Message content
    • From/To: Sender and recipient numbers

Processing

  • User Data: Youth entrepreneur profile and credit program details
  • Debtor Data: Information about the person who owes money
  • Conversation State: Current step in the follow-up process
  • User Response: Parsed and categorized user input

Output

  • WhatsApp Message: Contextual response in Swahili/English mix
  • Database Updates: New conversation state and debtor information
  • History Record: Outcome logging and future follow-up scheduling
  • HTTP Response: 200 OK to Twilio

Error Handling

The workflow includes basic error handling: - Non-Credit Users: Silent OK response for users not in the credit path program - Invalid Input: Fallback messages asking users to select from valid options (1-7) - Safety Override: Special handling for messages indicating threats or conflicts - Missing Data: Graceful handling of undefined or null values in database queries

Known Limitations

Based on the workflow documentation: - Development Only: Explicitly marked as "NOT for prod — testing only" - Single Test User: Pre-configured for testing with +254746919438 - Fixed Phone Number: Hardcoded Twilio number (+12402623539) - Language Mixing: Responses mix Swahili and English, may not suit all users - Manual Setup: Requires manual database seeding for test scenarios

No related workflows are explicitly mentioned in the current documentation.

Setup Instructions

1. Import and Configure Credentials

  1. Import the workflow into your n8n instance
  2. Set up PostgreSQL credentials:
    • Create a new Postgres credential named "sifaV4Dev"
    • Configure connection to your v4 development database
  3. Set up Twilio credentials:
    • Create a new Twilio API credential
    • Use your Twilio Account SID and Auth Token
    • Ensure access to WhatsApp messaging

2. Database Setup

Ensure your PostgreSQL database has the required tables: - v4_youthEntrepreneurs with credit path user data - v4_creditpathFollowup with active debt cases - v4_creditpathHistory for outcome logging

3. Twilio Configuration

  1. Activate the workflow in n8n
  2. Copy the webhook URL: https://your-n8n-instance.com/webhook/deterministic-test
  3. Configure in Twilio Console:
    • Go to Phone Numbers → Manage → Active Numbers
    • Select your WhatsApp-enabled number
    • Set webhook URL as "When a message comes in" (POST method)

4. Test Setup

For testing, seed the database with: - Test youth: +254746919438 with primary_pain_point = 'credit' - Test debtor: Active conversation with currentCreditFollowupStep = 'cfu_outcome_pending'

5. Testing

Send a WhatsApp message to your configured Twilio number from the test phone number to trigger the 7-outcome menu and walk through the conversation flow.