Skip to content

V4 - helpKeywordHandler

This workflow responds to "help" keyword requests by sending users the SIFA helpline number (0800-SIFA-00) via their preferred communication channel (WhatsApp or SMS) and logs the interaction for tracking purposes.

Purpose

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

Based on the workflow structure, this appears to handle help requests from users by providing them with a toll-free helpline number and tracking these interactions in a database.

How It Works

  1. Receives Input: Another workflow triggers this one, passing youth phone number and preferred channel
  2. Prepares Message: Creates a standardized help message containing the SIFA helpline number
  3. Routes by Channel: Determines whether to send via WhatsApp or SMS based on user preference
  4. Sends Message: Delivers the help information through the appropriate channel
  5. Logs Interaction: Records the help request event in the database for tracking and analytics

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Build Message]
    B --> C{Channel?}
    C -->|WhatsApp| D[Send WhatsApp]
    C -->|SMS| E[Send SMS]
    D --> F[Log Event WA]
    E --> G[Log Event SMS]

Trigger

Execute Workflow Trigger: This workflow is called by other workflows in the system. It expects to receive: - youthPhone: The recipient's phone number - channel: Communication preference ("whatsapp" or "sms")

Nodes Used

Node Type Node Name Purpose
Execute Workflow Trigger When Executed by Another Workflow Receives calls from other workflows
Set Build Message Prepares the help message and extracts input parameters
Switch Channel? Routes execution based on communication channel preference
Twilio Send WhatsApp Sends help message via WhatsApp
HTTP Request Send SMS Sends help message via SMS using Africa's Talking API
Postgres Log Event (WA) Records WhatsApp help requests in database
Postgres Log Event (SMS) Records SMS help requests in database

External Services & Credentials Required

Twilio (WhatsApp)

  • Credential ID: f1rV52vb9Dkb4f1K
  • Purpose: Sending WhatsApp messages
  • Required: Account SID, Auth Token, WhatsApp-enabled phone number

Africa's Talking (SMS)

  • Purpose: Sending SMS messages via toll-free shortcode
  • Required: API key, username (toll_free_sms_ke)
  • Shortcode: 24436

PostgreSQL Database

  • Credential IDs: 80LHOtylhMnmLKKV, HW3SZAbtOnuQRQ9x
  • Purpose: Logging help request events
  • Required: Database connection details

Environment Variables

No environment variables are explicitly used in this workflow. All configuration is handled through: - Hardcoded phone numbers and shortcodes - Credential-stored API keys and connection strings

Data Flow

Input

1
2
3
4
{
  "youthPhone": "+254XXXXXXXXX",
  "channel": "whatsapp" | "sms"
}

Processing

  • Message body: "0800-SIFA-00 - free from any phone - 8am-8pm"
  • WhatsApp sender: +254203892316
  • SMS sender: 24436 (shortcode)

Output

  • Message delivered to user via specified channel
  • Database record created in surfacing_events table with:
    • youth_phone: Recipient's phone number
    • surfacing_event_type: "help_keyword"
    • channel: "whatsapp" or "sms"

Error Handling

This workflow does not implement explicit error handling. Failed message deliveries or database insertions will cause the workflow to stop with an error. Consider adding: - Try-catch blocks around external API calls - Retry logic for failed deliveries - Fallback notification mechanisms

Known Limitations

  • No error handling for failed message deliveries
  • Hardcoded message content (not configurable)
  • No validation of phone number format
  • No rate limiting or duplicate request prevention
  • Database logging uses different credential IDs for WhatsApp vs SMS events

This workflow is designed to be called by other workflows that detect help keyword usage. No specific related workflows are identified in the current documentation.

Setup Instructions

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

  2. Configure Credentials:

    • Set up Twilio credentials for WhatsApp messaging
    • Configure Africa's Talking API credentials for SMS
    • Set up PostgreSQL database connections

  3. Database Setup: Ensure the surfacing_events table exists with columns: 

    1
2
3
4
5
6
    CREATE TABLE surfacing_events (
  youth_phone VARCHAR,
  surfacing_event_type VARCHAR,
  channel VARCHAR,
  created_at TIMESTAMP DEFAULT NOW()
);

  4. Test Configuration:

    • Verify WhatsApp number (+254203892316) is properly configured in Twilio
    • Confirm SMS shortcode (24436) is active with Africa's Talking
    • Test database connectivity and write permissions

  5. Integration: Configure calling workflows to pass the required youthPhone and channel parameters

  6. Monitoring: Set up monitoring for failed executions and message delivery failures