Skip to content

SMSTrigger

This workflow handles incoming SMS messages through Africa's Talking, validates users against a database, and either redirects WhatsApp users to their preferred channel or processes SMS inquiries through an AI sales tracking agent.

Purpose

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

How It Works

  1. Incoming SMS Reception: The workflow receives SMS messages via Africa's Talking webhook
  2. Message Processing: Extracts the sender's phone number and message text from the incoming SMS
  3. User Validation: Checks if the sender's phone number exists in the youthEntrepreneursReal database table
  4. Unknown User Handling: If the user is not found, sends an error message via SMS
  5. Channel Preference Check: For known users, retrieves their preferred communication channel from the database
  6. WhatsApp Redirection: If the user's preferred channel is WhatsApp, sends them a message with a WhatsApp link instead of processing the SMS
  7. SMS Processing: For users who prefer SMS, forwards the inquiry to the "Mark - SalesTrackingAgent" workflow
  8. Response Delivery: If the sales agent generates a response, sends it back to the user via SMS

Mermaid Diagram

graph TD
    A[Africa's Talking Incoming messages] --> B[setSMSfields]
    B --> C[Execute a SQL query]
    C --> D[ifUserNotFound]
    D -->|User Not Found| E[Send SMS via Africa's Talking2]
    D -->|User Found| F[Execute a SQL query1]
    F --> G[If]
    G -->|Channel = WhatsApp| H[Send SMS via Africa's Talking1]
    G -->|Channel ≠ WhatsApp| I[setUserPhoneNumnberAndQuery]
    I --> J[Call 'Mark - SalesTrackingAgent']
    J --> K[If1]
    K -->|Has Response| L[Send SMS via Africa's Talking]
    K -->|No Response| M[No Operation, do nothing]

Trigger

Webhook Trigger: Listens for POST requests from Africa's Talking SMS service at the endpoint /webhook/0f856185-73f9-46e4-ac8f-fb3458a0bdc3

Nodes Used

Node Type Node Name Purpose
Webhook Africa's Talking Incoming messages Receives incoming SMS webhooks
Set setSMSfields Extracts phone number and message text
PostgreSQL Execute a SQL query Checks if user exists in database
If ifUserNotFound Routes based on user existence
PostgreSQL Execute a SQL query1 Retrieves user's preferred channel
If If Routes based on channel preference
Set setUserPhoneNumnberAndQuery Prepares data for sales agent
Execute Workflow Call 'Mark - SalesTrackingAgent' Processes inquiry through AI agent
If If1 Checks if agent generated response
HTTP Request Send SMS via Africa's Talking Sends agent response via SMS
HTTP Request Send SMS via Africa's Talking1 Sends WhatsApp redirect message
HTTP Request Send SMS via Africa's Talking2 Sends user not found error
No Operation No Operation, do nothing Handles empty responses
Sticky Note Sticky Note Documentation note

External Services & Credentials Required

Africa's Talking SMS API

  • API Key: Required for sending SMS messages
  • Username: toll_free_sms_ke
  • Short Code: 24436
  • Base URL: https://api.africastalking.com/version1/messaging

PostgreSQL Database

  • Credential Name: PostgresOnSupabase
  • Database: Contains youthEntrepreneursReal table
  • Required Fields: id, phoneNumber, channel
  • Mark - SalesTrackingAgent (ID: SQuf6XRV3xERKdsY): Processes user inquiries and generates responses

Environment Variables

No environment variables are explicitly used in this workflow. Configuration is handled through: - Hardcoded Africa's Talking credentials (API key visible in workflow) - Database credentials stored in n8n credential system - Static webhook path and short code values

Data Flow

Input (Africa's Talking Webhook)

1
2
3
4
5
6
7
8
9
{
  "body": {
    "from": "+254712287952",
    "text": "Yes",
    "to": "24436",
    "id": "message-id",
    "date": "2026-02-26T06:48:06.154Z"
  }
}

Processing

  • Extracts phone number (removes leading +)
  • Validates against database
  • Retrieves channel preference
  • Routes to appropriate handler

Output (SMS Response)

  • Error message for unknown users
  • WhatsApp redirect for WhatsApp users
  • AI-generated response for SMS users

Error Handling

  1. Unknown Users: Users not found in the database receive the message "Sorry, your number was not found in our database"
  2. WhatsApp Users: Users with WhatsApp preference receive a redirect message with link to WhatsApp
  3. Empty Responses: If the sales agent doesn't generate a response, no SMS is sent (handled by No Operation node)
  4. Retry Logic: The "Call 'Mark - SalesTrackingAgent'" node has retry enabled for handling temporary failures

Known Limitations

  • API key is hardcoded in the workflow (security risk)
  • No validation of message content or length limits
  • Single database table dependency
  • No handling for malformed webhook payloads
  • WhatsApp redirect uses hardcoded phone number (254203892316)
  • Mark - SalesTrackingAgent: Processes user inquiries and generates contextual responses for sales tracking

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance
  2. Configure Database Credential:
    • Create PostgreSQL credential named "PostgresOnSupabase"
    • Ensure access to youthEntrepreneursReal table with fields: id, phoneNumber, channel
  3. Set Up Africa's Talking:
    • Replace the hardcoded API key with your own
    • Configure webhook URL in Africa's Talking dashboard to point to your n8n instance
    • Verify short code and username match your Africa's Talking account
  4. Deploy Related Workflow:
    • Ensure "Mark - SalesTrackingAgent" workflow is deployed and accessible
  5. Test Integration:
    • Send test SMS to your Africa's Talking number
    • Verify database lookups and response delivery
  6. Security Hardening:
    • Move API key to environment variable or credential store
    • Add webhook authentication if required
    • Review and update hardcoded phone numbers