USSD Flow Studio

Design a USSD menu, test it in the simulator, export a server.

Screens (6)

Edit screen main

Links are by id. Renaming updates every option that points here.

Screen type
62/182 chars on screen

Options

Simulator

USSDSession open
Welcome to Demo Wallet 1. Buy airtime 2. Check balance 3. Exit
Gateway text
""
Response
CON from main

Validation

No problems found. The flow is ready to export.

Export server code

// USSD server generated by USSD Flow Studio.
//
//   npm install express
//   node ussd-server.mjs            # listens on $PORT (default 3000)
//
// Point your USSD gateway's callback URL at POST /ussd. The gateway sends the
// caller's full input history as a '*'-joined "text" field ("" on first dial).

import express from 'express'

const FLOW = {
  "start": "main",
  "nodes": {
    "main": {
      "id": "main",
      "prompt": "Welcome to Demo Wallet",
      "kind": "menu",
      "options": [
        {
          "key": "1",
          "label": "Buy airtime",
          "next": "airtime_network"
        },
        {
          "key": "2",
          "label": "Check balance",
          "next": "balance"
        },
        {
          "key": "3",
          "label": "Exit",
          "next": "goodbye"
        }
      ]
    },
    "airtime_network": {
      "id": "airtime_network",
      "prompt": "Buy airtime for which network?",
      "kind": "menu",
      "options": [
        {
          "key": "1",
          "label": "MTN",
          "next": "airtime_amount"
        },
        {
          "key": "2",
          "label": "Telecel",
          "next": "airtime_amount"
        },
        {
          "key": "3",
          "label": "AT",
          "next": "airtime_amount"
        },
        {
          "key": "0",
          "label": "Back",
          "next": "main"
        }
      ]
    },
    "airtime_amount": {
      "id": "airtime_amount",
      "prompt": "Select amount",
      "kind": "menu",
      "options": [
        {
          "key": "1",
          "label": "GHS 1",
          "next": "airtime_done"
        },
        {
          "key": "2",
          "label": "GHS 5",
          "next": "airtime_done"
        },
        {
          "key": "3",
          "label": "GHS 10",
          "next": "airtime_done"
        },
        {
          "key": "0",
          "label": "Back",
          "next": "airtime_network"
        }
      ]
    },
    "airtime_done": {
      "id": "airtime_done",
      "prompt": "Request received. You will get an SMS confirmation shortly.",
      "kind": "end",
      "options": []
    },
    "balance": {
      "id": "balance",
      "prompt": "Your Demo Wallet balance is GHS 120.50.",
      "kind": "end",
      "options": []
    },
    "goodbye": {
      "id": "goodbye",
      "prompt": "Thank you for using Demo Wallet.",
      "kind": "end",
      "options": []
    }
  }
}

function getScreen(id) {
  return Object.prototype.hasOwnProperty.call(FLOW.nodes, id) ? FLOW.nodes[id] : undefined
}

function render(screen) {
  if (screen.kind === 'end') return 'END ' + screen.prompt
  const lines = [screen.prompt, ...screen.options.map((o) => o.key + '. ' + o.label)]
  return 'CON ' + lines.join('\n')
}

export function handleUssd(text) {
  let screen = getScreen(FLOW.start)
  if (!screen) return "END Service unavailable."

  const keys = text === '' ? [] : text.split('*')
  for (const key of keys) {
    if (screen.kind === 'end') break
    const option = screen.options.find((o) => o.key === key)
    const next = option ? getScreen(option.next) : undefined
    if (!next) return "END Invalid option."
    screen = next
  }
  return render(screen)
}

const app = express()
app.use(express.urlencoded({ extended: false }))

app.post('/ussd', (req, res) => {
  const text = typeof req.body?.text === 'string' ? req.body.text : ''
  res.type('text/plain').send(handleUssd(text))
})

const server = app.listen(Number(process.env.PORT ?? 3000), () => {
  console.log('USSD server listening on port ' + server.address().port)
})