# ExUssd

[![Actions Status](]( ![]( ![](


- An idiomatic, readable, and comfortable API for Elixir developers
- Extensibility based on small parts that do one thing well.
- Detailed error messages and documentation.
- A focus on robustness and production-level performance.

## Why Use ExUssd?

 ExUssd lets you create simple, flexible, and customizable USSD interface.
 Under the hood ExUssd uses Elixir Registry to create and route individual USSD session.

## Documentation

The docs can be found at [](

## Installation

The package can be installed
by adding `ex_ussd` to your list of dependencies in `mix.exs`:

defp deps do
    {:ex_ussd, "~> 1.0.2"}

## Configuration

Add to your `config.exs`

# config/config.exs
# TODO: This are example values, replace them with your own
config :ex_ussd,
  nav: [ :home, name: "HOME", match: "00", reverse: true, orientation: :vertical), :back, name: "BACK", match: "0", right: 1), :next, name: "MORE", match: "98")
  delimiter: ").",
  default_error: "invalid input,try again\n"

## Usage

### ExUssd Callbacks

ExUssd provides you with 3 callbacks

#### Example

Create a new module:

defmodule ApiWeb.HomeResolver do
  use ExUssd
  def ussd_init(menu, _payload) do
    ExUssd.set(menu, title: "Enter your PIN")

  def ussd_callback(menu, payload, %{attempt: %{count: count}}) do
    if payload.text == "5555" do
      |> ExUssd.set(data: %{name: "John"}) # use payload `phone_number` to fetch the user from DB
      |> ExUssd.set(resolve: &home_rc/2)
      ExUssd.set(menu, error: "Wrong PIN, #{2 - count} attempt left\n")

  def ussd_after_callback(%{error: true} = menu, _payload, %{attempt: %{count: 3}}) do
    |> ExUssd.set(title: "Account is locked, Dial *234# to reset your account")
    |> ExUssd.set(should_close: true)

  def home_rc(%ExUssd{data: %{name: name}} = menu, _) do
    |> ExUssd.set(title: "Welcome #{name}!")
    |> ExUssd.add( "option 1"))
    |> ExUssd.add( "option 2"))
    |> ExUssd.set(show_navigation: false) # hide navigation options

## Contribution

If you'd like to contribute, start by searching through the [issues]( and [pull requests]( to see whether someone else has raised a similar idea or question.
If you don't see your idea listed, [Open an issue](

Check the [Contribution guide]( on how to contribute.

## Contributors

Auto-populated from:

<a href="">
  <img src="" />

## Licence

ExUssd is released under [Apache License 2.0](./LICENSE).