Skip to content

[DEV] Sifa WhatsApp Router

This workflow serves as an intelligent routing system for incoming WhatsApp messages, determining whether messages should be handled by human agents or automated bot responses based on conversation state and specific keywords.

Purpose

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

How It Works

  1. Message Reception: Receives incoming WhatsApp messages via webhook from Twilio
  2. Data Extraction: Extracts the sender's phone number and message content from the webhook payload
  3. Keyword Detection: Checks if the message contains help keywords ("HELP", "HELP ME", or "MSAADA")
  4. Help Routing: If help keywords are detected, routes to a specialized help handler workflow
  5. Agent Takeover Check: For non-help messages, queries the database to see if an agent has taken over the conversation
  6. Message Routing:
    • If agent takeover exists: Logs the message and responds with OK (agent will handle separately)
    • If no agent takeover: Forwards the message to the main WhatsApp bot trigger for automated processing
  7. Response: Returns appropriate HTTP response to acknowledge message receipt

Workflow Diagram

graph TD
    A[WhatsApp 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 WhatsAppTrigger]
    I --> K[Respond OK - Agent Mode]
    J --> L[Respond OK - Bot Mode]

Trigger

  • Type: Webhook (POST)
  • Path: /sifa-whatsapp-router
  • Source: Twilio WhatsApp webhook
  • Status: Currently disabled (development mode)

Nodes Used

Node Type Node Name Purpose
Webhook WhatsApp Incoming Receives incoming WhatsApp messages from Twilio
Set Extract Phone & Message Extracts phone number and message text from webhook payload
If HELP Keyword? Checks for help-related keywords in the message
Set Set Channel Prepares data for help handler workflow
Execute Workflow Call helpKeywordHandler Triggers specialized help handling workflow
Postgres Check Agent Takeover Queries database for active agent takeover sessions
If Agent Owns Conversation? Determines routing based on agent takeover status
Postgres Log to chatLog (Agent Mode) Records message when agent has taken over
HTTP Request Forward to WhatsAppTrigger Forwards message to main bot workflow
Respond to Webhook Multiple response nodes Acknowledges message receipt with HTTP 200 OK

External Services & Credentials Required

Required Credentials

  • Postgres Database: Connection to chat logging and agent takeover database
    • Credential ID: 80LHOtylhMnmLKKV
    • Used for: Agent takeover checks and message logging

External Services

  • Twilio WhatsApp: Source of incoming webhook messages
  • n8n Webhook Endpoint: https://n8n.dev.educate-agent.com/webhook/23dd4bb2-c037-4603-8483-d52e2faecf48 (WhatsApp bot trigger)

Environment Variables

No specific environment variables are configured in this workflow. All endpoints and credentials are hardcoded or use n8n's credential system.

Data Flow

Input

  • Webhook Payload: Twilio WhatsApp webhook containing:
    • WaId: Sender's WhatsApp ID (phone number)
    • Body: Message text content
    • Various Twilio metadata fields

Processing

  • Phone Number: Formatted with + prefix
  • Message Text: Extracted and checked for keywords
  • Database Queries: Agent takeover status and message logging

Output

  • HTTP Response: Always returns "OK" with status 200
  • Side Effects:
    • Database logging (in agent mode)
    • Workflow triggering (help or bot modes)

Error Handling

The workflow includes several error handling mechanisms:

  • Continue on Error: Most nodes are configured to continue execution even if they fail
  • Always Output Data: Database nodes are set to always produce output, even on query failures
  • Timeout Protection: HTTP requests have a 30-second timeout limit

Known Limitations

  • Workflow is currently disabled (development status)
  • Hardcoded webhook URLs may need updating for different environments
  • No validation of incoming webhook authenticity beyond Twilio signature
  • Help keywords are case-sensitive after uppercase conversion
  • V4 - helpKeywordHandler (ethAUW0G7i8qZ9CI): Handles help-related messages
  • WhatsApp Bot Trigger: Main bot workflow for automated responses

Setup Instructions

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

  2. Configure Database Credentials:

    • Set up Postgres connection with ID 80LHOtylhMnmLKKV
    • Ensure access to agent_takeover and chatLog tables

  3. Update Webhook URLs:

    • Replace hardcoded webhook URL in "Forward to WhatsAppTrigger" node
    • Ensure target workflow exists and is active

  4. Configure Twilio:

    • Set up Twilio WhatsApp webhook to point to this workflow's webhook URL
    • Ensure proper webhook signature validation if needed

  5. Enable Workflow:

    • Change status from disabled to active
    • Test with sample WhatsApp messages

  6. Verify Dependencies:

    • Ensure helpKeywordHandler workflow exists and is accessible
    • Test database connections and table schemas