Skip to content

V4 - helpKeywordHandler

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

Purpose

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

Based on the workflow implementation, this appears to be part of a youth support system that provides immediate access to help resources when users send a "help" keyword. The workflow ensures youth can quickly receive the toll-free SIFA helpline number through their preferred communication method.

How It Works

  1. Receives Request: Another workflow triggers this one, passing youth phone number and preferred channel
  2. Prepares Response: Builds a standardized message containing the SIFA helpline number
  3. Routes by Channel: Determines whether to send via WhatsApp or SMS based on the youth's preference
  4. Sends Message: Delivers the helpline 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 phone number to send the help information to - channel: The preferred communication method ("whatsapp" or "sms")

Nodes Used

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

External Services & Credentials Required

Twilio (WhatsApp)

  • Credential Name: "Twilio account"
  • Purpose: Send WhatsApp messages
  • Required: Account SID, Auth Token, WhatsApp-enabled phone number

Africa's Talking (SMS)

  • Purpose: Send SMS messages via toll-free shortcode
  • Authentication: API key (configured in HTTP request headers)
  • Shortcode: 24436
  • Username: toll_free_sms_ke

PostgreSQL Database

  • Credential Name: "Postgres account"
  • Purpose: Log help keyword events for analytics
  • Required: Database connection details (host, port, database, username, password)

Environment Variables

No environment variables are explicitly used in this workflow. All configuration is handled through: - Node parameters (phone numbers, API endpoints) - Credential storage (API keys, database connections) - Input data from triggering workflows

Data Flow

Input

1
2
3
4
{
  "youthPhone": "+254712345678",
  "channel": "whatsapp"
}

Processing

  • Message body: "0800-SIFA-00 - free from any phone - 8am-8pm"
  • Channel routing: WhatsApp or SMS
  • Database logging with event type "help_keyword"

Output

  • Message delivered to youth via chosen channel
  • Event logged in surfacing_events table
  • No return data (fire-and-forget pattern)

Error Handling

This workflow does not implement explicit error handling. Potential failure points: - Twilio API failures (invalid phone numbers, service outages) - Africa's Talking API failures (network issues, account problems) - Database connection issues during logging

Consider adding error handling nodes to: - Retry failed message sends - Log errors for monitoring - Send fallback notifications to administrators

Known Limitations

  • No validation of input phone number format
  • No retry mechanism for failed API calls
  • Hard-coded message content (not configurable)
  • No delivery confirmation tracking
  • Database logging failures don't prevent message sending

This workflow is designed to be called by other workflows that handle: - Keyword detection in incoming messages - Youth registration and preference management - Message routing and processing

Setup Instructions

  1. Import Workflow 

    1
    # Import the JSON file into your n8n instance

  2. Configure Credentials

    • Set up Twilio account credentials with WhatsApp sandbox or production access
    • Configure Africa's Talking API credentials
    • Set up PostgreSQL database connection

  3. Database Setup 

    1
2
3
4
5
6
7
8
    -- Ensure the surfacing_events table exists
CREATE TABLE IF NOT EXISTS surfacing_events (
  id SERIAL PRIMARY KEY,
  youth_phone VARCHAR(20),
  surfacing_event_type VARCHAR(50),
  channel VARCHAR(20),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

  4. Test Configuration

    • Verify Twilio WhatsApp number is properly configured
    • Test Africa's Talking shortcode 24436 functionality
    • Confirm database write permissions

  5. Integration

    • Update calling workflows to pass correct parameters
    • Ensure phone numbers are in international format (+254...)
    • Test both WhatsApp and SMS delivery paths