Skip to content

KDP Entry Original

A multi-channel messaging workflow that handles incoming messages from both WhatsApp and SMS, validates users against a database, and routes valid users to an AI sales tracking agent while sending appropriate responses back through the original communication channel.

Purpose

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

This workflow appears to be part of a youth entrepreneurship program that helps track daily sales data. It receives messages from young entrepreneurs via WhatsApp or SMS, validates their registration status, and uses an AI agent to process their sales information before responding with appropriate guidance.

How It Works

  1. Message Reception: The workflow listens for incoming messages from two sources - Twilio WhatsApp webhook and Africa's Talking SMS webhook
  2. Channel Detection: A switch node determines whether the message came from WhatsApp or SMS and normalizes the data format
  3. User Validation: The system queries a PostgreSQL database to check if the sender's phone number is registered
  4. Error Handling: If the user is not found, an appropriate "not found" message is sent back via the original channel
  5. AI Processing: Valid users have their messages forwarded to a sales tracking AI agent workflow
  6. Response Delivery: The AI agent's response is sent back to the user through WhatsApp (SMS response path appears incomplete)
  7. Scheduled Nudges: A disabled 7 PM trigger can send daily prompts asking users about their sales, expenses, profit, and credit

Workflow Diagram

graph TD
    A[Twilio WhatsApp Webhook] --> D[Switch - Channel Detection]
    B[Africa's Talking SMS Webhook] --> D
    C[7:00 PM Trigger - DISABLED] --> E[Get Youth Numbers]

    D --> F[setSMSfields - SMS Path]
    D --> G[setSMSfields1 - WhatsApp Path]

    F --> H[Execute SQL Query - User Validation]
    G --> H

    H --> I[ifUserNotFound]
    I --> J[userNotFound - WhatsApp Response]
    I --> K[setUserPhoneNumberAndQuery]

    K --> L[Call Sales Tracking Agent]
    L --> M[Send WhatsApp Response via Twilio]

    E --> N[Send 7:00pm WhatsApp Nudge - DISABLED]
    E --> O[Send 7:00 PM SMS Nudge - DISABLED]

Triggers

  • Twilio WhatsApp Webhook: Receives incoming WhatsApp messages (currently disabled)
  • Africa's Talking SMS Webhook: Receives incoming SMS messages (currently disabled)
  • 7:00 PM Schedule Trigger: Daily scheduled nudges to users (currently disabled)

Nodes Used

Node Type Purpose
Webhook Receive incoming messages from Twilio WhatsApp and Africa's Talking SMS
Switch Route messages based on source channel (SMS vs WhatsApp)
Set Normalize message data format between different channels
PostgreSQL Query user database to validate phone numbers
If Check user validation results and route accordingly
Execute Workflow Call external AI sales tracking agent
Twilio Send WhatsApp responses back to users
HTTP Request Send SMS responses via Africa's Talking API
Google Sheets Read user contact information for scheduled nudges
Schedule Trigger Send daily 7 PM nudges to users

External Services & Credentials Required

Twilio

  • Purpose: WhatsApp message sending and receiving
  • Credential: twilioApi (ID: KIdaZWKXNQtH7wvH)
  • Required: Account SID, Auth Token, WhatsApp phone number

Africa's Talking

  • Purpose: SMS sending and receiving
  • API Key: Required for SMS operations
  • Username: toll_free_sms_ke
  • Short Code: 24436

PostgreSQL (Supabase)

  • Purpose: User validation database
  • Credential: postgres (ID: Hw9XWerQ5RNHaVTk)
  • Database: Contains youthEntrepreneurs table with phone numbers

Google Sheets

  • Purpose: User contact management for nudges
  • Document: "Prototype Itinerary" spreadsheet
  • Sheet: "Nudge test numbers"

Environment Variables

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

Data Flow

Input

  • WhatsApp Messages: Phone number (WaId), message body, sender profile
  • SMS Messages: Phone number (from), message text, timestamp
  • Scheduled Trigger: User data from Google Sheets

Processing

  • Phone number validation against PostgreSQL database
  • Message routing to AI sales tracking agent
  • Response formatting based on original channel

Output

  • WhatsApp Responses: Formatted messages sent via Twilio
  • SMS Responses: Messages sent via Africa's Talking API
  • Error Messages: "Number not found" notifications

Error Handling

The workflow includes basic error handling:

  • User Not Found: If a phone number isn't in the database, users receive a "Sorry, your number was not found in our database" message
  • Channel-Specific Responses: Error messages are sent back through the same channel the user originally used
  • Retry Logic: The sales tracking agent call has retry enabled

Known Limitations

Based on the workflow comments and structure:

  • SMS response path appears incomplete - the Africa's Talking response node isn't properly connected
  • The workflow has multiple disabled nodes, suggesting it's in development/testing phase
  • A/B testing considerations mentioned but not implemented for nudge delivery channels
  • Source tagging for the AI agent isn't implemented, limiting context awareness
  • Webhook connections may interfere with data flow when both are enabled simultaneously
  • Mark - SalesTrackingAgent (ID: SQuf6XRV3xERKdsY): AI agent that processes sales tracking queries and generates responses

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance

  2. Configure Credentials:

    • Set up Twilio API credentials for WhatsApp
    • Configure Africa's Talking API key and username
    • Connect PostgreSQL/Supabase database credentials
    • Set up Google Sheets access (if using nudge features)

  3. Database Setup:

    • Ensure youthEntrepreneurs table exists with phoneNumber and id columns
    • Populate with registered user phone numbers

  4. Webhook Configuration:

    • Enable the appropriate webhook nodes (currently disabled)
    • Configure Twilio webhook URL in your Twilio console
    • Set up Africa's Talking webhook endpoint

  5. Test the Flow:

    • Send test messages from registered phone numbers
    • Verify user validation and AI agent responses
    • Test error handling with unregistered numbers

  6. Enable Scheduled Nudges (Optional):

    • Enable the 7:00 PM trigger node
    • Configure Google Sheets with user contact information
    • Enable the nudge sending nodes

  7. Production Deployment:

    • Enable webhook nodes
    • Monitor message flow and error rates
    • Adjust AI agent responses based on user feedback