EmergentUssdGateway

EmergentUssdGateway is a Ruby gem that simplifies handling USSD requests from the Emergent Technology USSD Gateway. Built for Rails developers, it provides a structured way to parse USSD push requests, manage sessions, and send back valid JSON responses.

Features

Parse and normalize USSD initiation, response, release, and timeout events
Provide structured response builders for Response and Release
Easily integrate with any Rails app by subclassing a base controller
Mask input routes when expecting confidential entries like PINs
Optional local session tracking (in-memory, Redis, etc. - future versions)

Installation

Add this line to your Gemfile:

gem 'emergent_ussd_gateway'

Then run:

bundle install

Or install it directly:

gem install emergent_ussd_gateway

Usage in Rails

Create a controller that inherits from the gem’s base controller and implement your USSD logic by overriding handle_ussd.

# app/controllers/emergent_ussd_controller.rb
class EmergentUssdController < EmergentUssdGateway::BaseController
  private

  def handle_ussd(request)
    case request.type.downcase
    when "initiation"
      EmergentUssdGateway::ResponseBuilder.new(
        type: "Response",
        message: "Welcome.\n1. Check Balance 2. Change PIN 3. Request Support."
      )
    when "response"
      case request.message.strip
      when "1"
        EmergentUssdGateway::ResponseBuilder.new(
          type: "Release",
          message: "Your account balance is GHS 53,743"
        )
      when "2"
        EmergentUssdGateway::ResponseBuilder.new(
          type: "Response",
          message: "Enter your new PIN",
          mask_next_route: true
        )
      when "3"
        EmergentUssdGateway::ResponseBuilder.new(
          type: "Response",
          message: "Support: Call 1234 or email support@example.com"
        )
      else
        EmergentUssdGateway::ResponseBuilder.new(
          type: "Response",
          message: "Invalid option. 1. Check Balance 2. Change PIN 3. Request Support."
        )
      end
    else
      EmergentUssdGateway::ResponseBuilder.new(
        type: "Release",
        message: "Session ended."
      )
    end
  end
end

Add a route to your config/routes.rb:

post "/ussd-app", to: "emergent_ussd#ussd"

Example Payloads

Incoming POST from Emergent Gateway

{
  "Mobile": "233262183777",
  "SessionId": "abc123",
  "ServiceCode": "711",
  "Type": "initiation",
  "Message": "*711#",
  "Operator": "Vodafone"
}

Response JSON

{
  "Type": "Response",
  "Message": "Enter your PIN",
  "MaskNextRoute": true
}

Development

git clone https://github.com/smorttey/emergent_ussd_gateway.git
cd emergent_ussd_gateway
bin/setup       # Install dependencies
rake spec       # Run tests
bin/console     # Interactive dev console

To install locally:

bundle exec rake install

To release a new version:

Update lib/emergent_ussd_gateway/version.rb
Run:
```
bundle exec rake release
```

Contributing

Bug reports and pull requests are welcome at: https://github.com/smorttey/emergent_ussd_gateway

License

This gem is available as open source under the terms of the MIT License.