Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ruach.ng/llms.txt

Use this file to discover all available pages before exploring further.

​
USSD Session Webhook

The USSD API sends POST requests to your configured endpoint for each stage of a USSD session. Your endpoint should parse the payload and return a JSON response that tells the network whether to continue or end the session.

​
Overview

The USSD session follows three stages:
  1. Begin: Starts a new session.
  2. Continue: Sends user input during an active session.
  3. End: Closes the session and displays a final response.
Your endpoint must be reachable and return valid JSON quickly. If the callback fails or times out, the session may terminate for the user.

​
Endpoint Setup

Provide a publicly reachable POST URL that can:
  • Receive JSON payloads for begin and continue events.
  • Return JSON responses in the expected format.
  • Handle optional backend data when provided by the network/backend.

​
Request Format

​
Begin Request

{
  "backend": {
    "cuap": {
      "body": {
        "code_scheme": 15,
        "msisdn": "2348099999999",
        "service_code": "*123",
        "ussd_content": "1",
        "ussd_op_type": 3,
        "ussd_version": 32
      },
      "header": {
        "command_id": 112,
        "command_length": 66,
        "command_status": 0,
        "receiver_id": 6904,
        "sender_id": 135477
      }
    }
  },
  "id": {
    "session": "",
    "ussd": "2417796521717513624645694627"
  },
  "msisdn": "2348099999999",
  "network": "9mobile",
  "session": {
    "type": {
      "code": 2,
      "name": "begin"
    },
    "ui": {
      "code": 1,
      "name": "input"
    }
  },
  "shortcode": "123",
  "status": {
    "code": 200,
    "message": "OK"
  },
  "text": "*123#"
}

​
Continue Request

{
  "backend": {
    "cuap": {
      "header": {
        "command_id": 112,
        "command_len": 172,
        "receiver_id": "135477",
        "sender_id": "135477"
      }
    }
  },
  "msisdn": "2348099999999",
  "network": "9mobile",
  "op_type": 1,
  "session": {
    "type": {
      "code": 3,
      "name": "continue"
    },
    "ui": {
      "code": 1,
      "name": "input"
    }
  },
  "shortcode": "123",
  "status": {
    "code": 200,
    "message": "OK"
  },
  "text": "1"
}

​
Response Format

​
Continue Response (Prompt User for More Input)

Use this response when you want the session to remain active. 
{
  "backend": {
    "cuap": {
      "header": {
        "command_id": 112,
        "command_len": 172,
        "receiver_id": "135477",
        "sender_id": "135477"
      }
    }
  },
  "msisdn": "2348099999999",
  "network": "9mobile",
  "op_type": 1,
  "session": {
    "type": {
      "code": 3,
      "name": "continue"
    },
    "ui": {
      "code": 1,
      "name": "input"
    }
  },
  "shortcode": "123",
  "text": "Select an option:\n1. Balance\n2. Buy Airtime"
}

​
End Response (Close Session)

Use this response when the interaction is complete. 
{
  "backend": {
    "cuap": {
      "header": {
        "command_id": 113,
        "command_len": 60,
        "receiver_id": "135477",
        "sender_id": "135477"
      }
    }
  },
  "msisdn": "2348099441402",
  "network": "9mobile",
  "op_type": 2,
  "session": {
    "type": {
      "code": 4,
      "name": "end"
    },
    "ui": {
      "code": 2,
      "name": "dialog"
    }
  },
  "shortcode": "123",
  "text": "Thank you for using our service."
}

​
Field Descriptions

​
Common Fields

​
msisdn
string
required
Subscriber phone number (for example, 2348099999999).
​
network
string
required
Mobile network name. Expected values include 9mobile, mtn, glo, and airtel.
​
shortcode
string
required
USSD shortcode used for the session (for example, 123).
​
text
string
required
Current USSD input/message content.

​
Session Fields

​
session.type.code
number
required
Session stage code (2 = begin, 3 = continue, 4 = end).
​
session.type.name
string
required
Session stage name (begin, continue, end).
​
session.ui.code
number
UI mode code (0 = none, 1 = input, 2 = dialog).
​
session.ui.name
string
UI mode name (none, input, dialog).

​
Optional Backend Fields

​
backend
object
Optional backend payload. This may vary by telco/network integration and can be omitted in responses.
​
backend.cuap.body
object
USSD backend body information.
​
backend.cuap.header
object
USSD backend header information.

​
Status Fields

​
status.code
number
Request status code (for example, 200).
​
status.message
string
Request status message (for example, OK).

​
Best Practices

  • Return only valid JSON in the expected shape.
  • Keep responses short and fast to avoid session timeout.
  • Treat backend as optional and parse defensively.
  • Log msisdn, session.type, and text for troubleshooting.