This is a .NET library for developing dynamic USSD applications.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Smsgh.UssdFramework.Demo
Smsgh.UssdFramework.Logging
Smsgh.UssdFramework
packages
.gitattributes
.gitignore
CHANGELOG.md
README.md
Smsgh.UssdFramework.sln

README.md

Hubtel USSD Framework

This is a natural successor to our UssdFramework.

Motivation

The previous UssdFramework was a nice foundation, but it fell short in a few areas.

  • Explicit routing.
  • Integrated session store.
  • Step based flow.
  • Unnecessary abstractions that limit flexiblity.

Hubtel.UssdFramework addresses these and a lot more by focusing on simplicity.

Hubtel.UssdFramework allows you to easily build dynamic USSD applications on our USSD platform.

Key Features

  • Automated session management.
  • Fully asynchronous.
  • Pluggable session store. RedisStore included.
  • ASP.NET MVC / Web Api -ish controllers.
  • Dynamic routing.
  • DataBag helper in controllers for caching data across requests.
  • Create forms to collect user input.
  • Logging (optional).

Quick Start

Dependencies

Hubtel.UssdFramework requires a session store. Redis store is included.

On Windows, Redis can be installed using github.com/MSOpenTech/redis.

Don't want to use the bundled RedisStore? Implement IStore using your store backend. Better still, submit a pull request.

Installation

The easiest way to install Hubtel.UssdFramework is via NuGet.

PM> Install-Package Smsgh.UssdFramework

Setup

To process USSD requests, make a static call to Ussd.Process.

Here is a sample setup in an ASP.NET Web Api action.

using System.Threading.Tasks;
using System.Web.Http;
using Smsgh.UssdFramework.Stores;

namespace Smsgh.UssdFramework.Demo.Controllers
{
    public class DefaultController : ApiController
    {
        [HttpPost]
        public async Task<IHttpActionResult> Index(UssdRequest request)
        {
            return Ok(await Ussd.Process(new RedisStore(), request, "Main", "Start"));
        } 
    }
}

This tells the framework to route all initial requests to MainController's Start action, which is a method with signature Func<Task<UssdResponse>>.

Controller actions

Next we create our MainController which inherits UssdController.

using System;
using System.Threading.Tasks;

namespace Smsgh.UssdFramework.Demo.UssdControllers
{
    public class MainController : UssdController
    {
        public async Task<UssdResponse> Start()
        {
            var menu = UssdMenu.New("Welcome", Environment.NewLine + "by SMSGH")
                .AddItem("Greet me", "GreetingForm")
                .AddItem("What's the time?", "Time")
                .AddZeroItem("Exit", "Exit");
            return await RenderMenu(menu);
        }


        public async Task<UssdResponse> GreetingForm()
        {
            var form = UssdForm.New("Greet Me!", "Greeting")
                .AddInput(UssdInput.New("Name"))
                .AddInput(UssdInput.New("Sex")
                    .Option("M", "Male")
                    .Option("F", "Female"));
            return await RenderForm(form);
        } 

        public async Task<UssdResponse> Greeting()
        {
            var hour = DateTime.UtcNow.Hour;
            var greeting = string.Empty;
            if (hour < 12)
            {
                greeting = "Good morning";
            }
            if (hour >= 12)
            {
                greeting = "Good afternoon";
            }
            if (hour >= 18)
            {
                greeting = "Good night";
            }
            var name = FormData["Name"];
            var prefix = FormData["Sex"] == "M" ? "Master" : "Madam";
            return Render(string.Format("{0}, {1} {2}!", greeting, prefix, name));
        }

        public async Task<UssdResponse> Time()
        {
            return await Task.FromResult(Render(string.Format("{0:t}", 
                DateTime.UtcNow)));
        }

        public async Task<UssdResponse> Exit()
        {
            return await Task.FromResult(Render("Bye bye!"));
        } 
    }
}

And that's it!

See Smsgh.UssdFramework.Demo folder in source for full sample source code.

You can simulate USSD sessions using USSD Mocker.

Logging

It is often convenient to log USSD sessions. Smsgh.UssdFramework supports logging to MongoDB.

Dependencies

Visit mongodb.org/downloads to install MongoDB.

Installation

Install Smsgh.UssdFramework.Logging from NuGet.

PM> Install-Package Smsgh.UssdFramework.Logging

Setup

To enable logging pass an instance of MongoDbLoggingStore when calling Ussd.Process.

using System.Threading.Tasks;
using System.Web.Http;
using Smsgh.UssdFramework.Logging;
using Smsgh.UssdFramework.Stores;

namespace Smsgh.UssdFramework.Demo.Controllers
{
    public class DefaultController : ApiController
    {
        [HttpPost]
        public async Task<IHttpActionResult> Index(UssdRequest request)
        {
            return Ok(await Ussd.Process(new RedisStore(), request, "Main", "Start", null, 
                new MongoDbLoggingStore("mongodb://localhost", "demoussd")));
        } 
    }
}

That's it!

You now have detailed session logs in your MongoDB database. You can use a tool like UMongo to view logs.

License

MIT