> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beem.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Build interactive USSD applications that work across multiple mobile networks through a single API.

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

```text theme={null}
Subscriber
     │
     │ Dial USSD Code
     ▼
Mobile Network Operator
     │
     ▼
Beem USSD Hub
     │
     │ HTTP Request
     ▼
Your Application
     │
     │ Menu Response
     ▼
Beem USSD Hub
     │
     ▼
Subscriber
```

***

## Session lifecycle

<Steps>
  <Step title="Dial USSD code">
    A subscriber dials your assigned USSD code from their mobile phone.
  </Step>

  <Step title="Request forwarded">
    The mobile network forwards the request to the Beem USSD Hub.
  </Step>

  <Step title="Callback to your API">
    Beem sends an HTTP request containing the session details to your application's callback URL.
  </Step>

  <Step title="Generate a response">
    Your application processes the request and returns the next menu or response.
  </Step>

  <Step title="Continue the session">
    The subscriber selects another option, and the process repeats until the session ends.
  </Step>

  <Step title="Session ends">
    The session ends when your application explicitly terminates it, the subscriber exits, or the session times out.
  </Step>
</Steps>

***

## Key features

<CardGroup cols={2}>
  <Card title="Single Integration">
    Integrate once and serve subscribers across multiple supported mobile networks.
  </Card>

  <Card title="Real-Time Menus">
    Generate menus dynamically from your own application in real time.
  </Card>

  <Card title="API Driven">
    Every user interaction is delivered to your application through simple HTTP callbacks.
  </Card>

  <Card title="Session Management">
    Maintain interactive sessions until the user exits or the session expires.
  </Card>
</CardGroup>

***

## 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](/api-reference/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](/guides/ussd/check-balance)). Contact [support@beem.africa](mailto:support@beem.africa) for tariffs and top-ups.

***

## API surface

| Integration                                        | Direction          | Description                                          |
| -------------------------------------------------- | ------------------ | ---------------------------------------------------- |
| [USSD callback](/guides/ussd/callback)             | Beem → your server | Session events (`initiate`, `continue`, `terminate`) |
| [Check credit balance](/guides/ussd/check-balance) | Your server → Beem | Query USSD billing balance (`app_name=USSD`)         |
| [USSD simulator](/api-reference/ussd/simulator)    | Testing tool       | Debug your callback without a live telco session     |

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

***

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/ussd/authentication">
    Set up API credentials for balance checks.
  </Card>

  <Card title="USSD callback" icon="webhook" href="/guides/ussd/callback">
    Implement your callback endpoint to handle session events.
  </Card>

  <Card title="Check balance" icon="wallet" href="/guides/ussd/check-balance">
    Query your USSD credit balance before launching campaigns.
  </Card>

  <Card title="USSD simulator" icon="mobile" href="/api-reference/ussd/simulator">
    Test your callback handler interactively without a real USSD session.
  </Card>
</CardGroup>