Tender:
Development of a Reusable, Open-Source USSD Framework via Custom n8n Nodes
Date of Issue: October 25, 2025
1. Introduction & Executive Summary
agriBORA is developing a robust, omni-channel customer engagement platform. A core component of this platform is the ability to offer services via USSD menus. To ensure scalability, maintainability, and rapid development of future USSD applications, we are seeking a skilled developer to build a suite of custom, reusable nodes within our existing n8n workflow automation environment.
This project will abstract the complexities of USSD session management and provider-specific API formats into a set of intuitive, high-level nodes. The end goal is to empower our team to build complex USSD flows visually within n8n, without needing to handle the underlying stateful logic or API integrations for each new service.
Crucially, this project will be developed as a high-quality, open-source tool for the benefit of the wider n8n community.
2. Project Background
Our current architecture utilizes:
-
n8n as the central engine for workflow automation and process orchestration.
-
Redis as a high-performance cache for managing temporary data, such as user sessions.
We require a solution that integrates seamlessly into this stack. The initial USSD API providers to be supported is Africa’s Talking, but the solution must be designed with extensibility in mind to accommodate other providers in the future.
The Africa’s Talking API documentation and free sandbox environment is available under https://account.africastalking.com/auth/login and https://developers.africastalking.com/
3. Scope of Work & Core Deliverables
The primary deliverable is a functional, well-documented suite of custom n8n nodes that, when used together, provide a complete framework for building USSD applications.
The developer will be responsible for designing, building, testing, and documenting the following four (4) custom n8n nodes:
3.1. Deliverable 1: USSD Trigger Node
This node will serve as the standardized entry point for all USSD interactions.
-
Functionality:
-
Acts as a trigger, initiating the workflow when a USSD provider sends a webhook.
-
Provider Abstraction: Must include a dropdown to select the USSD Provider (initial options: “Africa’s Talking”, “Beem Africa”).
-
Automatically parses the provider-specific incoming webhook payload and outputs a single, standardized JSON object (e.g., { “sessionId”: “…”, “phoneNumber”: “…”, “userInput”: “…”, “provider”: “africastalking” }).
-
Session Initiation: On the first request of a session (i.e., when userInput is empty), it must automatically create a new session entry in the connected Redis instance.
3.2. Deliverable 2: USSD Menu Node
This node will be the primary tool for building navigation menus.
-
Functionality:
-
Takes a menu text as input (e.g., “Welcome to agriBORA. \n1. Check Balance \n2. Market Prices”).
-
Provides a simple, dynamic UI within the n8n editor to map user inputs (e.g., “1”, “2”, “*”) to the node’s distinct output anchors.
-
Reads the standardized userInput and routes the n8n execution to the corresponding output.
-
Sends the menu text as a “continue” response to the user via the appropriate provider API.
-
Updates the user’s state in Redis to reflect their current position in the menu.
3.3. Deliverable 3: USSD Input Node
This node will handle the collection of free-text or numeric input from the user.
-
Functionality:
-
Takes a prompt text as input (e.g., “Please enter your National ID number:”).
-
Sends the prompt to the user as a “continue” response.
-
Saves the user’s subsequent text input to a specified variable within the n8n workflow data (e.g., a variable named id_number).
-
Input Validation: Must include built-in, configurable validation rules (e.g., “Is Numeric”, “Min/Max Length”, “Regex Pattern”). If validation fails, the node should automatically re-display the prompt with a customizable error message.
3.4. Deliverable 4: USSD Response Node
This node will be the standard mechanism for ending a USSD session.
-
Functionality:
-
Takes a final message text as input (e.g., “Thank you for using our service.”).
-
Provider Abstraction: Automatically formats the response with the correct “end session” prefix (e.g., END for Africa’s Talking, FB for Beem Africa) based on the provider specified in the trigger.
-
Sends the final message to the user.
-
Session Cleanup: Must automatically delete the user’s session data from the Redis cache.
4. Technical Requirements
-
All nodes must be developed in TypeScript using the standard n8n custom node development framework.
-
The solution must integrate with an external Redis instance for all session management. The Redis connection details (host, port, password) must be configurable via a new n8n Credential type.
5. Non-Functional Requirements
-
Reusability & Maintainability: The code must be clean and structured in a way that allows for easy extension and maintenance.
-
Performance: All Redis interactions must be highly efficient to ensure low latency for the end-user.
-
Error Handling: The nodes must gracefully handle potential errors (e.g., a failed Redis connection, invalid API response) and expose these errors clearly within the n8n workflow.
-
Multi-language Support: The nodes should be designed to support multiple languages for menu texts, prompts, and response messages, ideally through dynamic content retrieval based on session data or configuration.
6. Code Quality & Open Source Standards
-
Compliance with n8n Standards: The code for all nodes must adhere to the official n8n contribution guidelines for community nodes. The ultimate goal is for this node suite to be of sufficient quality to be accepted into the official n8n-nodes-community repository or even as a core integration. This includes following all prescribed coding styles, conventions, and architectural patterns.
-
Open Source Documentation: The project will be open-sourced on GitHub. The code must be documented to the highest standards, including:
-
A comprehensive README.md file explaining the project’s purpose, installation, configuration, and usage.
-
Clear, well-commented code that explains the “why” behind complex logic, not just the “what.”
-
An appropriate open-source license (e.g., MIT).
-
Testing: The developer is expected to provide unit tests for key functionalities to ensure robustness and facilitate future development.
7. Developer Qualifications
-
Proven experience in developing custom n8n nodes, ideally with one or more nodes accepted as a community node.
-
Strong proficiency in TypeScript and Node.js, with a deep understanding of modern best practices.
-
Experience contributing to open-source projects.
-
Experience working with Redis.
-
Demonstrable experience integrating with third-party REST APIs.
-
Excellent communication skills and ability to work independently.
8. Proposal Requirements
Interested developers should submit a proposal containing the following:
-
A brief cover letter introducing yourself and your relevant experience, specifically highlighting any contributions to open-source projects or n8n.
-
Links to your portfolio, GitHub profile, and/or examples of previous n8n custom node projects.
-
A proposed technical approach to the project.
-
A detailed project timeline with key milestones.
-
A fixed-bid cost estimate for the entire scope of work.
-
A brief statement acknowledging the open-source and n8n-compliance requirements.
Submit your proposal to [email protected]
Looking forward to your applications and replies!
