Sifa Apology Outreach (SMS)

This workflow sends a universal apology message via SMS to onboarded Sifa users who communicate through the SMS channel. It acknowledges system issues and redirects users to WhatsApp for continued support, helping maintain user engagement after service disruptions.

Purpose

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

Based on the workflow implementation, this appears to be a crisis communication tool that allows the Sifa team to quickly reach out to SMS users when there have been system problems. The workflow sends an apology message in Swahili that translates to "We had a problem but now it's okay. Send your data and ask SIFA any question about your business."

How It Works

1. Manual Trigger: A team member (likely Edith, based on the notes) manually executes the workflow
2. Configuration Setup: The workflow loads Africa's Talking SMS credentials and sets the outreach tag for tracking
3. User Query: Fetches SMS users who are onboarded but haven't received this specific apology message yet
4. Batch Processing: Processes users one at a time to respect rate limits
5. Message Rendering: Prepares the apology SMS with user details
6. SMS Delivery: Sends the message via Africa's Talking SMS service
7. Audit Logging: Records the outreach in the chat log for tracking and idempotency
8. Rate Limiting: Waits 1.5 seconds between sends to stay within API limits

The workflow is designed to be idempotent - running it multiple times won't send duplicate messages to the same users.

Workflow Diagram

graph TD
    A[Manual Trigger] --> B[Config]
    B --> C[Fetch Queue]
    C --> D[Loop 1 row]
    D --> E[Render SMS]
    E --> F[SMS Live Send]
    F --> G[Log chatLog]
    G --> H[Rate Limit Wait]
    H --> D
    D --> I[Complete]

Trigger

Manual Trigger: The workflow must be manually executed by clicking "Execute Workflow" in the n8n interface. This is intentional for crisis communication scenarios where human oversight is required.

Nodes Used

Node Type	Node Name	Purpose
Manual Trigger	Manual Trigger	Allows manual execution of the workflow
Set	Config	Stores Africa's Talking credentials and outreach tag
Postgres	Fetch Queue	Queries database for SMS users who need the apology message
Split in Batches	Loop (1 row)	Processes users one at a time
Set	Render SMS	Prepares the SMS message content
HTTP Request	SMS Live Send	Sends SMS via Africa's Talking API
Postgres	Log chatLog	Records the outreach for audit and idempotency
Wait	Rate Limit Wait	Prevents API rate limit violations

External Services & Credentials Required

Africa's Talking SMS

• Service: SMS delivery platform
• Credentials needed:
  • API Key
  • Username (toll_free_sms_ke)
  • Sender Code (24436)
• Endpoint: https://api.africastalking.com/version1/messaging

PostgreSQL Database

• Service: User data and chat log storage
• Credentials needed: Database connection credentials
• Tables accessed:
  • youthEntrepreneursReal (user data)
  • youthProgressReport (onboarding status)
  • chatLog (message audit trail)

Environment Variables

The workflow uses hardcoded configuration in the Config node: - outreach_tag: "system/apology-2026-04-25" - at_username: "toll_free_sms_ke" - at_sender_code: "24436" - at_api_key: API key for Africa's Talking (should be moved to environment variable)

Data Flow

Input

• Source: PostgreSQL database query
• Data: SMS users who are onboarded but haven't received this apology message
• Fields: phone number, first name, channel

Processing

• Filters for SMS channel users only
• Excludes users who already received this specific apology (idempotent)
• Renders Swahili apology message with WhatsApp redirect

Output

• SMS Message: Apology text sent to user's phone
• Audit Record: Entry in chatLog table with outreach tag
• Rate Limiting: 1.5 second delay between sends

Error Handling

The workflow does not include explicit error handling nodes. Failures in SMS sending or database operations will stop the workflow execution. Consider adding error handling for: - SMS delivery failures - Database connection issues - API rate limit exceeded responses

Known Limitations

• Hardcoded Credentials: API key is embedded in the workflow rather than using environment variables
• No Error Recovery: Failed SMS sends are not retried or logged separately
• Single Channel: Only handles SMS users, not WhatsApp users
• Manual Execution Only: Requires human intervention to run
• Rate Limiting: Processing ~235 users takes approximately 6 minutes due to 1.5s delays

Related Workflows

Based on the notes mentioning "matches nudge workflow," there appears to be a related nudge workflow that uses similar Africa's Talking configuration.

Setup Instructions

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

2. Configure Database Connection:

   • Set up PostgreSQL credentials named "Postgres account"
   • Ensure access to tables: youthEntrepreneursReal, youthProgressReport, chatLog

3. Update Configuration:

   • Replace the hardcoded API key in the Config node with your Africa's Talking credentials
   • Update the outreach tag if running a new apology campaign
   • Verify the sender code and username match your Africa's Talking setup

4. Test Setup:

   • Run the Fetch Queue node independently to verify database connectivity
   • Test with a small subset of users first

5. Execute:

   • Click "Execute Workflow" to start the apology outreach
   • Monitor progress through the execution log
   • Verify messages are being logged in the chatLog table

6. Post-Execution:

   • Check SMS delivery reports in Africa's Talking dashboard
   • Verify audit trail in chatLog table
   • Monitor for any user responses or issues