Copy page

USSD Internals

Cellcube XML/HTTP Protocol — LCC-Orange USSD Gateway Integration

This document provides a comprehensive summary of the Cellcube XML/HTTP Interface Specification (Release 6.6.0) by Myriad, detailing the protocol requirements for integrating with the LCC-Orange (Liberia Cellcom/Orange) USSD gateway. It maps every protocol requirement against our current Tech231 Platform USSD gateway architecture and the existing LiberiaOrangeAdapterGrain implementation.

---

Table of Contents

• 1. Protocol Overview
• 2. Architecture Models
• 3. XML Response Format (ESP → Cellcube)
  • 3.1 Document Structure
  • 3.2 DTD Reference
  • 3.3 Page Element
  • 3.4 Links (Menu Options)
  • 3.5 Forms (User Input)
  • 3.6 Navigation Control
  • 3.7 Session Termination
  • 3.8 Content Adaptation
  • 3.9 Multiple Pages & Tags
  • 3.10 Includes & Redirects
  • 3.11 Multi-Language Support
  • 3.12 Plugin Functions
  • 3.13 Dynamic Content in Links
• 4. HTTP Interface Requirements (Cellcube → ESP)
  • 4.1 Request Format
  • 4.2 Response Format
  • 4.3 User Identity Headers
  • 4.4 Session Management (Cookies)
  • 4.5 Cache Control
  • 4.6 Quality of Service & Timeouts
  • 4.7 Error Handling
  • 4.8 HTTP Redirects
  • 4.9 Enhanced HTTP Redirect (Orange Money)
  • 4.10 Keep-Alive & Transport
  • 4.11 Traffic Shaping
• 5. Mapping to Tech231 Platform Architecture
  • 5.1 Our Role as ESP
  • 5.2 Request Ingress Path
  • 5.3 LiberiaOrangeAdapterGrain Implementation
  • 5.4 XML Serialization Models
  • 5.5 Flow Control Mapping
• 6. Protocol Constraints & Limitations
• 7. Implementation Gaps & Recommendations
• 8. Quick Reference: HTTP Headers
• 9. Full XML Example

---

1. Protocol Overview

Cellcube is a USSD gateway platform (by Myriad, now part of Orange/LCC infrastructure) that acts as an intermediary between the GSM network and External Service Providers (ESPs). It provides:

• A USSD browsing experience for mobile subscribers
• An XML/HTTP interface that allows ESPs (like our Tech231 Platform) to serve dynamic USSD menus
• Automatic content adaptation (page splitting, character translation, navigation management)
• Session management including cookies, back/home navigation, and shortcuts

How It Works

Code
┌──────────┐         ┌──────────────┐         ┌──────────────────────────┐
│  Mobile   │  USSD   │   Cellcube   │  HTTP   │  Tech231 Platform (ESP)  │
│  Handset  │◄──────►│   Gateway    │◄──────►│  Ussd.App / Silo          │
│           │  SS7    │  (LCC-Orange)│  XML    │                          │
└──────────┘         └──────────────┘         └──────────────────────────┘

Key insight: In this architecture, our platform acts as an External Service Provider (ESP). Cellcube sends us HTTP requests on behalf of the mobile user, and we respond with XML-formatted pages following the Cellcube DTD.

Protocol Characteristics

Property	Value
Protocol Version	Cellcube XML/HTTP Release 6.6.0
Transport	HTTP/1.0 and HTTP/1.1 over IPv4
Request Methods	GET, HEAD, POST (from Cellcube to ESP)
Response Content-Type	text/xml
Supported Charsets	us-ascii, iso-8859-1, utf-8
Max USSD Message Size	182 characters
Session Model	USSD Phase 2 (multi-turn interactive)
DTD	cellflash-1.3.dtd (Cellcube XML DTD v1.3)

---

2. Architecture Models

Cellcube supports three deployment modes. For LCC-Orange, we operate in the Open Gateway model:

2.1 Open Gateway Architecture (Our Model)

Code
                                    ┌─────────────────────┐
                                    │   Remote HTTP        │
                                    │   Servers (ESPs)     │
                                    │   ── Tech231 ──      │
             ┌──────────────────┐   │                     │
  GSM        │                  │   └─────────┬───────────┘
  Network ──►│    Cellcube      │◄────────────┘
             │    Gateway       │   Internet / Firewall
             │                  │
             │  ┌────────────┐  │   ┌─────────────────────┐
             │  │ Local      │  │   │  Local HTTP          │
             │  │ XML Files  │  │   │  Servers (Operator)  │
             │  └────────────┘  │   └─────────────────────┘
             │                  │
             │  Operator        │
             │  Platforms       │
             └──────────────────┘

