cic-ussd

A Fastify-based, USSD client implementation, that interfaces with the community inclusion currencies custodial system. It is built using Node.js (>=18). The app is designed to provide a simple and efficient way to create and manage USSD menus and interactions.

Pre-requisites

Node.js >= 18
NPM (Tested on v9.3.1)

Installation

Clone the repository:

git clone https://github.com/grassrootseconomics/cic-ussd

Change into the project directory:

cd cic-ussd

Install dependencies:

npm install

Create a .env file in the root directory of the project and add your environment variables:

cp .env.example .env

Running the app

To start the application in development mode, run:

npm run dev

To start the application in production mode, first build the application:

npm run build

Then start the application:

npm start

The application will be available at http://localhost:9000.

Usage

The app exposes an API for handling USSD requests. It currently supports the AfricasTalking USSD API. To use the API, send a POST request to the api/v1/ussd/africasTalking endpoint with the appropriate USSD payload. We recommend using the Dialoguss library for a more interactive and streamlined USSD experience.

Example request:

{
  "sessionId": "1234",
  "serviceCode": "*123#",
  "phoneNumber": "+254712345678",
  "text": "1*2*3"
}

The app will process the request and return a response in the format expected by USSD gateways. Example response:

CON Welcome to Sarafu Network!
1. English
2. Kiswahili

00.Exit
11. Next

Contributing

If you would like to contribute to this project, please read our contributing guide.

License

This project is licensed under the GNU Affero General Public License v3.0. See the LICENSE file for details.

grassrootseconomics / cic-ussd