Skip to content

SMSTrigger

This workflow handles incoming SMS messages from users, providing intelligent routing between automated AI responses and human agent takeover scenarios. It manages daytime message queuing, user validation, and integrates with specialized handlers for weekly reports and general sales tracking inquiries.

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. Agent Logging: If agent takeover is active, logs the message for human response and stops processing
  4. User Validation: Extracts phone number and validates the user exists in the system database
  5. Unknown User Handling: Sends error message for unregistered phone numbers
  6. Activity Tracking: Updates the user's last inbound message timestamp
  7. Daytime Queuing: Messages received before 7 PM when evening session hasn't started are stored for later processing
  8. Message Routing: Routes messages to either Weekly Report Handler or Sales Tracking Agent based on user's current stage
  9. Response Processing: Validates AI agent responses and cleans output for SMS compatibility
  10. SMS Delivery: Sends the processed response back to the user via Africa's Talking
  11. Error Handling: Logs errors and sends fallback messages when AI processing fails

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]
    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[Set WR Input]
    M -->|No| O[Call Sales Agent]
    N --> P[Call Weekly Report Handler]
    P --> Q{Has Output?}
    O --> Q
    Q -->|Yes| R[Clean SMS Output]
    Q -->|No| S[Log Error]
    R --> T[Send SMS Response]
    S --> U[Send Fallback SMS]

Trigger

Webhook: Listens for POST requests from Africa's Talking SMS service at endpoint 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, agent takeover checks, message storage, and error logging
Set Data transformation and field mapping
If Conditional logic for routing and validation
Execute Workflow Calls specialized handlers for weekly reports and sales tracking
HTTP Request Sends SMS responses via Africa's Talking API
Sticky Note Documentation and workflow description

External Services & Credentials Required

  • PostgreSQL Database: User data, agent takeover status, message storage, and error logging
  • Africa's Talking SMS API: SMS sending and receiving capabilities

Required Credentials

  • Postgres account: Database connection for user management and logging
  • Africa's Talking API key (embedded in HTTP requests)

Environment Variables

No explicit environment variables are used. API keys and configuration are embedded in the workflow nodes.

Data Flow

Input

  • SMS message payload from Africa's Talking containing:
    • from: Sender's phone number
    • to: Recipient shortcode (24436)
    • text: Message content
    • date: Timestamp
    • id: Message ID

Output

  • SMS response sent back to user 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 Errors: Continues processing if takeover check fails
  2. User Not Found: Sends specific error message to unregistered users
  3. AI Processing Failures: Logs errors to database and sends fallback messages
  4. SMS Delivery: Uses retry mechanisms for reliable message delivery
  5. Database Operations: Continues execution even if logging operations fail

Known Limitations

Based on the workflow structure: - Daytime messages (before 7 PM) are queued but require separate processing - Some nodes are disabled, indicating potential incomplete functionality - Fallback SMS is disabled, which may impact error recovery - API keys are hardcoded rather than using secure credential management

  • Francis - SalesTrackingAgent (aygyT37fIK22WZ9a): Handles general sales and business inquiries
  • Weekly Report Handler (SlShcSkVHkkJ54wK): Processes weekly business report submissions
  • Error Workflow (cuHEGQjAfvuGwIOD): Handles workflow-level errors

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance
  2. Configure Database:
    • Set up PostgreSQL connection with credential ID EJPqF6MDH1ZwAzyv
    • Ensure required tables exist: youthEntrepreneursReal, agent_takeover, pendingDaytimeMessages, errorLog, chatLog
  3. Africa's Talking Setup:
    • Configure webhook URL in Africa's Talking dashboard
    • Update API keys in HTTP Request nodes if needed
    • Verify shortcode 24436 is properly configured
  4. Dependent Workflows:
    • Import and configure the Sales Tracking Agent workflow
    • Import and configure the Weekly Report Handler workflow
  5. Testing:
    • Use the pinned test data to verify webhook reception
    • Test with known user phone numbers
    • Verify database connections and table access
  6. Activation: Enable the workflow to start processing incoming SMS messages