Skip to content

[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 active agent takeovers 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. Receives SMS: The workflow starts when an SMS message is received via webhook
  2. Extracts Data: Pulls the sender's phone number and message content from the incoming SMS
  3. Checks Agent Status: Queries the database to see if a human agent has taken over this conversation
  4. Routes Message:
    • If an agent owns the conversation: logs the message to the chat history and responds with "OK"
    • If no agent takeover exists: forwards the SMS to the automated bot system and responds with "OK"

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 SMS data with fields like from, to, text, date, id, and optional 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
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) Records SMS in chat log when agent is handling conversation
HTTP Request Forward to SMSTrigger Forwards SMS to bot system when no agent takeover exists
Respond to Webhook Respond OK (Agent Mode) Returns success response for agent-handled messages
Respond to Webhook Respond OK (Bot Mode) Returns success response for bot-forwarded messages

External Services & Credentials Required

Database Connection

  • Service: PostgreSQL
  • Credential Name: sifaV4Dev
  • Required For: Checking agent takeover status and logging chat messages
  • Tables Used:
    • agent_takeover (read access)
    • chatLog (write access)

SMS Bot System

  • Service: Internal n8n webhook endpoint
  • URL: https://n8n.dev.educate-agent.com/webhook/0f856185-73f9-46e4-ac8f-fb3458a0bdc3
  • Purpose: Forwards SMS messages to automated bot system

Environment Variables

No environment variables are explicitly used in this workflow. All configuration is handled through: - Database credentials (stored in n8n credential system) - Hardcoded webhook URLs for SMS forwarding

Data Flow

Input (SMS Webhook)

1
2
3
4
5
6
7
8
{
  "from": "+254707050598",
  "to": "24436", 
  "text": "User message content",
  "date": "2026-04-08T14:43:39.121Z",
  "id": "unique-message-id",
  "linkId": "0"
}

Processing

  • Extracts youthPhone and youthMessage from input
  • Queries for active agent takeover using phone number
  • Routes based on takeover status

Output

  • HTTP 200 response with "OK" text
  • Side effects: Database logging (agent mode) or SMS forwarding (bot mode)

Error Handling

The workflow includes basic error handling: - Database nodes are configured with continueRegularOutput to prevent workflow failure - alwaysOutputData is enabled on database queries to handle empty results - HTTP request has a 30-second timeout configured

Known Limitations

  • Hardcoded webhook URL for SMS forwarding limits flexibility
  • No validation of incoming SMS format
  • Agent takeover expiration relies on database timestamp comparison
  • No retry mechanism for failed database operations or HTTP requests

This workflow forwards messages to another n8n workflow accessible at webhook ID 0f856185-73f9-46e4-ac8f-fb3458a0bdc3, which likely handles the automated bot responses.

Setup Instructions

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

  2. Configure Database Credential:

    • Create a PostgreSQL credential named sifaV4Dev
    • Ensure it has access to agent_takeover and chatLog tables

  3. Update Webhook URLs:

    • Note the webhook URL generated for "SMS Incoming"
    • Update your SMS provider to send messages to this endpoint
    • Verify the forwarding URL in "Forward to SMSTrigger" matches your bot system

  4. Database Schema Requirements: 

    1
2
3
4
5
    -- agent_takeover table should have:
-- id, phone_number, expires_at columns

-- chatLog table should have:
-- userPhone, userQuery, agentResponse, channel columns

  5. Test the Workflow:

    • Send a test SMS to verify routing logic
    • Check database logs to ensure proper data recording
    • Verify bot forwarding works correctly

  6. Activate: Set the workflow to active status to begin processing live SMS messages