In this model:

• Cellcube routes specific USSD service codes or menu items to our HTTP server
• The operator (LCC-Orange) manages privacy/security authorizations
• Our server receives HTTP requests and responds with Cellcube-compliant XML

---

3. XML Response Format (ESP → Cellcube)

3.1 Document Structure

Every XML response must include:

1. XML declaration with encoding
2. DOCTYPE referencing the Cellcube DTD
3. Root <pages> element containing one or more <page> elements

Code
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pages SYSTEM "cellflash-1.3.dtd">
<pages descr="Service Name">
  <page>
    Welcome to our service
    <a href="menu2.xml">Option 1</a>
    <a href="menu3.xml">Option 2</a>
  </page>
</pages>

3.2 DTD Reference

The complete Cellcube XML DTD v1.3 defines these entities:

Code
<!ENTITY % pckw    "#PCDATA|kw|br">
<!ENTITY % citem   "%pckw;|include|subst|lang">
<!ENTITY % navig   "%citem;|a|form|nbblock|help|title">

<!ELEMENT pages    (page*)>
<!ELEMENT page     (((%ht;)*,redirect)|(%navig;)*)>
<!ELEMENT a        (%citem;|help)*>
<!ELEMENT form     (entry)*>
<!ELEMENT entry    (prompt)>
<!ELEMENT include  EMPTY>
<!ELEMENT redirect EMPTY>
<!ELEMENT subst    EMPTY>

3.3 Page Element

The <page> element is the core building block. Key attributes:

