SMSTrigger - Francis¶

This workflow handles incoming SMS messages from Africa's Talking, intelligently routing users based on their preferred communication channel and implementing time-based message queuing for optimal user experience.

Purpose¶

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

This workflow serves as the primary SMS gateway for a youth entrepreneurship program, managing inbound SMS communications and ensuring users receive responses through their preferred channels at appropriate times.

How It Works¶

Message Reception: Receives incoming SMS messages via Africa's Talking webhook
Data Processing: Extracts and formats the phone number and message content
User Lookup: Queries the database to find the user's record and communication preferences
User Validation: Checks if the sender is registered in the system
Channel Routing: Determines if the user prefers WhatsApp or SMS communication
Time-Based Filtering: For SMS users, checks if it's during daytime hours (before 7 PM)
Message Processing: Either stores daytime messages for later or processes them immediately
AI Agent Integration: Calls the SalesTrackingAgent workflow for intelligent response generation
Response Delivery: Sends the AI-generated response back via SMS
Error Handling: Logs errors and sends fallback messages when needed

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 & No Evening Session| J[storeDaytimeMessage]
    I -->|Evening or Session Started| K[setUserPhoneNumnberAndQuery]
    J --> K
    K --> L[Call SalesTrackingAgent]
    L --> M{hasAgentOutput}
    M -->|Valid Output| N[Send SMS via Africa's Talking]
    M -->|No Output| O[logError]
    L -->|Error| O
    O --> P[sendFallbackSMS]

Trigger¶

Webhook Trigger: Listens for POST requests from Africa's Talking at the /kdp endpoint when SMS messages are received.

Nodes Used¶

Node Type	Node Name	Purpose
Webhook	Africa's Talking Incoming messages	Receives incoming SMS webhooks
Set	setSMSfields	Formats phone number and message text
Postgres	getUserRecord	Looks up user information in database
If	ifUserNotFound	Checks if user exists in system
HTTP Request	userNotFoundSMS	Sends error message for unknown users
Postgres	updateLastInboundAt	Updates user's last contact timestamp
If	isWhatsAppUser	Determines user's preferred channel
HTTP Request	redirectToWhatsApp	Redirects WhatsApp users to WhatsApp
If	isDaytimeMessage	Checks if message is during daytime hours
Postgres	storeDaytimeMessage	Stores daytime messages for later processing
Set	setUserPhoneNumnberAndQuery	Prepares data for AI agent
Execute Workflow	Call 'Francis - SalesTrackingAgent'	Processes message with AI agent
If	hasAgentOutput	Validates AI agent response
HTTP Request	Send SMS via Africa's Talking	Sends response SMS
Postgres	logError	Records errors for debugging
HTTP Request	sendFallbackSMS	Sends generic error message

External Services & Credentials Required¶

Africa's Talking SMS API¶

Purpose: Send and receive SMS messages
Credentials: API key (currently hardcoded - should be moved to environment variables)
Username: toll_free_sms_ke
Short Code: 24436

PostgreSQL Database (Supabase)¶

Purpose: User data storage and message queuing
Credential Name: PostgresOnSupabase
Tables Used:
- youthEntrepreneursReal - User profiles and preferences
- pendingDaytimeMessages - Queued daytime messages
- errorLog - Error tracking

Environment Variables¶

No environment variables are currently used. The following should be migrated from hardcoded values:

AFRICASTALKING_API_KEY
AFRICASTALKING_USERNAME
AFRICASTALKING_SHORT_CODE
WHATSAPP_REDIRECT_NUMBER

Data Flow¶

Input¶

SMS Webhook Data: Phone number, message text, timestamp, and metadata from Africa's Talking

Processing¶

User lookup and channel preference determination
Time-based message routing
AI agent processing for response generation

Output¶

SMS Responses: Intelligent replies via Africa's Talking
WhatsApp Redirects: Instructions to contact via WhatsApp
Database Updates: User activity tracking and message storage

Error Handling¶

The workflow includes comprehensive error handling:

Unknown Users: Sends informative message directing them to contact program coordinator
AI Agent Failures: Logs errors to database and sends fallback message in Swahili
Empty Responses: Validates AI output and handles null/empty responses
Retry Logic: SalesTrackingAgent call includes retry on failure

Known Limitations¶

API keys are hardcoded in the workflow (security risk)
Daytime cutoff is fixed at 7 PM (19:00) with no timezone consideration
No rate limiting or spam protection
WhatsApp redirect number is hardcoded
Error messages are in mixed languages (English/Swahili)

Francis - SalesTrackingAgent (z3uutKAWYHk3qbQE): AI agent that processes user queries and generates responses

Setup Instructions¶

Import Workflow: Import the JSON into your n8n instance
Configure Database Connection:
- Set up PostgreSQL credential named "PostgresOnSupabase"
- Ensure tables exist: youthEntrepreneursReal, pendingDaytimeMessages, errorLog
Set Up Africa's Talking:
- Create Africa's Talking account and get API credentials
- Configure webhook URL to point to your n8n webhook endpoint
- Update hardcoded API key in HTTP Request nodes
Configure Dependencies:
- Ensure "Francis - SalesTrackingAgent" workflow is imported and active
- Verify workflow ID matches in the Execute Workflow node
Test Setup:
- Send test SMS to your Africa's Talking number
- Verify webhook receives data and processes correctly
- Check database for proper user lookup and logging
Security Hardening:
- Move API keys to environment variables
- Set up proper credential management
- Configure webhook authentication if needed