manuelgeek/ex_ussd

ExUssd

Example New USSD API

Simple USSD menu

Implement ExUssd init/2 callback. Use ExUssd.set/2 to set USSD value

@allowed_fields [
    :error, # -> Custom error message, Used in the `callback/2`
    :title, # -> USSD menu title
    :next, # -> %{name: "MORE", next: "98", delimiter: ":"}
    :previous, # -> %{name: "BACK", previous: "0", delimiter: ":"}
    :should_close, # -> Indicate Menu state, default `false`
    :split, # -> Set split menu list by,  default 7
    :delimiter, # -> Set delimiter style,  ":"
    :continue, # -> Navigation state, Used in the `callback/2`
    :default_error, # -> Set default error message, "Invalid Choice\n", Used in the `init/2`
    :show_navigation # Show navigation, default `true`  
  ]

  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "Welcome")
    end
  end

  menu = ExUssd.new(name: "Home", handler: MyHomeHandler)

  api_parameters = %{"service_code" => "*544#", "session_id" => "session_01", "text" => ""}

  ExUssd.goto(menu: menu, api_parameters: api_parameters)

  {:ok, %{menu_string: "Welcome", should_close: false}}

End USSD Session

Manually close USSD session, Use ExUssd.end_session/1 it takes the session_id as params

  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "Welcome")
      |> ExUssd.set(should_close: true)
    end
  end

  menu = ExUssd.new(name: "Home", handler: MyHomeHandler)

  api_parameters = %{"service_code" => "*544#", "session_id" => "session_01", "text" => ""}

  ExUssd.goto(menu: menu, api_parameters: api_parameters)
    |> case do
    {:ok, %{menu_string: menu_string, should_close: false}} ->
      "CON " <> menu_string

    {:ok, %{menu_string: menu_string, should_close: true}} ->
      # End Session
      ExUssd.end_session(session_id: "session_01")

      "END " <> menu_string
    end

USSD Simple List

Use ExUssd.add/2 to add to USSD menu list. The USSD menu list is [] by default.

  defmodule ProductAHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu |> ExUssd.set(title: "selected product a")
    end
  end

  defmodule ProductBHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu |> ExUssd.set(title: "selected product b")
    end
  end

  defmodule ProductCHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "selected product c")
    end
  end
  
  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "Welcome")
      |> ExUssd.add(ExUssd.new(name: "Product A", handler: ProductAHandler))
      |> ExUssd.add(ExUssd.new(name: "Product B", handler: ProductBHandler))
      |> ExUssd.add(ExUssd.new(name: "Product C", handler: ProductCHandler))
    end
  end

  menu = ExUssd.new(name: "Home", handler: MyHomeHandler)

USSD Nested List

Use ExUssd.add/2 to add to USSD menu list on Individual USSD menu.

  
  defmodule ProductCHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "selected product c")
    end
  end
  
  defmodule ProductBHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "selected product b")
      |> ExUssd.add(ExUssd.new(name: "Product C", handler: ProductCHandler))
    end
  end

  defmodule ProductAHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "selected product a")
      |> ExUssd.add(ExUssd.new(name: "Product B", handler: ProductBHandler))
    end
  end

  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "Welcome")
      |> ExUssd.add(ExUssd.new(name: "Product A", handler: ProductAHandler))    
    end
  end

  menu = ExUssd.new(name: "Home", handler: MyHomeHandler)

Using USSD navigation_response/1

Implement navigation_response/1 function on your USSD handler module. navigation_response/1 callback returns navigation status.

Scenario

User passes in invalid

• payload {:error, api_parameters}

User passes in valid input, name navigated to next menu

• payload {:ok, api_parameters}

  # ...
  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "Welcome")
      |> ExUssd.add(ExUssd.new(name: "Product A", handler: ProductAHandler))
      |> ExUssd.add(ExUssd.new(name: "Product B", handler: ProductBHandler))
      |> ExUssd.add(ExUssd.new(name: "Product C", handler: ProductCHandler))
    end

    def navigation_response(payload) do
      IO.inspect payload
    end
  end
  
  menu = ExUssd.new(name: "Home", handler: MyHomeHandler)

Using USSD callback/2

Implement ExUssd callback/2 in the event you need to validate the Users input

Simple validation menu

  # ...
  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "Welcome")
      |> ExUssd.add(ExUssd.new(name: "Product A", handler: ProductAHandler))
      |> ExUssd.add(ExUssd.new(name: "Product B", handler: ProductBHandler))
      |> ExUssd.add(ExUssd.new(name: "Product C", handler: ProductCHandler))
    end

    def callback(menu, api_parameters) do
      case api_parameters.text == "5555" do
        true ->
          menu
          |> ExUssd.set(title: "You have Entered the Secret Number, 5555")
          |> ExUssd.set(should_close: true)
          |> ExUssd.set(continue: true)

        _ ->
          menu 
          |> ExUssd.set(continue: false)
      end
    end
  end

  menu = ExUssd.new(name: "Home", handler: MyHomeHandler)

  api_parameters = %{"service_code" => "*544#", "session_id" => "session_01", "text" => "5555"}

  ExUssd.goto(menu: menu, api_parameters: api_parameters)

  {:ok, %{menu_string: "You have Entered the Secret Number, 5555", should_close: false}}

