Skip to content

V4 - helpKeywordHandler

This workflow responds to help keyword requests by sending contact information to youth via WhatsApp or SMS and logging the interaction for tracking purposes.

Purpose

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

How It Works

  1. Receives Request: The workflow is triggered via webhook with youth phone number and channel information
  2. Builds Response: Creates a standardized help message containing the SIFA contact number (0800-SIFA-00)
  3. Routes by Channel: Determines whether to send via WhatsApp or SMS based on the channel parameter
  4. Sends Message: Delivers the help information through the appropriate messaging service
  5. Logs Event: Records the help keyword interaction in the database for tracking and analytics

Workflow Diagram

graph TD
    A[Webhook] --> 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]

    style E fill:#f9f,stroke:#333,stroke-dasharray: 5 5
    style G fill:#f9f,stroke:#333,stroke-dasharray: 5 5

Trigger

Webhook: Accepts POST requests at endpoint 837385f5-0ef2-4eee-9c32-4e6ffe78a2bf

Expected payload: - youthPhone: The recipient's phone number - channel: Either "whatsapp" or "sms"

Nodes Used

Node Type Node Name Purpose
Webhook Webhook Receives incoming help keyword requests
Set Build Message Prepares the help message and extracts request data
Switch Channel? Routes execution based on messaging channel
Twilio Send WhatsApp Sends help message via WhatsApp
HTTP Request Send SMS Sends help message via SMS (currently disabled)
Postgres Log Event (WA) Records WhatsApp help interactions
Postgres Log Event (SMS) Records SMS help interactions (currently disabled)

External Services & Credentials Required

Twilio (WhatsApp)

  • Credential: "Twilio account 3"
  • Purpose: Send WhatsApp messages
  • From Number: +12402623539

Africa's Talking (SMS)

  • Purpose: Send SMS messages (currently disabled)
  • Username: toll_free_sms_ke
  • From Code: 24436

PostgreSQL Database

  • Credential: "Postgres account 3"
  • Purpose: Log help keyword events
  • Table: surfacing_events

Environment Variables

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

Data Flow

Input

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

Output

  • Message Sent: "0800-SIFA-00 - free from any phone - 8am-8pm"
  • Database Record: Help keyword event logged with phone number, event type, and channel

Database Schema

1
2
3
4
5
6
7
8
9
INSERT INTO surfacing_events (
  youth_phone,
  surfacing_event_type,
  channel
) VALUES (
  phone_number,
  'help_keyword',
  'whatsapp'
);

Error Handling

This workflow does not implement explicit error handling. Failed message sends or database operations will cause the workflow to stop with an error. Consider adding error handling nodes for production use.

Known Limitations

  • SMS functionality is currently disabled (nodes are present but disabled)
  • No retry mechanism for failed message delivery
  • No validation of phone number format
  • No error handling for external service failures
  • Hard-coded message content (not configurable)

No related workflows identified from the current configuration.

Setup Instructions

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

  2. Configure Credentials:

    • Set up Twilio API credentials for WhatsApp messaging
    • Configure PostgreSQL database connection
    • (Optional) Set up Africa's Talking credentials for SMS

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

    • youth_phone (text)
    • surfacing_event_type (text)
    • channel (text)

  4. Test the Webhook: Send a POST request to the webhook endpoint: 

    1
2
3
    curl -X POST https://your-n8n-instance.com/webhook/837385f5-0ef2-4eee-9c32-4e6ffe78a2bf \
  -H "Content-Type: application/json" \
  -d '{"youthPhone": "+254700000000", "channel": "whatsapp"}'

  5. Enable SMS (Optional): If SMS functionality is needed, enable the disabled SMS nodes and configure Africa's Talking credentials

  6. Activate Workflow: Set the workflow to active status to begin processing requests