DEVELOPERS

API Documentation

Integrate seamlessly with Malawi's most reliable infrastructure.

Overview

The Rapid Digital USSD API enables third-party applications to interact with Airtel Malawi's USSD network. The USSD Gateway acts as an intermediary, receiving requests from Airtel's core network and forwarding them securely to your application endpoint via HTTP POST.

When a user dials your provisioned USSD code (e.g., *4391*100#) or responds to a prompt, the Rapid USSD Gateway will forward a standardized JSON payload to your configured HTTP endpoint. Your application must process this request and return an appropriate response instructing the gateway on what to display to the user and whether to keep the session alive.

1. Receiving Requests

The Gateway will always forward USSD traffic to your endpoint using an HTTP POST request with a JSON body.

Request Headers

Content-Type: application/json

Request Payload (JSON)

The gateway sends a standardized JSON object containing the session and input details.

{
  "provider": "airtel_mw",
  "sessionId": "4693a120-1a1b-4c2d-8e4f-56789abcdef0",
  "msisdn": "265991234567",
  "phoneNumber": "+265991234567",
  "serviceCode": "*4391*100#",
  "input": "1",
  "rawInput": "1",
  "network": "airtel",
  "gatewayRequestId": "gw-req-12345",
  "timestamp": "2026-06-22T00:00:00.000Z"
}

Field Definitions

Field	Type	Description
`provider`	String	The originating telecom provider (e.g., `"airtel_mw"`).
`sessionId`	String	A unique identifier for the current USSD session. This remains the same across multiple interactions by the same user until the session ends or times out. Use this to maintain user state.
`msisdn`	String	The user's mobile number without the + prefix (e.g., `"265991234567"`).
`phoneNumber`	String	The user's mobile number formatted with the + prefix.
`serviceCode`	String	The root USSD code dialed by the user to initiate the session (e.g., `4391100#`).
`input`	String	The exact input provided by the user in the current interaction. On the very first request (dialing the code), this will often be the dial string or empty. On subsequent menus, it will be the digit/text they entered.
`rawInput`	String	The raw input string exactly as received from the telecom network. Typically matches `input`.
`network`	String	The telecom network identifier (`"airtel"`).
`gatewayRequestId`	String	A unique UUID generated by the gateway for this specific HTTP request, useful for tracing and debugging.
`timestamp`	String	ISO 8601 timestamp of when the gateway processed the request.

IMPORTANT: State ManagementAirtel only sends the latest input provided by the user. Your application must use the sessionId to keep track of the user's state/menu navigation level in your own database or cache.

2. Responding to the Gateway

Your application must return an HTTP 200 OK response with specific instructions for the telecom network. You must tell the network two things:

What text to display to the user.
Whether the session should remain open (awaiting more input) or be closed.

2.1 The Freeflow Header (Session Control)

You must include the Freeflow HTTP header in your response to instruct the gateway how to handle the session lifecycle.

Header Value	Meaning	Action
`Freeflow: FC`	Continue	The session remains active. The text is displayed with an input prompt.
`Freeflow: FB`	Break/End	The session is terminated. The text is displayed, and the menu closes.

2.2 Response Body (Display Text)

The Rapid Digital Gateway supports two formats for the response body: Plain Text or JSON.

Option A: Plain Text (Recommended)

Return a simple string containing the text you want to display on the user's screen.

Example: Prompting for input (Continue Session)

HTTP/1.1 200 OK
Content-Type: text/plain
Freeflow: FC

Welcome to My App!
1. Check Balance
2. Buy Airtime

Example: Ending the session (Break Session)

HTTP/1.1 200 OK
Content-Type: text/plain
Freeflow: FB

Your transaction was successful. Thank you!

Option B: JSON Response

If your framework prefers returning JSON, you can wrap your response text in a message property.

HTTP/1.1 200 OK
Content-Type: application/json
Freeflow: FC

{
  "message": "Enter your PIN to continue:"
}

WARNING: Timeout ConstraintsTelecom networks enforce strict timeouts on USSD sessions (typically 30-60 seconds for the user to respond, and ~2-5 seconds for your API to return a response). Ensure your application responds to the gateway as quickly as possible. If your API takes too long, the gateway will return an error to the user and terminate the session.

Ready to build your USSD menu?

Reach out to our team to provision your shortcode and get your endpoint connected to the Airtel core network.