Skip to content

SMS Trigger Workflow

This workflow handles incoming SMS messages from users, routing them through an AI agent system while managing daytime message queuing, user validation, and agent takeover functionality for a youth entrepreneurship program.

Purpose

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

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 either to a weekly report handler (for users in weekly report stages) or to the main sales tracking agent
  6. Response Processing: Agent responses are cleaned for SMS compatibility and sent back to the user
  7. Error Handling: Failed agent calls are logged and fallback messages are sent in Swahili

Workflow Diagram

graph TD
    A[SMS 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{Daytime Message?}
    J -->|Yes| K[Store Daytime Message]
    J -->|No| L[Set User Data]
    K --> L
    L --> M{Weekly Report Stage?}
    M -->|Yes| N[Call Weekly Report Handler]
    M -->|No| O[Call Sales Tracking Agent]
    N --> P{Has Agent Output?}
    O --> P
    P -->|Yes| Q[Clean SMS Output]
    P -->|No| R[Log Error]
    Q --> S[Send SMS Response]
    R --> T[Send Fallback SMS]

Trigger

Webhook: Africa's Talking incoming SMS webhook at path 0f856185-73f9-46e4-ac8f-fb3458a0bdc3 - Method: POST - Receives SMS data including sender phone number, message content, and metadata

Nodes Used

Node Type Purpose
Webhook Receives incoming SMS messages from Africa's Talking
Postgres Database operations for user lookup, logging, and message storage
If Conditional routing based on agent takeover, user existence, time, and message type
Set Data transformation and field mapping
Execute Workflow Calls external workflows for agent processing and weekly reports
HTTP Request Sends SMS responses via Africa's Talking API

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

  • Credential Name: "Postgres account"
  • Tables Used:
    • youthEntrepreneursReal - User records and session state
    • agent_takeover - Human agent takeover tracking
    • pendingDaytimeMessages - Queued daytime messages
    • chatLog - Conversation logging for agents
    • errorLog - Error tracking and debugging

Environment Variables

No explicit environment variables are used in this workflow. Configuration is handled through: - Hard-coded Africa's Talking API credentials - Database connection via n8n credentials system - Workflow IDs for sub-workflow calls

Data Flow

Input

  • SMS webhook payload containing:
    • body.from: Sender phone number
    • body.text: Message content
    • body.to: Recipient short code
    • body.date: Message timestamp

Output

  • SMS responses sent via Africa's Talking API
  • Database records updated for user activity and message logging
  • Error logs for failed processing attempts

Error Handling

The workflow includes comprehensive error handling:

  1. Agent Takeover Failures: Continues processing if takeover check fails
  2. User Not Found: Sends specific error message asking user to contact program coordinator
  3. Agent Processing Errors: Logs errors to database and sends fallback message in Swahili
  4. Empty Agent Responses: Treated as errors and logged accordingly
  5. Workflow Execution Errors: Sub-workflow calls have retry logic and error output handling

Known Limitations

Based on the workflow structure: - Daytime messages are queued but no automatic evening processing is visible - Hard-coded API credentials pose security risks - No rate limiting or spam protection mechanisms - Fallback messages are only in Swahili, may not suit all users - Agent takeover system requires manual database management

  • Francis - SalesTrackingAgent (aygyT37fIK22WZ9a): Main AI agent for handling user queries
  • 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 Connection:
    • Set up PostgreSQL credential named "Postgres account"
    • Ensure all required tables exist with proper schema
  3. Set Up Africa's Talking:
    • Replace API key with your actual credentials
    • Configure webhook URL in Africa's Talking dashboard
    • Verify short code and username settings
  4. Configure Sub-Workflows:
    • Ensure the Sales Tracking Agent workflow is imported and active
    • Ensure the Weekly Report Handler workflow is imported and active
  5. Test Setup:
    • Send test SMS to verify webhook reception
    • Check database connections and table access
    • Verify SMS sending functionality
  6. Security Review:
    • Move hard-coded credentials to n8n credential system
    • Review database permissions and access controls