USSD callback

When a subscriber dials your USSD code, Beem POSTs session events to your callback URL. Your application processes each event and returns the next menu prompt until the session ends. See Receive USSD session callback for the interactive API reference.

Callback flow

Subscriber dials *123#
        │
        ▼
Beem USSD Hub
        │
        │ POST /your/callback
        ▼
Your application
        │
        │ JSON menu response
        ▼
Beem USSD Hub → Subscriber screen

Inbound request fields

Beem sends a JSON body on every session step:

Field	Type	Description
`command`	string	`initiate`, `continue`, or `terminate`
`msisdn`	string	Subscriber mobile number
`operator`	string	Network operator (`vodacom`, `tigo`, `airtel`, `halotel`, `ttcl`, etc.)
`session_id`	string	Unique session identifier
`payload.request_id`	string/number	Step identifier (`0` on initiate)
`payload.response`	string/number	Subscriber input (`0` at session start)

Outbound response fields

Return HTTP 200 with a JSON body:

Field	Type	Description
`msisdn`	string	Echo subscriber number
`operator`	string	Echo operator
`session_id`	string	Echo session ID
`command`	string	Next command: `continue` or `terminate`
`payload.request_id`	string/number	Step identifier for your menu
`payload.request`	string	Menu text shown to the subscriber

In your response, the payload field is request (the menu text). In Beem’s inbound request, the equivalent subscriber input field is response.

Sample requests

Initiate
Continue
Terminate

{
  "command": "initiate",
  "msisdn": "255762089337",
  "session_id": "4574",
  "operator": "vodacom",
  "payload": { "request_id": 0, "response": 0 }
}

{
  "command": "continue",
  "msisdn": "255762089337",
  "session_id": "6545",
  "operator": "vodacom",
  "payload": { "request_id": "112322", "response": "2556730000002" }
}

{
  "command": "terminate",
  "msisdn": "255762089337",
  "session_id": "7845",
  "operator": "vodacom",
  "payload": { "request_id": "12323", "response": "1" }
}

Sample responses

Menu prompt
End session

{
  "msisdn": "2556730893370",
  "operator": "vodacom",
  "session_id": "66545",
  "command": "terminate",
  "payload": {
    "request_id": "2",
    "request": "Thank you. Session ended."
  }
}

Sample implementations

Node.js
GitHub

const express = require("express");
const app = express();

app.use(express.json());

const ussdMenu = [{ text: "enter phone number" }, { text: "enter amount" }];

app.post("/ussd/callback", (req, res) => {
  let {
    command,
    msisdn,
    session_id,
    operator,
    payload: { request_id, response },
  } = req.body;

  const request = ussdMenu[request_id]?.text || "Invalid option";
  command = request_id + 1 === ussdMenu.length ? "terminate" : "continue";

  res.json({
    msisdn,
    operator,
    session_id,
    command,
    payload: { request_id, request },
  });
});

app.listen(4000, () => console.log("USSD callback on port 4000"));

Session commands

Command	When Beem sends it	Your typical response
`initiate`	Subscriber first dials your code	Show main menu (`command: continue`)
`continue`	Subscriber selects an option	Show next prompt or terminate
`terminate`	Session is closing	Acknowledge and close (`command: terminate`)

Respond within the operator timeout window (typically a few seconds) to avoid session failure.

Getting Started

APIs

Callback flow

Inbound request fields

Outbound response fields

Sample requests

Sample responses

Sample implementations

Session commands

​Callback flow

​Inbound request fields

​Outbound response fields

​Sample requests

​Sample responses

​Sample implementations

​Session commands

Callback flow

Inbound request fields

Outbound response fields

Sample requests

Sample responses

Sample implementations

Session commands