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.

JSON HTTP Integration Callback API

When in Proxy Forwarder mode, the MSpace Gateway proxies the incoming GSM packet directly to your registered callback URL as an HTTP POST request.

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.