Skip to content

SMS Trigger Workflow

This workflow handles incoming SMS messages from Africa's Talking, routing them through an AI agent system while managing user authentication, daytime message queuing, agent takeover scenarios, and error handling with appropriate fallback responses.

Purpose

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

This workflow serves as the primary SMS entry point for a youth entrepreneur coaching program, processing incoming text messages and routing them to appropriate AI agents or human operators based on user status and timing constraints.

How It Works

  1. Incoming SMS Reception: The workflow receives SMS messages via Africa's Talking webhook
  2. Agent Takeover Check: First checks if a human agent has taken over the conversation for this phone number
  3. User Validation: Looks up the sender's phone number in the youth entrepreneurs database
  4. Daytime Message Handling: If it's before 7 PM and the user hasn't started their evening session, messages are stored silently for later processing
  5. Message Routing: Active messages are routed to either a weekly report handler or the main sales tracking agent based on the user's current stage
  6. Response Delivery: AI-generated responses are sent back via SMS, with error logging and fallback messages for failed cases

Mermaid Diagram

graph TD
    A[Africa's Talking Webhook] --> B[Check Agent Takeover]
    B --> C{Agent Active?}
    C -->|Yes| D[Log SMS for Agent]
    C -->|No| E[Set SMS Fields]
    E --> F[Get User Record]
    F --> G{User Found?}
    G -->|No| H[Send User Not Found SMS]
    G -->|Yes| I[Update Last Inbound Time]
    I --> J{Is Daytime Message?}
    J -->|Yes| K[Store Daytime Message]
    J -->|No| L[Set User Phone and Query]
    K --> L
    L --> M{Is Weekly Report?}
    M -->|Yes| N[Set WR Input] --> O[Call Weekly Report Handler]
    M -->|No| P[Call Sales Tracking Agent]
    O --> Q{Has Agent Output?}
    P --> Q
    Q -->|Yes| R[Send SMS via Africa's Talking]
    Q -->|No| S[Log Error] --> T[Send Fallback SMS]

Trigger

Webhook Trigger: Listens for POST requests from Africa's Talking SMS service at endpoint /webhook/0f856185-73f9-46e4-ac8f-fb3458a0bdc3

Nodes Used

Node Type Purpose
Webhook Receives incoming SMS messages from Africa's Talking
Postgres Database operations for user lookup, logging, and message storage
Set Data transformation and field mapping
If Conditional logic for routing and validation
Execute Workflow Calls other workflows (Sales Tracking Agent, Weekly Report Handler)
HTTP Request Sends SMS responses via Africa's Talking API
Sticky Note Documentation and workflow comments

External Services & Credentials Required

Africa's Talking SMS API

  • API Key: Required for sending SMS responses
  • Username: toll_free_sms_ke
  • Short Code: 24436

PostgreSQL Database

  • Connection: Postgres account credentials
  • Tables Used:
    • youthEntrepreneursReal - User records and status
    • pendingDaytimeMessages - Queued messages for evening processing
    • errorLog - Error tracking and debugging
    • chatLog - Message logging for agent takeover
    • agent_takeover - Human agent session management

Environment Variables

No explicit environment variables are used in this workflow. Configuration is handled through: - Hard-coded API credentials (should be moved to environment variables) - Database connection settings in n8n credentials

Data Flow

Input

  • SMS Message: Text content, sender phone number, timestamp
  • Webhook Data: Africa's Talking message payload with metadata

Output

  • SMS Response: AI-generated or templated text messages
  • Database Records: User activity logs, error logs, pending messages
  • Error Notifications: Fallback messages in case of system failures

Error Handling

The workflow includes comprehensive error handling:

  1. User Not Found: Sends a standard message directing users to contact their program coordinator
  2. Agent Failures: Logs errors to database and sends fallback message in Swahili
  3. Empty Responses: Detects when AI agents return no output and triggers error flow
  4. Database Errors: Uses alwaysOutputData and onError: continueRegularOutput for resilience

Known Limitations

  • API keys are hard-coded in the workflow (security risk)
  • Daytime cutoff is fixed at 7 PM with no timezone handling
  • No rate limiting or spam protection
  • Fallback messages are in mixed languages (English/Swahili)
  • Duplicate workflow paths suggest incomplete refactoring
  • Francis - SalesTrackingAgent_testing (aygyT37fIK22WZ9a): Main AI agent for sales tracking
  • Weekly Report Handler (SlShcSkVHkkJ54wK): Specialized handler for weekly report submissions

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance
  2. Configure Database: Set up PostgreSQL credentials with access to required tables
  3. Africa's Talking Setup:
    • Create account and get API key
    • Configure webhook URL to point to your n8n instance
    • Set up short code 24436
  4. Security: Move API keys to environment variables or n8n credentials
  5. Test: Send test SMS to verify webhook reception and response delivery
  6. Enable: Activate the workflow to start processing live SMS messages

Note: This workflow contains disabled duplicate nodes that should be cleaned up before production deployment.