[DEV] Sifa WhatsApp Router

This workflow acts as an intelligent routing system for incoming WhatsApp messages, determining whether messages should be handled by a human agent or forwarded to an automated bot system based on active agent takeover records.

Purpose

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

How It Works

1. Incoming Message Reception: The workflow receives WhatsApp messages via a webhook endpoint from Twilio
2. Data Extraction: Extracts the sender's phone number and message content from the incoming payload
3. Agent Takeover Check: Queries the database to see if there's an active agent takeover for this phone number
4. Routing Decision: Based on the takeover status, routes the message to either:
   • Agent Mode: Logs the message to the chat history and responds with a simple acknowledgment
   • Bot Mode: Forwards the complete message payload to another n8n workflow for automated processing
5. Response: Returns an "OK" response to Twilio to acknowledge receipt

Workflow Diagram

graph TD
    A[WhatsApp 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 WhatsAppTrigger]
    E --> G[Respond OK Agent Mode]
    F --> H[Respond OK Bot Mode]

Trigger

Webhook: Listens for POST requests at the endpoint /sifa-whatsapp-router - Expects Twilio WhatsApp webhook format - Configured to use response node for acknowledgment

Nodes Used

Node Type	Node Name	Purpose
Webhook	WhatsApp Incoming	Receives incoming WhatsApp messages from Twilio
Set	Extract Phone & Message	Extracts and formats phone number and message content
Postgres	Check Agent Takeover	Queries database for active agent takeover records
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 WhatsAppTrigger	Forwards message to bot workflow
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

Required Credentials

• PostgreSQL Database: For querying agent takeover records and logging chat messages
  • Tables needed: agent_takeover, chatLog
• n8n Webhook Access: For forwarding messages to the bot workflow

External Services

• Twilio WhatsApp API: Sends webhook requests to this workflow
• Target n8n Workflow: Receives forwarded messages at https://n8n.dev.educate-agent.com/webhook/23dd4bb2-c037-4603-8483-d52e2faecf48

Environment Variables

No specific environment variables are configured in this workflow. All endpoints and database connections use n8n's credential system.

Data Flow

Input

Twilio WhatsApp webhook payload containing: - WaId: Sender's WhatsApp ID - Body: Message content - Various Twilio metadata fields

Processing

• Extracts phone number (formatted with +)
• Queries agent_takeover table for active records
• Routes based on takeover status

Output

• Agent Mode: Message logged to chatLog table, "OK" response to Twilio
• Bot Mode: Complete payload forwarded to bot workflow, "OK" response to Twilio

Error Handling

The workflow includes basic error handling: - Database queries are configured to continue on error with alwaysOutputData: true - HTTP request has a 30-second timeout - All error-prone nodes use continueRegularOutput to prevent workflow failure

Known Limitations

• No business context provided yet — limitations will be documented when context is added
• Hard-coded webhook URL for bot forwarding
• No validation of incoming message format
• No retry mechanism for failed database operations

Related Workflows

• WhatsAppTrigger Workflow: Receives forwarded messages for bot processing (webhook ID: 23dd4bb2-c037-4603-8483-d52e2faecf48)

Setup Instructions

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

2. Configure Database Connection:

   • Set up PostgreSQL credentials in n8n
   • Ensure tables exist:

     -- agent_takeover table
     CREATE TABLE agent_takeover (
       id SERIAL PRIMARY KEY,
       phone_number VARCHAR(20),
       expires_at TIMESTAMP
     );
     
     -- chatLog table  
     CREATE TABLE "chatLog" (
       "userPhone" VARCHAR(20),
       "userQuery" TEXT,
       "agentResponse" TEXT,
       "channel" VARCHAR(50),
       "responseBy" VARCHAR(50)
     );
     

3. Update Webhook URLs:

   • Note the webhook URL for the "WhatsApp Incoming" trigger
   • Configure Twilio to send WhatsApp messages to this endpoint
   • Update the "Forward to WhatsAppTrigger" node URL if needed

4. Test the Workflow:

   • Send a test WhatsApp message
   • Verify routing works correctly based on agent takeover status
   • Check database logging is working

5. Activate: Enable the workflow to start processing live messages