Skip to content

SMSTrigger - Francis

This workflow handles incoming SMS messages for a youth entrepreneurship program, routing users to their preferred communication channel (SMS or WhatsApp) and managing message timing to respect evening-only communication windows.

Purpose

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

Based on the workflow implementation, this appears to serve a youth entrepreneurship program where participants can communicate via SMS or WhatsApp. The system enforces communication boundaries by storing daytime messages for later processing and redirecting WhatsApp users to their preferred channel.

How It Works

  1. Incoming SMS Reception: Africa's Talking webhook receives an SMS message
  2. Data Processing: Extracts phone number and message text from the incoming payload
  3. User Lookup: Searches the database for the sender's phone number
  4. User Validation: If user not found, sends an error message and stops
  5. Activity Tracking: Updates the user's last inbound message timestamp
  6. Channel Routing: Checks if user is designated as WhatsApp user
    • If WhatsApp user: Sends redirect message with WhatsApp link
    • If SMS user: Continues to message processing
  7. Timing Control: Checks if it's daytime (before 7 PM) and evening session hasn't started
    • If daytime: Stores message silently for later processing
    • If evening/session active: Processes message immediately
  8. AI Processing: Calls the SalesTrackingAgent workflow to generate a response
  9. Response Handling:
    • If agent returns valid output: Sends SMS response
    • If agent fails/returns empty: Logs error and sends fallback message

Workflow Diagram

