USSD Gateway Sandbox Configuration
Visual Screen States
AI Text-to-App Converter
Paste any plain-text USSD proposal, document, or bullet-point menu specs (such as screens, choices, amounts, and pin confirmations) here. Our smart parser will instantly convert it into a fully-functional, system-compatible USSD flow for you!
Edit USSD Schema JSON
Add Screen State
Telemetry Real-time Analytics
USSD Templates & Best Practices
Boost your development with our production-grade templates and standards.
Enterprise USSD Developer Reference Center
GSM Protocol & Encoding Limits
USSD (Unstructured Supplementary Service Data) operates directly on GSM signaling channels (specifically MAP/SS7 layer) rather than the GPRS IP layer. This means communication is highly synchronous, fast, and light on power.
- Character Budget: Maximum transaction packet is 182 characters using 7-bit GSM default alphabet. For double-byte languages (UCS2), the limit drops to 90 characters.
- Interactive Formatting: Always utilize newline characters (
\n) to structure lists. Avoid HTML tags, emojis, or rich formatting, which will translate to garbled characters on legacy phone chipsets. - Page Segmentation: If a prompt exceeds the 182-char budget, implement a pagination screen (e.g.,
98. More) to preserve telecom stream integrity and avoid packet dropouts.
HTTP GET Callback API Protocols & Parameters
When in Proxy Forwarder mode, the MSpace USSD Gateway forwards the active telecom session directly to your registered callback URL as a standard HTTP GET request with URL-encoded query parameters.
?MSISDN=254718317877
&SERVICE_CODE=*702*MARTIN_default%23
&SESSION_ID=98765432101
&USSD_STRING=1*2
MSISDN: The phone number of the simulated or live mobile subscriber.SERVICE_CODE: The unique USSD dial sequence/root code (e.g.,*702*MARTIN_default#).SESSION_ID: A persistent, unique transaction reference generated for the session lifecycle.USSD_STRING: The raw inputs entered by the user (separated by stars, e.g.1*2*98). Empty on initial dial.
Your backend API must respond with an HTTP 200 containing raw text prefixed by telecom control strings:
CON Welcome to USSD: Tells the gateway to keep the session alive and present an input text field to the subscriber.END Account balance is KES 500: Tells the gateway to show this final text and disconnect the call session immediately.
Session State & Timeouts
USSD is inherently a stateless transaction protocol. The user's cell carrier passes a unique session_id with each query in a single transaction sequence.
- Interactive Session Lifespan: Telco switches enforce a strict session timeout between 30 and 120 seconds. If no dynamic key input is registered within this window, the MSC drops the call signal.
- Backend Processing Timeout: The MSpace USSD Router expects your proxy endpoint response in under 4.5 seconds. If your server is slower, the gateway responds to the carrier with an automatic timeout drop message.
Troubleshooting & Diagnostics
- Error: "Testing mode active but no authorized test MSISDN..." - Testing mode is set to active. You must register your exact phone number in the Test Phone input in the Gateway Config panel to allow it through the gateway firewall.
- Error: HTTP 502 / Bad Gateway - Occurs when in Proxy Forwarding mode and your target API is offline, returning invalid JSON, or refusing CORS requests. Ensure standard headers are configured.
USSD Code Generator
Generate production-ready USSD handler code in your preferred language from your current flow schema.
Register Your Callback URL
Self-hosting your USSD backend? Submit your production callback URL and MSpace will route all live traffic from your shortcode directly to your server.
Developer Sandbox
Test your local USSD handler application live against the simulator. Note: To test an app running on your local machine, you must expose it via a public tunnel (like Ngrok). Private/local hostnames like localhost or 127.0.0.1 cannot be reached directly by our server.
Press Run Test or click Dial to establish a simulation session
Go-Live Production Integration
Request direct integration to MSpace's primary telecom switches. Transition from Sandbox environment to live Production in one click.
Your Production Applications
Onboarding Application Status
PENDINGAdministrator Feedback
Awaiting review from MSpace Operations team.
Production Access Credentials
Use the following keys to bind your production USSD portal integrations. Keep these secure.
Recent Portal Dispatch Logs
(Real-time Audit Trail)Submit Application for Production Review
External Apps: Only provide this URL if you are developing and hosting the USSD logic from your own external servers.
Purpose: Proves corporate legitimacy. Required by mobile telecommunication networks to verify legal business entities.
Purpose: Validates tax compliance. Authenticates business registration and ensures compliance with Safaricom and KRA laws.
Purpose: Duly filled and signed on company letterhead authorizing MSpace to allocate and manage the USSD service code.
Purpose: Complete Shared/Dedicated USSD subscriber application document capturing setup and routing specifications.
Purpose: Mobile numbers to be whitelisted for testing and verification during dry-run before full public release.
Purpose: Dynamic webhook endpoint target where your backend application logic is hosted to respond to USSD menus.
Purpose: Signed acknowledgement confirming compliance with communications authority rules governing allocating string resources.
Real-Time Gateway Log
Awaiting transactions. Dial the simulator to stream live logs.