[DEV] Sifa SMS Router

This workflow acts as an intelligent SMS routing system that determines whether incoming SMS messages should be handled by a human agent or forwarded to an automated bot system. It checks for agent takeover status and special help keywords to route messages appropriately.

Purpose

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

How It Works

1. Receives SMS: The workflow starts when an SMS message is received via webhook
2. Extracts Data: Parses the phone number and message content from the incoming SMS
3. Checks for Help Keywords: First checks if the message contains help keywords (HELP, HELP ME, MSAADA)
4. Routes Help Messages: If help keywords are detected, routes to a specialized help handler workflow
5. Checks Agent Takeover: For non-help messages, queries the database to see if an agent has taken over the conversation
6. Routes Based on Status:
   • If agent takeover exists: Logs the message and responds with OK
   • If no agent takeover: Forwards the SMS to the bot system for automated handling
7. Responds: Always returns an OK response to acknowledge receipt

Workflow Diagram

graph TD
    A[SMS Incoming] --> B[Extract Phone & Message]
    B --> C[HELP Keyword?]
    C -->|Yes| D[Set Channel]
    C -->|No| E[Check Agent Takeover]
    D --> F[Call helpKeywordHandler]
    F --> G[Respond OK - Help Mode]
    E --> H[Agent Owns Conversation?]
    H -->|Yes| I[Log to chatLog - Agent Mode]
    H -->|No| J[Forward to SMSTrigger]
    I --> K[Respond OK - Agent Mode]
    J --> L[Respond OK - Bot Mode]

Trigger

• Type: Webhook (POST)
• Path: /sifa-sms-router
• Method: POST
• Expected Format: Form-encoded data with SMS details (from, to, text, date, id, linkId)

Nodes Used

Node Type	Node Name	Purpose
Webhook	SMS Incoming	Receives incoming SMS messages via HTTP POST
Set	Extract Phone & Message	Extracts phone number and message text from webhook payload
If	HELP Keyword?	Checks if message contains help keywords (HELP, HELP ME, MSAADA)
Set	Set Channel	Prepares data for help keyword handler
Execute Workflow	Call helpKeywordHandler	Calls external workflow to handle help requests
Postgres	Check Agent Takeover	Queries database for active agent takeover records
If	Agent Owns Conversation?	Determines routing based on agent takeover status
Postgres	Log to chatLog (Agent Mode)	Logs message when agent has taken over conversation
HTTP Request	Forward to SMSTrigger	Forwards SMS to bot system when no agent takeover
Respond to Webhook	Multiple response nodes	Returns OK status for different routing paths

External Services & Credentials Required

Database

• PostgreSQL: Requires connection to Sifa database
• Credential Name: sifaV4Dev
• Tables Used:
  • agent_takeover: Stores agent takeover records with expiration
  • chatLog: Logs conversation history

External Workflows

• Help Keyword Handler: Workflow ID ethAUW0G7i8qZ9CI
• SMS Trigger: Webhook endpoint at https://n8n.dev.educate-agent.com/webhook/0f856185-73f9-46e4-ac8f-fb3458a0bdc3

Environment Variables

No specific environment variables are used in this workflow. Configuration is handled through: - Database credentials - Hardcoded webhook URLs - Workflow IDs

Data Flow

Input

• SMS Webhook Data:
  • from: Sender phone number
  • to: Recipient short code
  • text: Message content
  • date: Timestamp
  • id: Message ID
  • linkId: Optional link identifier

Output

• HTTP Response: Always returns "OK" with 200 status
• Database Logs: Messages logged to chatLog table when agent is active
• Forwarded Data: SMS data forwarded to bot system when no agent takeover

Error Handling

The workflow includes basic error handling: - Database operations are set to continue on error - HTTP requests have a 30-second timeout - All nodes use continueRegularOutput error mode to prevent workflow failure - Always outputs data even when database queries return no results

Known Limitations

• Help keyword detection is case-insensitive but requires exact matches
• Agent takeover check relies on database availability
• No retry mechanism for failed HTTP requests to external systems
• Hardcoded URLs make the workflow environment-specific

Related Workflows

• Help Keyword Handler (ID: ethAUW0G7i8qZ9CI): Handles help-related SMS messages
• SMS Trigger Workflow: Processes automated bot responses (external webhook)

Setup Instructions

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

2. Configure Database Credential:

   • Create PostgreSQL credential named sifaV4Dev
   • Configure connection to Sifa database
   • Ensure access to agent_takeover and chatLog tables

3. Update URLs (if needed):

   • Modify the SMS Trigger webhook URL in "Forward to SMSTrigger" node
   • Update help keyword handler workflow ID if different

4. Set Up Database Tables:

   -- Ensure agent_takeover table exists
   CREATE TABLE IF NOT EXISTS agent_takeover (
     id SERIAL PRIMARY KEY,
     phone_number VARCHAR(20),
     expires_at TIMESTAMP
   );
   
   -- Ensure chatLog table exists
   CREATE TABLE IF NOT EXISTS "chatLog" (
     "userPhone" VARCHAR(20),
     "userQuery" TEXT,
     "agentResponse" TEXT,
     "channel" VARCHAR(10)
   );
   

5. Test the Webhook:

   • Activate the workflow
   • Send a test POST request to the webhook endpoint
   • Verify routing works correctly for both agent and bot modes

6. Configure Help Keywords:

   • Ensure the help keyword handler workflow is available
   • Test with messages containing "HELP", "HELP ME", or "MSAADA"