Nested validation menu

  # ...
  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(%{data: data} = menu, _api_parameters) do
      IO.inspect data
      menu 
      |> ExUssd.set(title: "Welcome")
      |> ExUssd.add(ExUssd.new(name: "Product A", handler: ProductAHandler))
      |> ExUssd.add(ExUssd.new(name: "Product B", handler: ProductBHandler))
      |> ExUssd.add(ExUssd.new(name: "Product C", handler: ProductCHandler))
    end

    def callback(menu, api_parameters) do
      case api_parameters.text == "5555" do
        true ->
          menu
          |> ExUssd.set(title: "You have Entered the Secret Number, 5555")
          |> ExUssd.set(should_close: true)
          |> ExUssd.set(continue: true)

        _ ->
          menu 
          |> ExUssd.set(continue: false)
      end
    end
  end

  defmodule PinHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "Enter your pin number")
      |> ExUssd.set(show_navigation: false)
    end

    def callback(menu, api_parameters) do
      case api_parameters.text == "4321" do
        true ->
          menu
          # |> ExUssd.navigate(data: %{name: "John"}, handler: MyHomeHandler)
          |> ExUssd.navigate(handler: MyHomeHandler)
          |> ExUssd.set(continue: true)
        _ ->
          menu 
          |> ExUssd.set(error: "Wrong pin number\n")
          |> ExUssd.set(continue: false)
      end
    end

    def navigation_response(payload) do
      IO.inspect payload
    end
  end

  menu = ExUssd.new(name: "Check PIN", handler: PinHandler)
  # ...

Using USSD dynamic

Dymanic Vertical menus

  # ...
  defmodule SubCountyHandler do
    use ExUssd.Handler
    def init(%{data: %{name: name}} = menu, api_parameters) do
      # TODO: Fetch county sub locations by county_code
      # Make dynamic location menus for the county
      # Split by 6 / 7
      menu 
      |> ExUssd.set(title: "#{name} County")
    end
  end

  defmodule CountyHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menus = [
        ExUssd.new(name: "Nairobi", data: %{county_code: 47, name: "Nairobi"}),
        ExUssd.new(name: "Mombasa", data: %{county_code: 01, name: "Mombasa"}),
        ExUssd.new(name: "Kisumu", data: %{county_code: 42, name: "Kisumu"})
      ]

      menu 
      |> ExUssd.set(title: "List of Counties")
      |> ExUssd.dynamic(menus: menus, handler: SubCountyHandler, orientation: :vertical)
    end
  end

  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "Welcome")
      |> ExUssd.add(ExUssd.new(name: "Counties List", handler: CountyHandler))
    end
  end

  menu = ExUssd.new(name: "Home", handler: MyHomeHandler)
  # ...
  {:ok, %{
   menu_string: "List of Counties\n1:Nairobi\n2:Mombasa\n3:Kisumu\n0:BACK",
   should_close: false
 }}

Dymanic Horizontal menus

Note: The name value is Truncated after 140 characters

  defmodule NewsHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menus = fetch_api() |> Enum.map(fn %{"title": title, "body": body} -> 
           ExUssd.new(name: title <> "\n" <> body)
      end)

      menu 
      |> ExUssd.set(title: "World News")
      |> ExUssd.dynamic(menus: menus, orientation: :horizontal)
    end

    def fetch_api do
    [
      %{
        "userId": 1,
        "id": 1,
        "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
        "body": "quia et suscipit suscipit recusandae consequuntur expedita et cum reprehenderit molestiae ut ut quas totam nostrum rerum est autem sunt rem eveniet architecto"
      },
      %{
        "userId": 1,
        "id": 2,
        "title": "qui est esse",
        "body": "est rerum tempore vitae sequi sint nihil reprehenderit dolor beatae ea dolores neque fugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis qui aperiam non debitis possimus qui neque nisi nulla"
      },
      %{
        "userId": 1,
        "id": 3,
        "title": "ea molestias quasi exercitationem repellat qui ipsa sit aut",
        "body": "et iusto sed quo iure voluptatem occaecati omnis eligendi aut ad voluptatem doloribus vel accusantium quis pariatur molestiae porro eius odio et labore et velit aut"
      }]
    end
  end

  defmodule MyHomeHandler do
    use ExUssd.Handler
    def init(menu, _api_parameters) do
      menu 
      |> ExUssd.set(title: "BBC News")
      |> ExUssd.add(ExUssd.new(name: "News", handler: NewsHandler))
      # |> ExUssd.add(ExUssd.new(name: "WorkLife", handler: WorkLifeHandler))
      # |> ExUssd.add(ExUssd.new(name: "Sports", handler: SportsHandler))
    end
  end

  menu = ExUssd.new(name: "Home", handler: MyHomeHandler)
  # ...
  {:ok, %{
   menu_string: "1/3\nsunt aut facere repellat provident occaecati excepturi optio reprehenderit\nquia et suscipit suscipit recusandae consequuntur expedita et ...\n0:BACK 98:MORE",
   should_close: false
 }}

Phoenix Simulator

Update your router's configuration to forward requests to ExUssd Simlutate with a menu entry and phone_numbers list

# lib/my_app_web/router.ex
use MyAppWeb, :router

import ExUssd
...

if Mix.env() == :dev do
  scope "/" do
    pipe_through :browser
    simulate "/simulator",
      menu: ExUssd.new(name: "Home", handler: MyHomeHandler),
      phone_numbers: ["254700100100", "254700200200", "254700300300"]
  end
end

Installation

If available in Hex, the package can be installed by adding ex_ussd to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_ussd, git: "https://github.com/lenileiro/ex_ussd.git", branch: "main"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/ex_ussd.