SMSTrigger - Francis

An SMS inbound handler that processes incoming text messages, routes users to their preferred communication channel, and manages message timing to respect user availability windows.

Purpose

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

How It Works

1. Incoming SMS Processing: The workflow receives SMS messages via Africa's Talking webhook and extracts the sender's phone number and message content.

2. User Lookup: Queries the database to find the user record based on their phone number, retrieving their preferred communication channel and session status.

3. User Validation: If the user is not found in the system, sends an error message directing them to contact their program coordinator.

4. Channel Routing: For users designated as WhatsApp users, redirects them to WhatsApp with a link to contact Sifa directly.

5. Time-Based Message Handling: For SMS users, checks if it's daytime (before 7 PM) and if their evening session hasn't started. Daytime messages are stored silently for later processing.

6. Real-Time Processing: Evening messages or messages from users with active sessions are immediately processed by the Francis SalesTrackingAgent.

7. Response Delivery: Valid agent responses are sent back via SMS, while errors trigger fallback messages and are logged for monitoring.

Mermaid Diagram

graph TD
    A[Africas Talking Incoming messages] --> B[setSMSfields]
    B --> C[getUserRecord]
    C --> D[ifUserNotFound]
    D -->|User Not Found| E[userNotFoundSMS1]
    D -->|User Found| F[updateLastInboundAt]
    F --> G[isWhatsAppUser]
    G -->|WhatsApp User| H[redirectToWhatsApp1]
    G -->|SMS User| I[isDaytimeMessage]
    I -->|Daytime| J[storeDaytimeMessage]
    I -->|Evening/Active| K[setUserPhoneNumnberAndQuery]
    J --> K
    K --> L[Call 'Francis - SalesTrackingAgent']
    L -->|Success| M[hasAgentOutput]
    L -->|Error| N[logError]
    M -->|Has Output| O[Send SMS via Africa's Talking1]
    M -->|No Output| N
    N --> P[sendFallbackSMS1]

Trigger

Webhook: Africa's Talking incoming SMS webhook at path 0f856185-73f9-46e4-ac8f-fb3458a0bdc3

The webhook receives POST requests from Africa's Talking when SMS messages are sent to the configured short code (24436).

Nodes Used

Node Type	Node Name	Purpose
Webhook	Africas Talking Incoming messages	Receives incoming SMS webhooks from Africa's Talking
Set	setSMSfields	Extracts and formats phone number and message text
Postgres	getUserRecord	Queries user database to find sender's record
If	ifUserNotFound	Checks if user exists in the system
Postgres	updateLastInboundAt	Updates user's last inbound message timestamp
If	isWhatsAppUser	Determines if user prefers WhatsApp communication
If	isDaytimeMessage	Checks if message is during daytime hours
Postgres	storeDaytimeMessage	Stores daytime messages for later processing
Set	setUserPhoneNumnberAndQuery	Prepares data for agent processing
Execute Workflow	Call 'Francis - SalesTrackingAgent'	Processes user query through AI agent
If	hasAgentOutput	Validates agent response
Postgres	logError	Records errors for monitoring
HTTP Request	Multiple SMS nodes	Send SMS responses via Africa's Talking API

External Services & Credentials Required

Africa's Talking SMS API

• Credential: AT Header Auth (HTTP Header Authentication)
• Purpose: Send SMS responses
• Endpoint: https://api.africastalking.com/version1/messaging
• Required Headers: API key authentication

PostgreSQL Database

• Credential: kdpTables and Postgres account 2
• Purpose: User data storage and message logging
• Tables Used:
  • youthEntrepreneursReal: User records with channel preferences
  • pendingDaytimeMessages: Stored daytime messages
  • errorLog: Error tracking

Environment Variables

No explicit environment variables are used. Configuration is handled through: - Africa's Talking username: toll_free_sms_ke - SMS short code: 24436 - WhatsApp contact link: https://wa.me/254203892316

Data Flow

Input

• SMS webhook payload containing:
  • body.from: Sender's phone number
  • body.text: Message content
  • body.to: Destination short code

Output

• SMS responses sent back to users
• Database records updated/created:
  • User last inbound timestamp
  • Pending daytime messages
  • Error logs

Processing

• Phone number normalization (removes leading +)
• User channel preference routing
• Time-based message queuing
• AI agent query processing

Error Handling

The workflow includes comprehensive error handling:

1. User Not Found: Sends informational SMS directing users to contact their coordinator
2. Agent Failures: Catches errors from the SalesTrackingAgent workflow and logs them
3. Empty Responses: Detects when the agent returns no output and treats as an error
4. Fallback Messages: Sends generic error messages in Swahili when processing fails
5. Error Logging: Records all errors with phone number, workflow name, and raw input for debugging

Known Limitations

Based on the workflow configuration: - Daytime messages are stored but require separate processing workflow - WhatsApp redirection is manual (requires user to click link) - Hard-coded time threshold (7 PM) for daytime detection - Single language support for error messages (English/Swahili mix)

Related Workflows

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

Setup Instructions

1. Import Workflow: Import the JSON configuration into your n8n instance

2. Configure Credentials:

   • Set up Africa's Talking API credentials with your API key
   • Configure PostgreSQL connections to your database

3. Database Setup: Ensure these tables exist:

   -- User records table
   youthEntrepreneursReal (id, channel, eveningSessionStarted, todayDataCollected, lastInboundAt, phoneNumber)
   
   -- Pending messages table
   pendingDaytimeMessages (phoneNumber, content, channel, nairobiTime, date)
   
   -- Error logging table
   errorLog (phoneNumber, workflow, errorMessage, rawInput)
   

4. Webhook Configuration:

   • Copy the webhook URL from the workflow
   • Configure it in your Africa's Talking SMS settings
   • Ensure the webhook path matches: 0f856185-73f9-46e4-ac8f-fb3458a0bdc3

5. Dependencies: Deploy the Francis SalesTrackingAgent workflow first

6. Testing: Send a test SMS to your short code to verify the complete flow

7. Monitoring: Check the errorLog table regularly for any processing issues