Attribute	Values	Default	Description
nav	default, end, stop	default	Session flow control
tag	string	—	Page identifier for internal links (#tag)
hist	default, donthist, dohist, bookmark	default	Navigation history control
ismenu	true, false	false	Marks page as menu target
volatile	true, false	false	Prevents caching/resending
backtext	string	—	Custom "Back" label (use "notext" to hide)
menutext	string	—	Custom "Menu" label (use "notext" to hide)
helptext	string	—	Custom "Help" label
hometext	string	—	Custom "Home" label
cost	string	—	Billing information
log	string	—	Logging tag
descr	string	—	Page description

3.4 Links (Menu Options)

Links are rendered as numbered menu items by Cellcube. They function like HTML anchor elements:

Code
<page>
  Select a service
  <a href="balance.xml">Check Balance</a>
  <a href="transfer.xml">Transfer Money</a>
  <a href="airtime.xml">Buy Airtime</a>
</page>

Cellcube displays this as:

Code
Select a service
1:Check Balance
2:Transfer Money
3:Buy Airtime
0:Back 00:Menu

Link attributes:

Attribute	Required	Description
href	Yes	Target URL (absolute, relative, or #tag)
key	No	Custom shortcut key (overrides auto-numbering)
cost	No	Billing information

URL formats supported:

Code
<a href="http://www.myservice.com:8080/path/to/file.xml">Remote</a>
<a href="/path/to/file.xml">Absolute local</a>
<a href="otherfile.xml">Relative</a>
<a href="#otherpage">Same file, different page</a>
<a href="#">Back to main page</a>

3.5 Forms (User Input)

Cellcube supports simple input forms similar to HTML:

Code
<page>
  <form action="/api/process" method="POST">
    <entry kind="digits" var="amount">
      <prompt>Enter amount:</prompt>
    </entry>
  </form>
</page>

Form attributes:

Attribute	Values	Default	Description
action	URL	—	Target URL for form submission
method	GET, POST	GET	HTTP method
keywords	default, disable, user_defined	default	Navigation keyword handling
back	URL	—	Custom back target
menu	URL	—	Custom menu target
home	URL	—	Custom home target

Entry attributes:

Attribute	Values	Description
kind	digits, alpha, alphanum	Input type restriction
var	string	Variable name for submitted value

The user's input is sent as query parameters (GET) or form body (POST):

Code
GET /api/process?amount=50000 HTTP/1.0

3.6 Navigation Control

Cellcube provides built-in navigation that the ESP can control:

Navigation Command	Default Key	Description
Back	0	Return to previous page
Menu	00	Return to latest menu
Home	Varies	Return to first page of session
Help	Varies	Display help page
Bookmark	Varies	Bookmark current page

Navigation shortcuts: Users can chain selections with *, e.g., dialing *100*2*3# navigates through item 2, then item 3 automatically.

Forbid shortcuts: Use nav="stop" on confirmation pages to prevent shortcut bypass:

Code
<page nav="stop">
  Please confirm!
  <a href="accept.xml">Accept</a>
  <a href="cancel.xml">Cancel</a>
</page>

History control: Use hist="donthist" to skip a page in back navigation (useful for redirects/processing pages).

3.7 Session Termination

Set nav="end" to terminate the USSD session after the user reads the page:

Code
<page nav="end">
  Your transfer was successful.
  Transaction ID: 12345
</page>

This maps directly to our MenuFlowControl.Break concept.

3.8 Content Adaptation

Cellcube automatically handles:

• Page splitting: Text exceeding the USSD message limit (182 chars) is split into multiple messages with auto-generated "Next"/"Previous" links
• Character translation: Characters not supported by the handset are replaced (e.g., é → e)
• Line formatting: <br/> elements create line breaks; consecutive whitespace is collapsed
• Link formatting: Links are automatically prefixed with numbers (1:, 2:, 3:, etc.)
• Navigation labels: Back/Menu/Home labels are appended automatically and localized

Important for our implementation: Since Cellcube handles pagination, we should NOT pre-split content. However, we still track CharacterLimit (182) to optimize response size.

3.9 Multiple Pages & Tags

A single XML document can contain multiple pages using tag attributes:

Code
<pages>
  <page>
    Main menu
    <a href="#balance">Check Balance</a>
    <a href="#transfer">Transfer</a>
  </page>

  <page tag="balance">
    Your balance is $100.00
  </page>

  <page tag="transfer">
    Enter recipient number:
    <form action="/transfer">
      <entry kind="digits" var="recipient">
        <prompt>Phone number:</prompt>
      </entry>
    </form>
  </page>
</pages>

Current implementation note: Our LiberiaOrangeAdapterGrain currently generates single-page responses. Multi-page support could be leveraged for richer flows.

3.10 Includes & Redirects

Includes — embed content from another page:

Code
<page>
  Main content
  <include src="footer.xml"/>
</page>

Redirects — redirect to another URL without user interaction:

Code
<page>
  <redirect src="actual-page.xml"/>
</page>

3.11 Multi-Language Support

Cellcube supports multilingual content using <lang> blocks:

Code
<page>
  <lang>
    <en>Welcome to our service</en>
    <fr>Bienvenue sur notre service</fr>
  </lang>
  <a href="menu.xml">
    <lang>
      <en>Continue</en>
      <fr>Continuer</fr>
    </lang>
  </a>
</page>

Cellcube selects the appropriate language based on user preferences (configured per subscriber).

3.12 Plugin Functions

Cellcube provides server-side plugins accessible via special erl:// URLs:

Code
<!-- Plugin function (returns XML content) -->
<include src="erl://svc_core:redir_by_attribute?language&equal&en=#ok"/>

<!-- Plugin command (redirects session) -->
<redirect src="erl://svc_sms_ext:subst_sms_mo_init?Text&20001"/>

Note: These are internal Cellcube features. As an ESP, we do not use erl:// URLs — they are operator-managed.

3.13 Dynamic Content in Links

Links can contain dynamic session variables using dynerl:// format (reserved for local files, not available to ESPs via XML/HTTP interface):

• Session fields: $(msisdn.), $(imsi.), $(language.)
• Session variables: $(service.varname.separator)
• Date: $(date."%Y-%m-%d".local.)
• Lists: $(list.service.varname.[index].)

Note: Dynamic content via dynerl:// is NOT available over the HTTP interface for security reasons. Our platform receives session data via HTTP headers instead.

---

4. HTTP Interface Requirements (Cellcube → ESP)

4.1 Request Format

Cellcube sends HTTP requests to our platform:

Code
GET /index.xml HTTP/1.0
Host: tech231-ussd.example.com
User-MSISDN: 231881234567
User-Language: en
User-IMSI: 618030099991234
Handset-MaxSize: 182

Key characteristics:

• HTTP/1.0 or 1.1
• Methods: GET, HEAD, POST
• POST Content-Type: application/x-www-form-urlencoded
• POST charset: us-ascii, utf-8, or iso-8859 variant

4.2 Response Format

Our responses must comply with:

Requirement	Value
Content-Type	text/xml
Body	Strictly compliant with Cellcube DTD
Charset	us-ascii, iso-8859-1, or utf-8
Transfer-Encoding	7bit, 8bit, or chunked

Code
HTTP/1.0 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pages SYSTEM "cellflash-1.3.dtd">
<pages descr="Tech231 USSD">
  <page>
    Welcome to Tech231
    <a href="/menu/balance">Check Balance</a>
  </page>
</pages>

4.3 User Identity Headers

Cellcube forwards subscriber identity via HTTP headers:

Header	Example	Description
User-MSISDN	231881234567	Subscriber phone number
User-IMSI	618030099991234	SIM card identity
User-Language	en	Subscriber language preference
User-UID	90001234	Internal user ID
User-Subscription	prepaid	Subscription type
User-Identity	ton=international;npi=isdn;address=231881234567	Structured identity

Handset capability headers:

Header	Example	Description
Handset-Phase	2	USSD phase (1 or 2)
Handset-Input	alphanum	Input capability (digits, alpha, alphanum)
Handset-MaxSize	182	Max USSD message size in characters
Handset-IMEI	1234612123456	Device IMEI
Handset-TAC	12346	Type Allocation Code

Location headers (if available):

Header	Example	Description
Loc-VLR	231999990001	Visitor Location Register
Loc-Lat	6.3106	Latitude
Loc-Lon	-10.8047	Longitude
Loc-Country	lr	Country code
Loc-City	Monrovia	City

4.4 Session Management (Cookies)

Cellcube supports standard HTTP cookies for session management:

Code
# Cellcube forwards cookies we set:
Set-Cookie: session=abc123; path=/

# On subsequent requests:
Cookie: session=abc123

Current implementation: Our platform uses Orleans grain-based session management via IUSSDSessionGrain keyed by {tenantId}:{sessionId}. We currently rely on the DialogId (session ID) parameter rather than HTTP cookies.

4.5 Cache Control

Cellcube respects HTTP cache headers:

• Cache-Control: public — cacheable across all users (1-hour validity)
• Cache-Control: private — cached per-user for session duration
• Cache-Control: no-cache — always fetch fresh

Our responses should use Cache-Control: private or no-cache since USSD content is typically user-specific and session-dependent.

4.6 Quality of Service & Timeouts

Parameter	Typical Value	Description
Response timeout	5 seconds	Cellcube shows error if ESP doesn't reply in time
Max XML size	~10 KB	Recommended maximum XML document size
Max links per page	9	Recommended (depends on handset)
Max pages per document	~20	Recommended maximum
Max includes	Limited	Cellcube limits to prevent infinite loops
Max redirects	Configurable	pserver::max_xmlhttp_redirect

Critical: Our USSD processing pipeline must respond within 5 seconds to avoid Cellcube timeout errors. This includes Orleans grain activation, DSL execution, HTTP actions, and XML serialization.

4.7 Error Handling

HTTP error codes — Cellcube handles standard HTTP errors:

Status Code	Cellcube Behavior
2xx	Process response normally
3xx	Follow redirect (see 4.8)
4xx	Show configurable error to user
5xx	Show configurable error to user

Error notifications — Cellcube may POST error details to us if our XML is invalid:

Code
POST /cgi-bin/cellcube_reject HTTP/1.0
Content-Type: text/plain

Error: Invalid XML at line 5, column 12

Recommendation: We should implement a /cgi-bin/cellcube_reject endpoint to log and monitor Cellcube-reported XML errors.

4.8 HTTP Redirects

Cellcube follows standard 3xx redirects with a Location header:

Code
HTTP/1.1 301 Moved Permanently
Location: http://www.newhost.org/service.xml

Max redirect depth is configurable via pserver::max_xmlhttp_redirect.

4.9 Enhanced HTTP Redirect (Orange Money)

A special redirect mechanism exists for integration with local services like Orange Money:

Code
HTTP/1.1 301 Moved Permanently
Location: cellcube://orangemoney_validation
Content-Type: text/html
xmlhttp-merchantid: 1
xmlhttp-msisdn: +231881234567
xmlhttp-amount: 100
xmlhttp-servicename: TopUp
xmlhttp-result_url: http://our-server.com/result

The cellcube:// scheme redirects to a locally-configured Cellcube service (e.g., Orange Money validation). Parameters in HTTP headers are saved to the session and can be forwarded back to us.

Important for Orange Money integration: This is how we trigger payment flows from our USSD service. Our HTTP action responses can use this redirect pattern to invoke Orange Money billing.

4.10 Keep-Alive & Transport

• IPv4 required
• Connections initiated by Cellcube (pull model)
• Connection: Keep-Alive supported for persistent connections
• Cellcube may multiplex multiple user sessions on a single TCP connection
• Cellcube may load-balance requests from the same session across multiple connections
• HTTPS (SSL client authentication) supported

4.11 Traffic Shaping

Cellcube can rate-limit requests per ESP. Each ESP has a configurable maximum requests per second. This is operator-configured.

---

5. Mapping to Tech231 Platform Architecture

5.1 Our Role as ESP

Code
┌──────────────────────────────────────────────────────────────────────────────┐
│                        Tech231 Platform as ESP                               │
│                                                                              │
│  ┌──────────────────────────┐                                                │
│  │  Ussd.App                │ ◄── Cellcube sends HTTP requests here          │
│  │  /gateway/lr/orange      │     GET /gateway/lr/orange?msisdn=...&input=.. │
│  │                          │                                                │
│  │  GatewayEndpointHandlers │                                                │
│  └───────────┬──────────────┘                                                │
│              │                                                               │
│              ▼                                                               │
│  ┌──────────────────────────┐                                                │
│  │  Gateway Registry        │                                                │
│  │  IGatewayRegistryGrain   │ → Resolves "liberia-orange" adapter            │
│  └───────────┬──────────────┘                                                │
│              │                                                               │
│              ▼                                                               │
│  ┌──────────────────────────┐    ┌───────────────────────────┐               │
│  │  IUSSDSessionGrain       │──► │  ApplicationGrain          │               │
│  │  Session state machine   │    │  DSL definition storage    │               │
│  │  Input processing        │    └───────────────────────────┘               │
│  │  Navigation history      │                                                │
│  └───────────┬──────────────┘                                                │
│              │                                                               │
│              ▼                                                               │
│  ┌──────────────────────────┐                                                │
│  │  LiberiaOrangeAdapter    │ → Formats response as Cellcube XML             │
│  │  GrainType: liberia-orange│                                               │
│  │  Protocol: Cellcube XML  │                                                │
│  │  Char limit: 182         │                                                │
│  │  Encoding: UTF-8         │                                                │
│  └──────────────────────────┘                                                │
│              │                                                               │
│              ▼                                                               │
│  ┌──────────────────────────┐                                                │
│  │  HTTP Response            │                                               │
│  │  Content-Type: text/xml  │ ──► Cellcube receives and renders to handset   │
│  │  Body: <pages>...</pages>│                                                │
│  └──────────────────────────┘                                                │
└──────────────────────────────────────────────────────────────────────────────┘

5.2 Request Ingress Path

When Cellcube sends a request to our platform, this is the mapping:

Cellcube HTTP Header/Param	Tech231 Request Field	Notes
User-MSISDN	GatewayRequestInput.Msisdn	Bound from header, query, or body
Session ID (varies)	GatewayRequestInput.DialogId	May come as cookie or query param
User selection / form input	GatewayRequestInput.Input	The user's menu selection or text input
Service shortcode	GatewayRequestInput.ShortCode	e.g., *123#
Route: /gateway/lr/orange	Country=lr, TelcoNetwork=orange	Builds countryTelcoId = "liberia-orange"

Processing flow:

1. GatewayEndpointHandlers.GatewayGetRoute() receives the HTTP GET/POST
2. Builds countryTelcoId = "liberia-orange" from route params
3. Looks up adapter via IGatewayRegistryGrain
4. Resolves tenant from adapter metadata
5. Routes to IUSSDSessionGrain for DSL execution
6. Formats response via LiberiaOrangeAdapterGrain.FormatAsync()
7. Returns Cellcube-compliant XML

5.3 LiberiaOrangeAdapterGrain Implementation

The existing LiberiaOrangeAdapterGrain handles the Cellcube protocol:

Capabilities:

Property	Value
GrainType	liberia-orange
Character Limit	182
Encoding	UTF-8
Flow Format	CustomHeader (Freeflow)
Supports UDH	Yes
Supports Unicode	Yes
Max Options	9

XML Generation:

The adapter serializes the DSL menu output into Cellcube XML:

Code
// 1. Build Page with content and links
var page = new Page()
{
    Content = menuBody.Header,
    Nav = shouldContinue ? "default" : "end",
    Links = menuBody.MenuItems.Select((item, idx) => new Link
    {
        Href = $"/ussd/app/selection?selection={idx}",
        Text = item.Text
    }).ToList()
};

// 2. Wrap in Pages root element
var result = new Pages() { PageList = [page] };

// 3. Serialize with DTD declaration
writer.WriteDocTypeAsync("pages", null, "cellflash.dtd", null);
serializer.Serialize(writer, result, emptyNamespaces);

5.4 XML Serialization Models

Our existing C# models map to the Cellcube DTD:

Cellcube DTD Element	C# Model	Location
<pages>	Pages	Models/LiberiaOrange/Pages.cs
<page>	Page	Models/LiberiaOrange/Page.cs
<a>	Link	Models/LiberiaOrange/Link.cs
<form>	Form	Models/LiberiaOrange/Form.cs
<entry>	Entry	Models/LiberiaOrange/Entry.cs
<prompt>	Prompt	Models/LiberiaOrange/Prompt.cs

Page model attributes already implemented:

Code
public class Page
{
    [XmlText]      public string ContentXml { get; set; }    // Page text content
    [XmlAttribute("tag")]      public string? Tag { get; set; }
    [XmlAttribute("nav")]      public string? Nav { get; set; }        // "default"|"end"|"stop"
    [XmlAttribute("ismenu")]   public bool IsMenu { get; set; }
    [XmlAttribute("menutext")] public string? MenuText { get; set; }   // "notext" to hide
    [XmlAttribute("backtext")] public string? BackText { get; set; }   // "notext" to hide
    [XmlAttribute("helptext")] public string HelpText { get; set; }
    [XmlAttribute("hometext")] public string? HomeText { get; set; }
    [XmlElement("a")]          public List<Link> Links { get; set; }
    [XmlElement("form")]       public Form? Form { get; set; }
}

5.5 Flow Control Mapping

DSL Concept	Cellcube XML Mapping	Our Implementation
Continue session	<page nav="default">	MenuFlowControl.Continue → Nav="default"
End session	<page nav="end">	MenuFlowControl.Break → Nav="end"
Confirm (no shortcuts)	<page nav="stop">	Not yet mapped — potential enhancement
Hide Back button	<page backtext="notext">	Currently set to "notext" by default
Hide Menu button	<page menutext="notext">	Currently set to "notext" by default
Skip in history	<page hist="donthist">	Not yet mapped

---

6. Protocol Constraints & Limitations

Parameter	Absolute Max	Recommended Max
USSD message size	182 characters	182 characters
Number of links per page	Device dependent	9
XML document size	~10 KB	~5 KB
Pages per document	~50	~20
Includes per page	Limited	5
Cookie size	Limited	Per operator config
Response time	30 seconds	5 seconds

---

7. Implementation Gaps & Recommendations

Currently Implemented ✅

Feature	Status	Notes
XML document structure (<pages>, <page>)	✅	Full DTD-compliant output
Links as menu options (<a>)	✅	Auto-numbered by Cellcube
Forms for user input (<form>, <entry>)	✅	Model exists
Session termination (nav="end")	✅	Maps to MenuFlowControl.Break
UTF-8 encoding	✅	Primary encoding
182-char limit tracking	✅	CharacterLimit = 182
Content-Type: text/xml	✅	Set in GatewayResponse.HttpContentType
DOCTYPE declaration	✅	cellflash.dtd written by XmlWriter
Navigation label hiding	✅	backtext="notext", menutext="notext"
Line breaks (<br/>)	✅	Auto-converted from \n

Gaps / Recommended Enhancements ⚠️

Feature	Priority	Description	Effort
nav="stop" support	High	For confirmation pages — prevent shortcut bypass	Small
hist="donthist" support	Medium	Skip processing/redirect pages in back navigation	Small
Multi-page responses	Medium	Leverage tag attribute for richer flows	Medium
Cache-Control headers	Medium	Add private or no-cache to responses	Small
Error notification endpoint	Medium	/cgi-bin/cellcube_reject for XML error logging	Small
Orange Money redirect	High	Enhanced HTTP redirect with cellcube:// scheme	Medium
iso-8859-1 fallback	Low	Some older handsets may need ISO encoding	Small
User-Identity header parsing	Medium	Extract MSISDN/IMSI from Cellcube headers	Medium
Cookie-based session linking	Low	Alternative to query-param session ID	Medium
Volatile page support	Low	volatile="true" for real-time data	Small
Multi-language via <lang>	Low	Leverage Cellcube's built-in i18n	Large
Handset-MaxSize header parsing	Medium	Dynamic char limit from gateway instead of hardcoded 182	Small
key attribute on links	Low	Custom shortcut keys for options	Small
Include support (<include>)	Low	Compose responses from multiple sources	Medium

Recommended Priority Actions

1. Orange Money Integration — Implement the enhanced HTTP redirect pattern (cellcube://orangemoney_validation) to enable payment flows directly from USSD sessions.

2. nav="stop" for Confirmations — Map the DSL's confirmation/terminal patterns to nav="stop" to prevent users from accidentally skipping past payment confirmations.

3. Dynamic Handset-MaxSize — Parse the Handset-MaxSize header from Cellcube requests to dynamically set the character limit instead of hardcoding 182.

4. Error Notification Endpoint — Add a POST endpoint to receive and log Cellcube XML validation errors for debugging.

---

8. Quick Reference: HTTP Headers

Headers Sent by Cellcube (Request → ESP)

Code
# User Identity
User-MSISDN: 231881234567
User-IMSI: 618030099991234
User-Language: en
User-UID: 90001234
User-Subscription: prepaid
User-Identity: ton=international;npi=isdn;address=231881234567

# Handset
Handset-Phase: 2
Handset-Input: alphanum
Handset-MaxSize: 182
Handset-IMEI: 1234612123456

# Location (if available)
Loc-VLR: 231999990001
Loc-Lat: 6.3106
Loc-Lon: -10.8047
Loc-Country: lr

# Session
Cookie: session=abc123

# Standard HTTP
Host: our-server.example.com
Connection: Keep-Alive
Cache-Control: private

Headers Sent by ESP (Response → Cellcube)

Code
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Cache-Control: private, no-cache
Set-Cookie: session=abc123; path=/

# For Orange Money redirect:
HTTP/1.1 301 Moved Permanently
Location: cellcube://orangemoney_validation
xmlhttp-merchantid: 1
xmlhttp-msisdn: +231881234567
xmlhttp-amount: 100
xmlhttp-servicename: TopUp
xmlhttp-result_url: http://our-server/callback

---

9. Full XML Example

A complete valid Cellcube XML response from our platform:

Code
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pages SYSTEM "cellflash.dtd">
<pages descr="Tech231 Banking">
  <page>
    Welcome to T231 Banking<br/>
    <a href="/gateway/lr/orange?input=1&amp;session=sess123">Check Balance</a>
    <a href="/gateway/lr/orange?input=2&amp;session=sess123">Transfer Money</a>
    <a href="/gateway/lr/orange?input=3&amp;session=sess123">Buy Airtime</a>
    <a href="/gateway/lr/orange?input=4&amp;session=sess123">Mini Statement</a>
  </page>
</pages>

Cellcube renders as:

Code
Welcome to T231 Banking
1:Check Balance
2:Transfer Money
3:Buy Airtime
4:Mini Statement
0:Back 00:Menu

Terminal Response Example

Code
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pages SYSTEM "cellflash.dtd">
<pages>
  <page nav="end" backtext="notext" menutext="notext">
    Transfer Successful!<br/>
    Amount: $50.00<br/>
    To: 0881234567<br/>
    Ref: TXN-98765
  </page>
</pages>

Confirmation Page Example (with nav="stop")

Code
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE pages SYSTEM "cellflash.dtd">
<pages>
  <page nav="stop">
    Confirm transfer:<br/>
    Amount: $50.00<br/>
    To: 0881234567<br/>
    <a href="/gateway/lr/orange?input=1&amp;session=sess123">Confirm</a>
    <a href="/gateway/lr/orange?input=2&amp;session=sess123">Cancel</a>
  </page>
</pages>

---

See Also

• USSD Request Pipeline Architecture — End-to-end request flow documentation
• USSD DSL Reference — DSL syntax for building USSD applications
• Gateway Adapter Quick Reference — How to add/modify gateway adapters
• USSD Gateway Flow — Application resolution and routing