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

# Receive USSD session callback

> Webhook your application must implement. When a subscriber dials your USSD code, Beem POSTs session events (initiate, continue, terminate) to the callback URL configured in the Beem dashboard. Respond with the next menu prompt. Replace the server URL with your own HTTPS endpoint.



## OpenAPI

````yaml /openapi/ussd.json post /callback
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:
  /callback:
    post:
      summary: Receive USSD session callback
      description: >-
        Webhook your application must implement. When a subscriber dials your
        USSD code, Beem POSTs session events (initiate, continue, terminate) to
        the callback URL configured in the Beem dashboard. Respond with the next
        menu prompt. Replace the server URL with your own HTTPS endpoint.
      operationId: receiveUssdCallback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - command
                - msisdn
                - operator
                - session_id
                - payload
              properties:
                command:
                  type: string
                  enum:
                    - initiate
                    - continue
                    - terminate
                  description: >-
                    Session phase: initiate (first dial), continue (ongoing), or
                    terminate (close session).
                msisdn:
                  type: string
                  description: Subscriber mobile number.
                operator:
                  type: string
                  description: >-
                    Mobile network operator, e.g. vodacom, tigo, airtel,
                    halotel, ttcl.
                session_id:
                  type: string
                  description: Unique session identifier for the USSD transaction.
                payload:
                  type: object
                  required:
                    - request_id
                    - response
                  properties:
                    request_id:
                      description: >-
                        Step identifier. Use 0 on initiate; increment as the
                        session progresses.
                    response:
                      description: >-
                        Subscriber input for this step. Always 0 at the start of
                        a session.
            examples:
              initiate:
                summary: Session initiate
                value:
                  command: initiate
                  msisdn: '255762089337'
                  session_id: '4574'
                  operator: vodacom
                  payload:
                    request_id: 0
                    response: 0
              continue:
                summary: Session continue
                value:
                  command: continue
                  msisdn: '255762089337'
                  session_id: '6545'
                  operator: vodacom
                  payload:
                    request_id: '112322'
                    response: '2556730000002'
              terminate:
                summary: Session terminate
                value:
                  command: terminate
                  msisdn: '255762089337'
                  session_id: '7845'
                  operator: vodacom
                  payload:
                    request_id: '12323'
                    response: '1'
      responses:
        '200':
          description: Return the next USSD menu or session termination prompt
          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://example.com
          description: Your callback server — replace with your URL

````