The Ushahidi platform allows for data collection via SMS, Email, Twitter, Web and smartphone apps on Android and iOS. There’s increased demand for a low cost alternative to SMS as a data source on the platform. Currently, data from SMS comes in unstructured, and requires manual intervention to ensure it conforms to the structure of surveys. I.e it takes a massive amount of human effort to process data from SMS into meaningful information. Integrating USSD into Ushahidi would increase the ability of deployers to respond to issues in a timely and efficient manner without increasing the number of volunteers they require to clean and structure the data they receive, allowing them to focus on the needs of those they are serving at this critical time.

BotMan Studio is a Laravel and Botman bundled version that makes your chatbot development experience better. By providing testing tools, an out of the box web driver implementation and additional tools like an enhanced CLI with driver installation, class generation and configuration support, it speeds up the development significantly. BotMan is licensed under the MIT licenses.

Donate

Participating in this project requires adhering to the Ushahidi code of conduct

You can find the BotMan and BotMan Studio documentation at http://botman.io.

Also, you can find references about Laravel at the official documentation

Please check the official Laravel installation guide for server requirements before you start.

Clone the repository

git clone [email protected]:ushahidi/ussd-engine.git

Switch to the repo folder

cd ussd-engine

Install all the dependencies using composer

composer install

Copy the example env file and make the required configuration changes in the .env file

cp .env.example .env

Generate a new application key

php artisan key:generate

Start the local development server

php artisan serve

You can now access the server at http://localhost:8000

TL;DR command list

git clone [email protected]:ushahidi/ussd-engine.git
cd ussd-engine
composer install
cp .env.example .env
php artisan key:generate
php artisan serve

Make sure you set the correct values for your environment variables. Environment variables

Across the project we use a wide set of concepts related to Botman. We strongly suggest to read the "Core Concepts" guide at Botman documentation.

All the interaction with users and responses storage is structured using Botman Conversation classes.

Conversations are grouped in the app/Conversations folder.

Here's the list of available conversations:

• SurveyConversation: Contains all the logic for promting users which survey they want to complete, guide them through the form fields and store responses.

Botman is designed to work with different messaging channels. Each channel is powered by it's own driver, which is reponsible for handling incoming and outgoing messages from and to the messaging channel respectively.

BotMan ships with support for a number of different messaging channels. You can find the list of supported ones in the documentation.

We created a custom driver for Africa's Talking USSD service. You can find it in the app/Drivers folder. We use it to correctly extract the payload from each request recived from Africa's Talking gateway and to parse each message returned by Botman into text the Africa's Talking gateway can understand.

Supported drivers in this project:

• Africa's Talking Driver

Some important environment variables are:

• CACHE_DRIVER: This variable defines the cache driver to use in the project. Conversations and responses are stored using the Laravel's cache services. You can read more about it here.
• USHAHIDI_PLATFORM_API_URL: The URL where you are hosting your instance of the Ushahidi platform.
• USHAHIDI_PLATFORM_API_VERSION: The Ushahidi platform version you are using. Note: This project requires the Platform API to be version 5 or later.
• USHAHIDI_PLATFORM_API_TIMEOUT: Depending on your setup, you may want to set a custom timeout for requests to the Ushahidi Platform. It defaults to 2 seconds.
• USSD_MAX_CHARACTERS_PER_PAGE: USSD messages are limited to a fixed amount of characters depending on the telecommunications service provider. This allows to paginate the content delivered to your users. It defaults to 160 characters.

• API Specification
• Testing

This project is licensed under the AGPLv3. Find the full license here