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 active agent takeover sessions and routes messages accordingly while logging all interactions.

Purpose

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

How It Works

1. Receive SMS: The workflow receives incoming SMS messages via webhook from an SMS service provider
2. Extract Data: Extracts the sender's phone number and message content from the incoming request
3. Check Agent Status: Queries the database to see if there's an active agent takeover session for this phone number
4. Route Decision: Based on the agent takeover status, the workflow either:
   • Agent Mode: Logs the message to the chat history and responds immediately (agent will handle manually)
   • Bot Mode: Forwards the message to the automated SMS trigger system for AI processing
5. Respond: Returns an "OK" response to acknowledge receipt of the SMS

Workflow Diagram

graph TD
    A[SMS Incoming] --> B[Extract Phone & Message]
    B --> C[Check Agent Takeover]
    C --> D{Agent Owns Conversation?}
    D -->|Yes| E[Log to chatLog Agent Mode]
    D -->|No| F[Forward to SMSTrigger]
    E --> G[Respond OK Agent Mode]
    F --> H[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 request
Postgres	Check Agent Takeover	Queries database for active agent takeover sessions
If	Agent Owns Conversation?	Routes based on agent takeover status
Postgres	Log to chatLog (Agent Mode)	Records message in chat log when agent is handling
HTTP Request	Forward to SMSTrigger	Forwards message to bot system when no agent takeover
Respond to Webhook	Respond OK (Agent Mode)	Acknowledges receipt in agent mode
Respond to Webhook	Respond OK (Bot Mode)	Acknowledges receipt in bot mode

External Services & Credentials Required

Database

• PostgreSQL: Stores agent takeover sessions and chat logs
• Required Credential: Postgres account (connection details for the database)

SMS Service

• Incoming SMS Provider: External service that sends SMS webhooks to this workflow
• Outgoing SMS System: The SMSTrigger webhook endpoint that handles bot responses

Environment Variables

No environment variables are explicitly used in this workflow. Configuration is handled through: - Database connection credentials - Hardcoded webhook URL for SMS forwarding: https://n8n.dev.educate-agent.com/webhook/0f856185-73f9-46e4-ac8f-fb3458a0bdc3

Data Flow

Input (SMS Webhook)

{
  "from": "+254707050598",
  "to": "24436", 
  "text": "User message content",
  "date": "2026-04-08T14:43:39.121Z",
  "id": "unique-message-id",
  "linkId": "0",
  "networkCode": "63902",
  "cost": "None"
}

Database Queries

• Agent Takeover Check: Looks for active sessions where phone_number matches and expires_at > now()
• Chat Log Insert: Records user phone, message, and channel when in agent mode

Output

• HTTP Response: Simple "OK" text response to acknowledge SMS receipt
• Forward Data: When routing to bot, forwards all original SMS fields

Error Handling

The workflow includes basic error handling: - Continue on Error: Both database nodes are configured to continue execution even if queries fail - Always Output Data: Database nodes will output data even on empty results - Timeout Protection: HTTP request to SMSTrigger has a 30-second timeout

Known Limitations

No specific limitations documented in the business context.

Related Workflows

• SMSTrigger Workflow: The target workflow that handles automated bot responses (webhook ID: 0f856185-73f9-46e4-ac8f-fb3458a0bdc3)

Setup Instructions

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

2. Configure Database Credential:

   • Create a PostgreSQL credential named "Postgres account"
   • Ensure it has access to tables: agent_takeover and chatLog

3. Database Schema Requirements:

   -- Agent takeover table
   CREATE TABLE agent_takeover (
     id SERIAL PRIMARY KEY,
     phone_number VARCHAR(20),
     expires_at TIMESTAMP
   );
   
   -- Chat log table  
   CREATE TABLE "chatLog" (
     "userPhone" VARCHAR(20),
     "userQuery" TEXT,
     "agentResponse" TEXT,
     "channel" VARCHAR(10)
   );
   

4. Configure SMS Provider:

   • Point your SMS service to webhook: https://your-n8n-domain/webhook/sifa-sms-router
   • Ensure it sends POST requests with form-encoded data

5. Update SMSTrigger URL:

   • Modify the "Forward to SMSTrigger" node URL to match your SMSTrigger workflow webhook

6. Test the Workflow:

   • Send a test SMS to verify routing works correctly
   • Check database logs to confirm data is being recorded properly

7. Activate: Enable the workflow to start processing live SMS messages