graph TD
    A[Africa's Talking Webhook] --> B[setSMSfields]
    B --> C[getUserRecord]
    C --> D{ifUserNotFound}
    D -->|User Not Found| E[userNotFoundSMS]
    D -->|User Found| F[updateLastInboundAt]
    F --> G{isWhatsAppUser}
    G -->|WhatsApp User| H[redirectToWhatsApp]
    G -->|SMS User| I{isDaytimeMessage}
    I -->|Daytime| J[storeDaytimeMessage]
    I -->|Evening/Active| K[setUserPhoneNumnberAndQuery]
    K --> L[Call SalesTrackingAgent]
    L --> M{hasAgentOutput}
    L -->|Error| N[logError]
    M -->|Has Output| O[Send SMS via Africa's Talking]
    M -->|No Output| N
    N --> P[sendFallbackSMS]

Trigger

Webhook Trigger: Africa's Talking SMS webhook endpoint - Method: POST - Path: 0f856185-73f9-46e4-ac8f-fb3458a0bdc3 - Expected payload: Africa's Talking SMS webhook format with from, text, and other SMS metadata

Nodes Used

Node Type Node Name Purpose
Webhook Africa's Talking Incoming messages Receives incoming SMS webhooks
Set setSMSfields Extracts phone number and message text
PostgreSQL getUserRecord Looks up user by phone number
If ifUserNotFound Checks if user exists in database
HTTP Request userNotFoundSMS Sends error message for unknown users
PostgreSQL updateLastInboundAt Updates user's last activity timestamp
If isWhatsAppUser Routes based on user's preferred channel
HTTP Request redirectToWhatsApp Sends WhatsApp redirect message
If isDaytimeMessage Checks timing and session status
PostgreSQL storeDaytimeMessage Stores daytime messages for later
Set setUserPhoneNumnberAndQuery Prepares data for agent workflow
Execute Workflow Call 'Mark - SalesTrackingAgent' Processes message with AI agent
If hasAgentOutput Validates agent response
HTTP Request Send SMS via Africa's Talking Sends AI-generated response
PostgreSQL logError Records errors for debugging
HTTP Request sendFallbackSMS Sends fallback message on errors

External Services & Credentials Required

Africa's Talking SMS API

  • Purpose: Send outbound SMS messages
  • Credentials: API key (currently hardcoded - should be moved to environment variables)
  • Username: toll_free_sms_ke
  • Short code: 24436

PostgreSQL Database

  • Purpose: User data storage and message logging
  • Credential ID: Hw9XWerQ5RNHaVTk (PostgresOnSupabase)
  • Tables used:
    • youthEntrepreneursReal: User profiles and preferences
    • pendingDaytimeMessages: Stored daytime messages
    • errorLog: Error tracking

Dependent Workflow

  • SalesTrackingAgent (ID: SQuf6XRV3xERKdsY): AI agent for generating responses

Environment Variables

Currently, the Africa's Talking API key is hardcoded in the workflow. For production deployment, the following should be moved to environment variables:

  • AFRICAS_TALKING_API_KEY: API key for Africa's Talking service
  • AFRICAS_TALKING_USERNAME: Username for the SMS service
  • AFRICAS_TALKING_SHORTCODE: Short code for outbound messages

Data Flow

Input

  • SMS webhook payload from Africa's Talking containing:
    • from: Sender's phone number
    • text: Message content
    • to: Destination short code
    • date: Timestamp
    • Other metadata

Output

  • SMS responses sent via Africa's Talking API
  • Database updates to user records and message logs
  • WhatsApp redirects for users preferring that channel

Internal Data

  • User profile data including channel preference and session status
  • Stored daytime messages for later processing
  • Error logs for troubleshooting

Error Handling

The workflow includes comprehensive error handling:

  1. Unknown Users: Sends informative error message directing them to contact program coordinator
  2. Agent Failures: Catches errors from the SalesTrackingAgent workflow
  3. Empty Responses: Detects when agent returns no output
  4. Error Logging: Records all errors to database with context
  5. Fallback Messages: Sends user-friendly error message in Swahili when system fails

Known Limitations

  • API key is hardcoded and should be moved to environment variables
  • Daytime cutoff is hardcoded to 7 PM (19:00) with no timezone consideration
  • No rate limiting or spam protection
  • WhatsApp redirect URL is hardcoded
  • No message length validation for SMS limits
  • Mark - SalesTrackingAgent (ID: SQuf6XRV3xERKdsY): AI agent that processes user queries and generates responses

Setup Instructions

  1. Import the workflow into your n8n instance
  2. Configure PostgreSQL connection:
    • Set up credential for PostgreSQL database
    • Ensure tables exist: youthEntrepreneursReal, pendingDaytimeMessages, errorLog
  3. Set up Africa's Talking:
    • Create account and get API key
    • Configure SMS service with username and short code
    • Update hardcoded credentials in HTTP Request nodes
  4. Configure webhook:
    • Note the webhook URL from the trigger node
    • Configure Africa's Talking to send SMS webhooks to this URL
  5. Deploy SalesTrackingAgent workflow:
    • Ensure the referenced workflow (ID: SQuf6XRV3xERKdsY) is available
    • Test the workflow integration
  6. Test the flow:
    • Send test SMS to your Africa's Talking number
    • Verify database updates and response messages
  7. Activate the workflow to start processing live SMS messages

Database Schema Requirements

Ensure your PostgreSQL database has these tables with minimum required columns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
-- User profiles
CREATE TABLE "youthEntrepreneursReal" (
    id SERIAL PRIMARY KEY,
    "phoneNumber" VARCHAR(20),
    channel VARCHAR(20),
    "eveningSessionStarted" BOOLEAN,
    "todayDataCollected" BOOLEAN,
    "lastInboundAt" TIMESTAMP
);

-- Daytime message storage
CREATE TABLE "pendingDaytimeMessages" (
    id SERIAL PRIMARY KEY,
    "phoneNumber" VARCHAR(20),
    content TEXT,
    channel VARCHAR(20),
    "createdAt" TIMESTAMP DEFAULT NOW()
);

-- Error logging
CREATE TABLE "errorLog" (
    id SERIAL PRIMARY KEY,
    "phoneNumber" VARCHAR(20),
    workflow VARCHAR(50),
    "errorMessage" TEXT,
    "rawInput" TEXT,
    "createdAt" TIMESTAMP DEFAULT NOW()
);