> ## 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.

# USSD simulator

> Test your USSD callback with the Beem sandbox simulator.

<Info>
  Your callback URL must be **publicly reachable over HTTPS**. The simulator forwards each request to your endpoint via `https://ussdsim.beem.africa/`.
</Info>

***

## How to use

<Steps>
  <Step title="Set the three body fields">
    Enter **operator**, **msisdn**, and **callbackUrl**, then click **Try it**.
  </Step>

  <Step title="Verify your handler">
    Confirm your callback returns the next menu prompt with HTTP 200.
  </Step>
</Steps>

***

## Related

* [USSD callback](/guides/ussd/callback) — implement your handler
* [Receive USSD session callback](/api-reference/ussd/receive-ussd-session-callback) — production callback format


## OpenAPI

````yaml openapi/ussd.json POST /
openapi: 3.0.3
info:
  title: Beem USSD API
  version: 1.0.0
  description: >-
    USSD Hub integration: customer-hosted session callbacks and credit balance
    checks via the shared Topup service (app_name=USSD).
  contact:
    name: Beem
    url: https://beem.africa
    email: support@beem.africa
servers:
  - url: https://apitopup.beem.africa/v1
    description: Topup API — credit balance
security: []
tags: []
paths:
  /:
    post:
      summary: USSD simulator
      description: >-
        Send a test USSD session through the Beem sandbox proxy. Enter your
        **operator**, **msisdn**, and **callbackUrl** — the simulator forwards
        the request to your callback endpoint.
      operationId: ussdSimulator
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - operator
                - msisdn
                - callbackUrl
              additionalProperties: false
              properties:
                operator:
                  type: string
                  enum:
                    - tigotz
                  description: Mobile network operator to simulate.
                  example: tigotz
                msisdn:
                  type: string
                  description: Subscriber phone number (12 digits, e.g. 255712444555).
                  example: '255712444555'
                callbackUrl:
                  type: string
                  format: uri
                  description: Your publicly accessible USSD callback endpoint (HTTPS).
                  example: https://your-app.example.com/ussd/callback
            examples:
              default:
                summary: Test session
                value:
                  operator: tigotz
                  msisdn: '255712444555'
                  callbackUrl: https://your-app.example.com/ussd/callback
      responses:
        '200':
          description: Response from your callback handler
          content:
            application/json:
              schema:
                type: object
                required:
                  - msisdn
                  - operator
                  - session_id
                  - command
                  - payload
                properties:
                  msisdn:
                    type: string
                    description: Echo the subscriber mobile number.
                  operator:
                    type: string
                    description: Echo the operator.
                  session_id:
                    type: string
                    description: Echo the session ID.
                  command:
                    type: string
                    enum:
                      - initiate
                      - continue
                      - terminate
                    description: Next session command Beem should apply.
                  payload:
                    type: object
                    required:
                      - request_id
                      - request
                    properties:
                      request_id:
                        description: Step identifier for the menu you are returning.
                      request:
                        type: string
                        description: USSD menu text or prompt shown to the subscriber.
              examples:
                menuPrompt:
                  summary: Menu prompt
                  value:
                    msisdn: '2556730893370'
                    operator: vodacom
                    session_id: '33545'
                    command: continue
                    payload:
                      request_id: '1'
                      request: enter amount
                sessionEnd:
                  summary: End session
                  value:
                    msisdn: '2556730893370'
                    operator: vodacom
                    session_id: '66545'
                    command: terminate
                    payload:
                      request_id: '2'
                      request: press 1 to end session
      servers:
        - url: https://ussdsim.beem.africa
          description: Beem USSD sandbox proxy

````