Skip to main content
The Beem USSD Hub enables businesses to build, deploy, and manage interactive USSD applications through a single unified API. Instead of integrating separately with each mobile network operator, Beem acts as a gateway between your application, mobile subscribers, and supported operators. This allows you to create USSD services that work across multiple networks using one integration. Whenever a subscriber starts a USSD session, the Beem USSD Hub forwards the request to your application’s callback endpoint. Your application processes the request, returns the appropriate menu or response, and Beem delivers it back to the subscriber. This exchange continues until the session is completed or terminated.

​
How the USSD Hub works

​
Session lifecycle

1

Dial USSD code

A subscriber dials your assigned USSD code from their mobile phone.
2

Request forwarded

The mobile network forwards the request to the Beem USSD Hub.
3

Callback to your API

Beem sends an HTTP request containing the session details to your application’s callback URL.
4

Generate a response

Your application processes the request and returns the next menu or response.
5

Continue the session

The subscriber selects another option, and the process repeats until the session ends.
6

Session ends

The session ends when your application explicitly terminates it, the subscriber exits, or the session times out.

​
Key features

Single Integration

Integrate once and serve subscribers across multiple supported mobile networks.

Real-Time Menus

Generate menus dynamically from your own application in real time.

API Driven

Every user interaction is delivered to your application through simple HTTP callbacks.

Session Management

Maintain interactive sessions until the user exits or the session expires.

​
Session timing

USSD sessions are short-lived. If your callback endpoint does not respond in time, or the subscriber is idle, the session may timeout and terminate automatically. Design menus to minimize round trips and respond quickly (typically within a few seconds). Exact timeout windows may vary by mobile network. Test with the USSD simulator and your account manager before production launch.

​
Best practices

  • Return menus promptly — slow responses cause session timeouts
  • Use terminate when the flow is complete; do not leave sessions open
  • Validate session_id and msisdn on every callback
  • Handle duplicate callbacks idempotently where possible
  • Test all menu paths with the simulator before go-live

​
Billing

USSD sessions are billed from your Beem USSD credit balance (app_name=USSD on Check balance). Contact support@beem.africa for tariffs and top-ups.

​
API surface

Beem manages communication with mobile network operators while your application controls the business logic and user experience.

​
Next steps

Authentication

Set up API credentials for balance checks.

USSD callback

Implement your callback endpoint to handle session events.

Check balance

Query your USSD credit balance before launching campaigns.

USSD simulator

Test your callback handler interactively without a real USSD session.