V4 - NudgeSender - Warenga

A utility workflow that handles multi-channel message delivery for the SIFA coaching platform, routing nudges through web app notifications and SMS alerts while maintaining comprehensive delivery logs and user profile updates.

Purpose

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

This workflow serves as the central message dispatch system for SIFA's youth entrepreneur coaching program. It receives nudge requests from daily cron jobs and credit follow-up systems, then intelligently routes messages through the appropriate channel (web app or SMS) while maintaining detailed delivery logs and updating user engagement records.

How It Works

1. Input Processing: Receives a nudge request with phone number, message content, nudge type/step, and target channel
2. Dual Channel Dispatch: Simultaneously sends the message to the web app and prepares an SMS alert
3. Web Delivery: Posts the full nudge content to the SIFA web app via webhook
4. SMS Alert Generation: Creates a short SMS notification with a link to the web app (different from the full nudge content)
5. SMS Sending: Delivers the SMS alert via Africa's Talking using the "Educate" sender ID
6. Delivery Verification: Checks if web and SMS delivery were successful
7. Comprehensive Logging: Records delivery details in multiple database tables
8. Profile Updates: Updates the youth entrepreneur's profile with latest nudge information

The workflow ensures messages reach users through multiple channels while maintaining detailed audit trails for engagement tracking.

Workflow Diagram

graph TD
    A[Input] --> B[Dispatch Web]
    A --> C[Build SMS Alert]
    B --> D[Web Delivered?]
    C --> E[Send SMS AT Educate]
    E --> F[SMS Sent?]
    D --> |Yes| G[Insert Chat History]
    F --> |Yes| H[Build SMS Log]
    H --> I[Write SMS Nudge]
    G --> J[Insert Nudge Log]
    J --> K[Update Youth Profile]

Trigger

Execute Workflow Trigger - This is a utility workflow called by other workflows (daily cron jobs, credit follow-up systems) rather than running independently.

Required Input Parameters: - phoneNumber - Target user's phone number - message - Full nudge content for web delivery - nudge_type - Type of nudge (daily_morning, daily_evening, credit_followup, etc.) - nudge_step - Current step in the nudge sequence - youth_id - User identifier - firstName - User's first name for personalization - channel - Target channel (webapp/sms)

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	Input	Receives nudge parameters from calling workflows
HTTP Request	Dispatch Web	Sends full nudge content to SIFA web app
Code	Build SMS Alert	Generates personalized SMS alert with web app link
HTTP Request	Send SMS (AT Educate)	Sends SMS via Africa's Talking API
If	Web Delivered?	Checks if web delivery was successful
If	SMS Sent?	Verifies SMS delivery status
Code	Build SMS Log	Prepares SMS delivery data for database logging
Postgres	Insert Chat History	Records message in chat history table
Postgres	Insert Nudge Log	Logs nudge delivery details
Postgres	Write SMS Nudge	Records SMS-specific delivery metadata
Postgres	Update Youth Profile	Updates user's last nudge information

External Services & Credentials Required

Africa's Talking SMS API - Credential: Africa's Talking Header OAuth - Used for: SMS delivery via toll-free number with "Educate" sender ID - Endpoint: https://api.africastalking.com/version1/messaging

SIFA Web App - Credential: X-Internal-Token - Used for: Web app message delivery - Endpoint: https://sifa.alpha-test.kriftx.app/webhooks/n8n/dispatch

PostgreSQL Database - Credential: sifaV4Dev - Used for: All data logging and profile updates - Tables: v4_nudgelog, n8n_chat_histories, v4_youthEntrepreneurs, v4_sms_nudges

Environment Variables

No explicit environment variables are used. Configuration is handled through: - Hardcoded web app base URL: https://sifa.alpha-test.kriftx.app - Africa's Talking username: toll_free_sms_ke - SMS sender ID: Educate

Data Flow

Input:

{
  "phoneNumber": "+254712345678",
  "message": "Full nudge content for web app",
  "nudge_type": "daily_morning",
  "nudge_step": "step_1",
  "youth_id": "user123",
  "firstName": "John",
  "channel": "webapp"
}

Processing: - Web app receives full message content - SMS contains personalized alert with web app link - Database logs capture delivery status and metadata

Output: - Updated user profile with latest nudge timestamp - Comprehensive delivery logs across multiple tables - Chat history entry for web app integration

Error Handling

The workflow includes error handling for external service calls: - Web dispatch failures: Continue execution (onError: continueRegularOutput) - SMS sending failures: Continue execution (onError: continueRegularOutput) - Database logging errors: SMS logging continues even if it fails

Failed deliveries are logged but don't stop the workflow, ensuring maximum delivery attempts across all channels.

Known Limitations

• SMS alerts are generic notifications rather than the full nudge content
• Web app URL is hardcoded and environment-specific
• No retry mechanism for failed deliveries
• SMS delivery verification relies on Africa's Talking response format
• Template SID functionality mentioned in comments but not implemented in current flow

Related Workflows

This workflow is called by: - Daily nudge cron jobs (morning, midday, evening) - Credit follow-up systems - Microaction follow-up workflows

Setup Instructions

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

2. Configure Database Credential:

   • Create PostgreSQL credential named sifaV4Dev
   • Ensure access to tables: v4_nudgelog, n8n_chat_histories, v4_youthEntrepreneurs, v4_sms_nudges

3. Configure Africa's Talking:

   • Create HTTP Header Auth credential named Africa's Talking Header OAuth
   • Add your Africa's Talking API key as the header value

4. Configure Web App Access:

   • Create HTTP Header Auth credential named X-Internal-Token
   • Add your internal API token for SIFA web app access

5. Update Environment URLs:

   • Modify the web app base URL in the "Build SMS Alert" node if deploying to different environment
   • Update the dispatch webhook URL in "Dispatch Web" node as needed

6. Test Integration:

   • Execute with test data to verify all channels work correctly
   • Check database tables for proper logging
   • Verify SMS delivery through Africa's Talking dashboard

7. Set Caller Policy: Ensure calling workflows have proper permissions (currently set to "workflowsFromSameOwner")