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 interaction windows.

Purpose

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

This workflow serves as the primary SMS intake system for program participants. It validates users against a database, routes WhatsApp-designated users to WhatsApp, stores daytime messages for later processing, and handles evening messages immediately through an AI agent system.

How It Works

1. Message Reception: Receives incoming SMS messages via Africa's Talking webhook
2. User Lookup: Extracts phone number and looks up user in the database
3. User Validation: If user not found, sends error message and stops
4. Channel Routing: If user is designated for WhatsApp, redirects them with a link
5. Time Gating: For SMS users, checks if it's daytime (before 7 PM) and evening session hasn't started
6. Message Storage: Daytime messages are stored silently in pendingDaytimeMessages table
7. Agent Processing: Evening messages are processed immediately by the Francis SalesTrackingAgent
8. Response Delivery: Agent responses are sent back via SMS, with fallback error handling

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| K[setUserPhoneNumnberAndQuery]
    J --> K
    K --> L[Call Francis SalesTrackingAgent]
    L --> M{hasAgentOutput}
    M -->|Has Output| N[Send SMS via Africa's Talking]
    M -->|No Output| O[logError]
    L -->|Error| O
    O --> P[sendFallbackSMS]

Trigger

Webhook: POST endpoint at /kdp that receives incoming SMS messages from Africa's Talking service. The webhook expects form-encoded data containing message details including sender phone number, message text, and metadata.

Nodes Used

Node Type	Node Name	Purpose
Webhook	Africa's Talking Incoming messages	Receives incoming SMS webhooks
Set	setSMSfields	Extracts and formats phone number and message text
Postgres	getUserRecord	Looks up user by phone number 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 message timestamp
If	isWhatsAppUser	Checks if user prefers WhatsApp
HTTP Request	redirectToWhatsApp	Sends WhatsApp redirect message
If	isDaytimeMessage	Checks if message is during daytime hours
Postgres	storeDaytimeMessage	Stores daytime messages for later processing
Set	setUserPhoneNumnberAndQuery	Prepares data for agent workflow
Execute Workflow	Call 'Francis - SalesTrackingAgent'	Processes message through AI agent
If	hasAgentOutput	Validates agent response
HTTP Request	Send SMS via Africa's Talking	Sends agent response back to user
Postgres	logError	Records errors for debugging
HTTP Request	sendFallbackSMS	Sends generic error message

External Services & Credentials Required

Africa's Talking SMS API

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

PostgreSQL Database

• Credential Name: PostgresOnSupabase
• Tables Used:
  • youthEntrepreneursReal - User records with phone numbers and preferences
  • pendingDaytimeMessages - Stores messages received during daytime
  • errorLog - Error tracking and debugging

Related Workflows

• Francis - SalesTrackingAgent (ID: z3uutKAWYHk3qbQE) - AI agent for processing user queries

Environment Variables

No explicit environment variables are used. Configuration is handled through: - Hardcoded API credentials (should be moved to environment variables) - Database connection via n8n credentials system - Time zone logic assumes Nairobi time (UTC+3)

Data Flow

Input

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

Processing

• User validation against database
• Channel preference routing
• Time-based message handling
• AI agent processing for immediate responses

Output

• SMS Responses: Direct replies via Africa's Talking API
• Database Updates: User activity tracking and message storage
• Error Logs: Debugging information for failed processes

Error Handling

The workflow includes comprehensive error handling:

1. Unknown Users: Sends polite error message asking to contact program coordinator
2. Agent Failures: Catches errors from the SalesTrackingAgent workflow and logs them
3. Empty Responses: Detects when agent returns no output and logs as error
4. Fallback Messages: Sends generic "try again later" message in Swahili when errors occur
5. Error Logging: All errors are stored in errorLog table with context for debugging

Known Limitations

• API keys are hardcoded in the workflow (security risk)
• Time zone handling assumes Nairobi time without explicit timezone conversion
• No rate limiting or spam protection
• Daytime messages are stored but no mechanism shown for processing them later
• WhatsApp redirect uses a fixed phone number that may need updating

Related Workflows

• Francis - SalesTrackingAgent: Processes user queries and generates responses for SMS users

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Database:
   • Set up PostgreSQL connection with credential name PostgresOnSupabase
   • Ensure tables youthEntrepreneursReal, pendingDaytimeMessages, and errorLog exist
3. Africa's Talking Setup:
   • Replace the hardcoded API key with your own
   • Configure webhook URL in Africa's Talking dashboard to point to your n8n webhook
   • Verify short code and username match your account
4. Link Agent Workflow: Ensure the Francis SalesTrackingAgent workflow is imported and active
5. Test: Send a test SMS to verify the complete flow works
6. Security: Move API credentials to environment variables or n8n credentials store