Telco Gateway
USSD Gateway & Interactive Menus
Provision dedicated or shared USSD codes (e.g. *123*111#), manage interactive menu applications, and handle telco session webhooks.
Architecture & Integration Guidelines:
- Protocol: When a subscriber dials your USSD code, CBI Gateway sends an HTTP POST to your configured callback_url.
- Response Format: Return plain text starting with CON (prompt user for input) or END (terminate session).
- Session timeout is configurable per application (default: 60 seconds). Sessions are identified by unique session_id.
POST
→ Inbound: https://your-server.com/ussd/callbackHandle USSD Session Callback
CBI Gateway POSTs this payload to your callback_url on every USSD interaction. Respond with plain text starting with CON (continue) or END (terminate).
Request Headers
Header
Value
Authorization
Bearer cbi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type
application/json
X-Channel
api
Request Body
{
"session_id": "sess_MTN_201910291828000000012345",
"phone_number": "+2348012345678",
"service_code": "*123*001#",
"text": "1*2",
"network": "MTN",
"created_at": "2026-08-26T12:00:00Z"
}Code Execution Playground
Request Snippet (CURL)
# Your server handles inbound POST from CBI Gateway: # POST https://your-server.com/ussd/callback # Body (form): session_id=sess_MTN_...&phone_number=+2348012345678&text=1 # Response must be plain text: # CON Welcome to Mobile Banking # 1. Check Balance # 2. Transfer
Success Response (200 OK)
{
"_note": "Your server must return plain text, not JSON.",
"example_con_response": "CON Welcome to Mobile Banking\\n1. Check Balance\\n2. Transfer\\n3. Exit",
"example_end_response": "END Your balance is NGN 93,300.01. Thank you."
}