Skip to content

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 based on active agent takeover sessions.

Purpose

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

How It Works

  1. Receive WhatsApp Message: The workflow receives incoming WhatsApp messages via a webhook from Twilio
  2. Extract Message Data: Parses the 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 complete message payload to another workflow for automated processing
  5. Respond: 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 /sifa-whatsapp-router endpoint. This webhook is typically configured in Twilio to receive WhatsApp message notifications.

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 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 WhatsAppTrigger Forwards message to bot workflow when no agent
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

  • Postgres Database: Connection to database containing agent_takeover and chatLog tables
    • Credential ID: EJPqF6MDH1ZwAzyv
    • Name: "Postgres account"

External Services

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

Environment Variables

No environment variables are explicitly used in this workflow. All configuration is handled through node parameters and credentials.

Data Flow

Input (from Twilio)

  • Complete WhatsApp message payload including:
    • WaId: WhatsApp ID (phone number)
    • Body: Message content
    • From, To: Sender and recipient numbers
    • Various Twilio metadata fields

Processing

  • Extracts phone number with + prefix
  • Queries agent_takeover table for active sessions
  • Routes based on agent availability

Output

  • Agent Mode: Message logged to chatLog table, "OK" response to Twilio
  • Bot Mode: Full 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 (continueRegularOutput) - HTTP request to bot workflow continues on error - All nodes have error handling to prevent workflow failures from blocking Twilio responses

Known Limitations

No specific limitations documented in the provided context.

  • Bot Workflow: Receives forwarded messages at webhook endpoint 23dd4bb2-c037-4603-8483-d52e2faecf48 for automated processing

Setup Instructions

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

  2. Configure Database Connection:

    • Set up PostgreSQL credentials named "Postgres account"
    • Ensure database contains required tables:
      • agent_takeover (columns: id, phone_number, expires_at)
      • chatLog (columns: userPhone, userQuery, agentResponse, channel, responseBy)

  3. Configure Webhook:

    • Note the webhook URL: https://your-n8n-instance.com/webhook/sifa-whatsapp-router
    • Configure this URL in your Twilio WhatsApp sandbox/phone number settings

  4. Update Bot Workflow URL:

    • Modify the "Forward to WhatsAppTrigger" node URL to point to your bot workflow webhook

  5. Test the Setup:

    • Send a test WhatsApp message
    • Verify the workflow executes and routes correctly based on agent takeover status

  6. Activate Workflow: Enable the workflow to start processing live WhatsApp messages