Skip to content

SMSTrigger - Francis_testing

An SMS inbound handler that processes incoming text messages, validates users against a database, and routes messages appropriately based on timing and user preferences. The workflow includes intelligent daytime message storage and error handling with fallback responses.

Purpose

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

This workflow serves as the primary entry point for SMS-based interactions, handling user validation, message routing, and timing-based message management. It ensures that users receive appropriate responses while managing communication preferences and system availability.

How It Works

  1. Message Reception: Incoming SMS messages are received via Africa's Talking webhook
  2. Data Processing: The SMS content and sender phone number are extracted and formatted
  3. User Validation: The system looks up the sender in the youth entrepreneurs database
  4. User Not Found: If no user record exists, an error message is sent via SMS
  5. Activity Tracking: For valid users, the last inbound message timestamp is updated
  6. Timing Check: The system determines if it's daytime (before 7 PM) and if the user hasn't started their evening session
  7. Daytime Storage: Messages received during daytime hours are stored silently for later processing
  8. Evening Processing: Messages received during evening hours or from users with active sessions are processed immediately
  9. Agent Processing: Valid messages are sent to the SalesTrackingAgent workflow for intelligent response generation
  10. Response Validation: The system checks if the agent provided a valid response
  11. SMS Delivery: Valid responses are sent back to the user via SMS
  12. Error Handling: Failed processing attempts are logged and fallback messages are sent

Workflow Diagram

graph TD
    A[Africas Talking Incoming messages] --> B[setSMSfields]
    B --> C[getUserRecord]
    C --> D[ifUserNotFound]
    D -->|User Not Found| E[userNotFoundSMS1]
    D -->|User Found| F[updateLastInboundAt]
    F --> G[isDaytimeMessage]
    G -->|Daytime| H[storeDaytimeMessage]
    G -->|Evening/Active| I[setUserPhoneNumnberAndQuery]
    H --> I
    I --> J[Call 'Francis - SalesTrackingAgent']
    J -->|Success| K[hasAgentOutput]
    J -->|Error| L[logError]
    K -->|Valid Output| M[Send SMS via Africa's Talking1]
    K -->|No Output| L
    L --> N[sendFallbackSMS1]

Trigger

Webhook Trigger: Africa's Talking incoming SMS webhook - Method: POST - Path: /webhook/0f856185-73f9-46e4-ac8f-fb3458a0bdc3 - Expected payload: SMS message data including sender phone number and message content

Nodes Used

Node Type Node Name Purpose
Webhook Africas Talking Incoming messages Receives incoming SMS messages
Set setSMSfields Extracts and formats SMS content and phone number
Postgres getUserRecord Looks up user in youth entrepreneurs database
If ifUserNotFound Checks if user exists in database
HTTP Request userNotFoundSMS1 Sends error message for unknown users
Postgres updateLastInboundAt Updates user's last message timestamp
If isDaytimeMessage Determines if message is during daytime hours
Postgres storeDaytimeMessage Stores daytime messages for later processing
Set setUserPhoneNumnberAndQuery Prepares data for agent processing
Execute Workflow Call 'Francis - SalesTrackingAgent' Processes message through AI agent
If hasAgentOutput Validates agent response
Postgres logError Records processing errors
HTTP Request Send SMS via Africa's Talking1 Sends successful responses
HTTP Request sendFallbackSMS1 Sends fallback error messages
Sticky Note Sticky Note Documentation and workflow description

External Services & Credentials Required

Africa's Talking SMS API

  • Purpose: Send and receive SMS messages
  • Credentials: API key required
  • Endpoints:
    • Incoming webhook for message reception
    • Messaging API for sending responses

PostgreSQL Database

  • Purpose: User management and message storage
  • Credential Name: kdpTestEnv
  • Tables Used:
    • youthEntrepreneursReal: User records and preferences
    • pendingDaytimeMessages: Stored daytime messages
    • errorLog: Error tracking and debugging

Environment Variables

No explicit environment variables are configured in this workflow. All configuration is handled through: - Hard-coded API keys (should be moved to credentials) - Database connection credentials - Workflow references

Data Flow

Input

  • SMS Message: Raw SMS data from Africa's Talking webhook
  • Required Fields:
    • body.from: Sender phone number
    • body.text: Message content

Output

  • SMS Response: Automated reply sent to user
  • Database Updates: User activity tracking and message storage
  • Error Logs: Failed processing attempts recorded

Internal Data

  • User validation and channel preferences
  • Timing-based message routing decisions
  • Agent-generated responses

Error Handling

The workflow includes comprehensive error handling:

  1. User Not Found: Sends informative SMS about contacting program coordinator
  2. Agent Processing Errors: Captured and logged with fallback response
  3. Empty Agent Output: Detected and handled with error logging
  4. Database Errors: Workflow continues with error output paths
  5. Fallback Messages: Swahili error message sent when processing fails

Error details are stored in the errorLog table including: - Phone number - Workflow name - Error message - Raw input content

Known Limitations

Based on the workflow implementation: - API keys are hard-coded in HTTP request nodes (security risk) - Daytime cutoff is fixed at 7 PM (19:00) with no timezone handling - No rate limiting or spam protection - Single language fallback message (Swahili only) - No message length validation for SMS limits

  • Francis - SalesTrackingAgent_testing (SGrZ4QpudpulAtLG): AI agent that processes user queries and generates responses

Setup Instructions

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

  2. Configure Database Credentials:

    • Create PostgreSQL credential named kdpTestEnv
    • Ensure access to required tables:
      • youthEntrepreneursReal
      • pendingDaytimeMessages
      • errorLog

  3. Set Up Africa's Talking:

    • Create Africa's Talking account
    • Obtain API key
    • Configure webhook URL in Africa's Talking dashboard
    • Update API key in HTTP request nodes (move to credentials for security)

  4. Configure Related Workflows:

    • Ensure "Francis - SalesTrackingAgent_testing" workflow is available
    • Verify workflow ID matches: SGrZ4QpudpulAtLG

  5. Database Schema:

    • Verify required columns exist in user table:
      • phoneNumber, channel, eveningSessionStarted, todayDataCollected, lastInboundAt
    • Set up pending messages table with appropriate schema
    • Configure error logging table

  6. Test Setup:

    • Send test SMS to verify webhook reception
    • Validate database connections
    • Test error handling paths

  7. Security Hardening:

    • Move API keys to n8n credentials
    • Implement webhook authentication
    • Add input validation and sanitization