USSD Gateway API Documentation

Overview
Interfaces
Message Types
Operations
Procedures
Protocol Details
Examples

Overview

The SigWay USSD Gateway is a signaling gateway that bridges SS7/M3UA networks with application servers. It provides multiple interfaces for applications to interact with USSD (Unstructured Supplementary Service Data) and ATI (Any Time Interrogation) services.

Key Features

Multiple Interface Support: TCP/XML, HTTP MO, and HTTP MT
Bidirectional Communication: SS7-initiated and app-initiated sessions
Session Management: Automatic dialog ID allocation and tracking
Rate Limiting: Configurable per-MSISDN rate limiting
Shortcode Filtering: Register for specific USSD shortcodes
ATI Support: Subscriber location queries

Architecture

SS7/M3UA Network <--> SigWay Gateway <--> Applications
                            |
                      [TCP/XML | HTTP MO | HTTP MT]

Interfaces

TCP/XML Interface

The TCP/XML interface provides a persistent TCP connection for bidirectional XML-based communication.

Connection

Protocol: TCP
Default Port: 9090 (configurable)
Framing: Two protocols supported:
- Length-prefixed (default): 4-byte little-endian length header + XML payload
- Delimiter-based: XML payload terminated by 0xFF 0x00 0x00 0x00

Connection Lifecycle

Connect: Application establishes TCP connection to gateway
Hello: Application sends registration message with optional shortcode
Communication: Exchange XML messages
Keep-Alive: Ping/Pong messages for connection health
Disconnect: Connection closed (graceful or timeout)

Hello Message (Registration)

Applications must send a hello message upon connection to register:

<siggw>
  <msg type="hello">
    <ussd_shortcode_request v="*123#"/>
  </msg>
</siggw>

Shortcode Filter: If provided, app only receives messages for that shortcode
No Shortcode: If omitted, app receives all messages
Multiple Apps: Multiple apps can connect; gateway routes to all eligible apps

Ping/Pong (Keep-Alive)

Ping (app → gateway):

<siggw>
  <msg type="ping"></msg>
</siggw>

Pong (gateway → app):

<siggw>
  <msg type="pong"></msg>
</siggw>

Message Format

All USSD messages use the following XML structure:

<siggw>
  <msg type="begin|continue|end|abort">
    <stack id="0"/>
    <user id="<app_id>"/>
    <dialog id="<dialog_id>"/>
    <context v="<context_hex>"/>
    <component type="invoke|return_l" id="<component_id>" op="<operation>">
      <param name="ussd_string" v="<hex_encoded_text>"/>
      <param name="msisdn" number="<msisdn>" nai="1" npi="1"/>
      <param name="data_coding_scheme" v="15"/>
    </component>
    <user_info>
      <object_identifier v="04000001010101"/>
      <map op="open|accept">
        <param name="destination_reference" number="<imsi>" nai="1" npi="1"/>
        <param name="origination_reference" number="<msisdn>" nai="1" npi="1"/>
      </map>
    </user_info>
  </msg>
</siggw>

Dialog ID Ranges

SS7-Initiated Sessions: Gateway assigns dialog IDs 32768-65535
App-Initiated Sessions: App provides dialog IDs 0-32767
Dialog ID Consistency: Within a session, the same dialog ID is used throughout

HTTP MO (Mobile Originated) Interface

HTTP MO is used when the gateway needs to send messages to applications via HTTP GET requests.

Configuration

Base URL: Configured in config.json (http.mo.base_url)
Timeout: Configurable (default: 30 seconds)
Method: HTTP GET
Response: Synchronous response expected

Request Format

Gateway sends HTTP GET requests to the configured base URL with query parameters:

GET <base_url>?transactionID=0x<hex>&dialogId=<id>&number=<msisdn>&text=<text>&status=<status>

Parameters:

transactionID: 32-bit transaction ID in hex format (e.g., 0x00001234)
dialogId: 16-bit dialog ID (decimal)
number: MSISDN (subscriber phone number)
text: USSD text payload (plain text)
status: Message status - "begin", "continue", or "end"

Example:

GET http://app.example.com/service.php?transactionID=0x00001234&dialogId=32768&number=1234567890&text=Hello&status=begin

Response Format

Application must respond with HTTP 200 OK and a response body containing:

Format: <control_char><text>

Control Characters:

0: End message with GSM7 encoding
1: Continue message with GSM7 encoding
2: End message with UCS2 encoding
3: Continue message with UCS2 encoding

GSM7 Encoding:

Text is sent as-is (plain ASCII/GSM7 characters)

UCS2 Encoding:

Text is hex-encoded UTF-16BE (big-endian)
Example: "Hello" → 00480065006C006C006F

Examples:

GSM7 End:

0Thank you

UCS2 Continue:

300480065006C006C006F

Transaction Management

Gateway creates a transaction ID for each session
Transaction ID persists for the entire session (begin → continue → end)
Transaction is cleaned up when session ends or times out

When HTTP MO is Used

TCP/XML interface is disabled, OR
No TCP/XML applications are registered for the shortcode
Gateway automatically falls back to HTTP MO if TCP/XML is unavailable

HTTP MT (Mobile Terminated) Interface

HTTP MT allows applications to initiate USSD sessions by sending HTTP requests to the gateway.

Configuration

Listen Port: Configured in config.json (http.mt.listen_port)
Endpoints: /begin and /notify
Method: HTTP GET

/begin Endpoint

Initiates a dialog-oriented USSD session.

Request:

GET /begin?dialogId=<id>&number=<msisdn>&text=<text>&text2=<ucs2_hex>

Parameters:

dialogId: 16-bit dialog ID (0-32767, provided by application)
number: MSISDN (destination phone number)
text: GSM7-encoded text (optional, use if GSM7)
text2: UCS2 hex-encoded text (optional, use if UCS2)
Either text or text2 must be provided

Response:

HTTP 200 OK with body "OK"
Gateway routes message to SS7
Application should expect responses via TCP/XML or HTTP MO (depending on configuration)

Example:

GET /begin?dialogId=1000&number=1234567890&text=Hello%20World

/notify Endpoint

Sends a notification-only message (no dialog expected).

Request:

GET /notify?dialogId=<id>&number=<msisdn>&text=<text>&text2=<ucs2_hex>

Parameters: Same as /begin

Response:

HTTP 200 OK with body "OK"
No response expected from SS7

Example:

GET /notify?dialogId=2000&number=1234567890&text=Notification

Text Encoding

GSM7 (text parameter):

Plain ASCII/GSM7 characters
URL-encoded if needed

UCS2 (text2 parameter):

Hex-encoded UTF-16BE
Example: "Hello" → 00480065006C006C006F

Message Types

Begin

Initiates a new USSD dialog.

SS7 → App:

Gateway receives Begin from SS7
Routes to eligible applications
Dialog ID assigned by gateway (32768-65535)

App → SS7:

Application sends Begin
Dialog ID provided by app (0-32767)
Gateway routes to SS7

Continue

Continues an existing dialog.

SS7 → App:

Gateway receives Continue from SS7
Routes to apps subscribed to the dialog
Uses same dialog ID as Begin

App → SS7:

Application sends Continue
Must use same dialog ID as Begin
Gateway routes to SS7 using stored SS7 transaction ID

End

Terminates a dialog.

SS7 → App:

Gateway receives End from SS7
Routes to apps subscribed to the dialog
Session is closed after delivery

App → SS7:

Application sends End
Must use same dialog ID as Begin
Session is closed after delivery
Optional: Include MAP accept in user_info

Abort

Aborts a dialog (error condition).

SS7 → App:

Gateway receives abort from SS7
Sends abort XML to subscribed apps
Session is closed

Format:

<siggw>
  <msg type="abort">
    <user id="<app_id>"/>
    <dialog id="<dialog_id>"/>
  </msg>
</siggw>

Operations

process_ussd_request (Operation Code 59)

Standard USSD request processing.

Context: 04000001001302 (USSD context)

Parameters:

ussd_string: Hex-encoded USSD text
msisdn: Subscriber MSISDN
data_coding_scheme: Encoding scheme (typically 15)

ussd_request (Operation Code 60)

USSD request operation.

Context: 04000001001302 (USSD context)

Parameters: Same as process_ussd_request

ussd_notify / unstructured_ss_notify (Operation Code 61)

Notification-only USSD message (no response expected).

Context: 04000001001302 (USSD context)

Parameters: Same as process_ussd_request

any_time_interrogation (Operation Code 71)

ATI operation for subscriber location queries.

Context: 04000001001D03 (ATI context)

Request Parameters:

msisdn: Subscriber MSISDN (in subscriber_identity nested param)
gsm_scf_address: GSM SCF address (optional)

Response Parameters:

subscriber_info:
- location_information:
  - age_of_location_information: Age in seconds
  - geographical_information: Hex-encoded geographical data
  - vlr_number: VLR number
- cell_glob_id_or_lai:
  - cell_glob_id_or_serv_area_fixed_length:
    - mcc: Mobile Country Code
    - mnc: Mobile Network Code
    - lca: Location Area Code (LAC)
    - cid: Cell ID (CI)

Procedures

SS7-Initiated Sessions

Flow:

SS7 Begin → Gateway
- Gateway receives Begin from SS7
- Extracts shortcode from USSD text
- Creates session with dialog ID (32768-65535)
- Finds eligible apps (shortcode match or no filter)
Gateway → App(s)
- Sends Begin XML to all eligible apps
- Apps receive dialog ID and can respond
App → Gateway (Continue/End)
- App sends Continue/End with same dialog ID
- Gateway routes to SS7 using stored SS7 transaction ID
SS7 → Gateway (Continue/End)
- Gateway receives Continue/End from SS7
- Routes to apps subscribed to dialog
- On End, session is closed

Example XML Flow:

SS7 Begin → App:

<siggw>
  <msg type="begin">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="32768"/>
    <context v="04000001001302"/>
    <component type="invoke" id="1" op="process_ussd_request">
      <param name="data_coding_scheme" v="15"/>
      <param name="ussd_string" v="48656C6C6F"/>
      <param name="msisdn" number="1234567890" nai="1" npi="1"/>
    </component>
    <user_info>
      <object_identifier v="04000001010101"/>
      <map op="open">
        <param name="destination_reference" number="123456789012345" nai="1" npi="1"/>
        <param name="origination_reference" number="1234567890" nai="1" npi="1"/>
      </map>
    </user_info>
  </msg>
</siggw>

App Continue → SS7:

<siggw>
  <msg type="continue">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="32768"/>
    <context v="04000001001302"/>
    <component type="invoke" id="2" op="process_ussd_request">
      <param name="data_coding_scheme" v="15"/>
      <param name="ussd_string" v="576F726C64"/>
    </component>
  </msg>
</siggw>

App-Initiated Sessions

Flow:

App Begin → Gateway
- App sends Begin with dialog ID (0-32767)
- Gateway creates session using app's dialog ID
- Routes to SS7 using dialog ID as transaction ID
SS7 → Gateway (Continue/End)
- Gateway receives Continue/End from SS7
- Stores SS7 transaction ID (OTID)
- Routes to app using app's dialog ID
App → Gateway (Continue/End)
- App sends Continue/End with same dialog ID
- Gateway routes to SS7 using stored SS7 transaction ID

Example XML Flow:

App Begin → SS7:

<siggw>
  <msg type="begin">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="1000"/>
    <context v="04000001001302"/>
    <component type="invoke" id="1" op="ussd_request">
      <param name="data_coding_scheme" v="15"/>
      <param name="ussd_string" v="48656C6C6F"/>
      <param name="msisdn" number="1234567890" nai="1" npi="1"/>
    </component>
  </msg>
</siggw>

ATI (Any Time Interrogation)

Flow:

App ATI Request → Gateway
- App sends Begin with ATI operation
- Includes MSISDN and optional GSM SCF address
- Gateway routes to SS7
SS7 ATI Response → Gateway
- Gateway receives End with ATI response
- Parses location information
- Routes to app as End message with ATI data

Example XML:

App ATI Request:

<siggw>
  <msg type="begin">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="2000"/>
    <context v="04000001001D03"/>
    <component type="invoke" id="1" op="any_time_interrogation">
      <param name="subscriber_identity">
        <param name="msisdn" number="1234567890" nai="1" npi="1"/>
      </param>
      <param name="gsm_scf_address" number="1234567890" nai="1" npi="1"/>
    </component>
  </msg>
</siggw>

SS7 ATI Response → App:

<siggw>
  <msg type="end">
    <user id="1"/>
    <dialog id="2000"/>
    <context v="04000001001D03"/>
    <component type="return_l" id="1" op="any_time_interrogation">
      <param name="subscriber_info">
        <param name="location_information">
          <param name="age_of_location_information" v="30"/>
          <param name="geographical_information" v="01020304"/>
          <param name="vlr_number" number="9876543210" nai="1" npi="1"/>
        </param>
        <param name="cell_glob_id_or_lai">
          <param name="cell_glob_id_or_serv_area_fixed_length" mcc="250" mnc="01" lca="1234" cid="5678"/>
        </param>
      </param>
    </component>
  </msg>
</siggw>

Protocol Details

Dialog ID Management

SS7-Initiated: Gateway assigns 32768-65535
App-Initiated: App provides 0-32767
Consistency: Same dialog ID used throughout session
Session Lookup: Gateway uses dialog ID to find session context

Component ID

Application Managed: Applications provide component ID in XML for all message types (Begin, Continue, End)
Gateway Pass-Through: Gateway passes through component IDs from app XML without storage, validation, or defaults
App Responsibility: Application decides which component ID to use for each message, including End messages
No Gateway Management: Gateway does not store, track, or validate component IDs

Text Encoding

Hex Encoding (XML):

USSD text is hex-encoded in XML
Example: "Hello" → 48656C6C6F

GSM7 vs UCS2:

GSM7: Standard ASCII/GSM7 character set
UCS2: UTF-16BE, hex-encoded
Gateway auto-detects encoding needs

User Info (MAP Open/Accept)

MAP Open (SS7-initiated Begin):

Contains destination_reference (IMSI)
Contains origination_reference (MSISDN or origination reference)

MAP Accept (App End with accept):

App can include <user_info><map op="accept"> in End message
Indicates dialog acceptance

Session Timeout

Default: 300 seconds (configurable)
Behavior: Session closed if no activity
Abort: Gateway sends abort to SS7 and apps on timeout

Rate Limiting

Per-MSISDN: Configurable requests per minute
Burst Size: Allowed burst requests
Action: Abort sent to SS7 if limit exceeded

Shortcode Extraction

Gateway extracts shortcode from USSD text (e.g., *123#)
Used to route to apps registered for that shortcode
Apps without shortcode filter receive all messages

Examples

Example 1: SS7-Initiated USSD Session (TCP/XML)

1. SS7 sends Begin:

Shortcode: *123#
MSISDN: 1234567890
Text: "Hello"

2. Gateway → App (XML):

<siggw>
  <msg type="begin">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="32768"/>
    <context v="04000001001302"/>
    <component type="invoke" id="1" op="process_ussd_request">
      <param name="data_coding_scheme" v="15"/>
      <param name="ussd_string" v="48656C6C6F"/>
      <param name="msisdn" number="1234567890" nai="1" npi="1"/>
    </component>
    <user_info>
      <object_identifier v="04000001010101"/>
      <map op="open">
        <param name="destination_reference" number="123456789012345" nai="1" npi="1"/>
        <param name="origination_reference" number="1234567890" nai="1" npi="1"/>
      </map>
    </user_info>
  </msg>
</siggw>

3. App responds with Continue:

<siggw>
  <msg type="continue">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="32768"/>
    <context v="04000001001302"/>
    <component type="invoke" id="2" op="process_ussd_request">
      <param name="data_coding_scheme" v="15"/>
      <param name="ussd_string" v="576F726C64"/>
    </component>
  </msg>
</siggw>

4. SS7 sends Continue:

Text: "World"

5. Gateway → App (XML):

<siggw>
  <msg type="continue">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="32768"/>
    <context v="04000001001302"/>
    <component type="return_l" id="2" op="process_ussd_request">
      <param name="data_coding_scheme" v="15"/>
      <param name="ussd_string" v="576F726C64"/>
    </component>
  </msg>
</siggw>

6. App sends End:

<siggw>
  <msg type="end">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="32768"/>
    <context v="04000001001302"/>
    <component type="invoke" id="3" op="process_ussd_request">
      <param name="data_coding_scheme" v="15"/>
      <param name="ussd_string" v="5468616E6B20796F75"/>
    </component>
  </msg>
</siggw>

Example 2: HTTP MO Session

1. SS7 sends Begin:

Shortcode: *456#
MSISDN: 9876543210
Text: "Balance"

2. Gateway → App (HTTP GET):

GET http://app.example.com/service.php?transactionID=0x00001234&dialogId=32769&number=9876543210&text=Balance&status=begin

3. App responds:

HTTP 200 OK
Body: "1Your balance is $100"

(Continue with GSM7 encoding)

4. Gateway → SS7:

Continue: "Your balance is $100"

5. SS7 sends End:

Text: "Thank you"

6. Gateway → App (HTTP GET):

GET http://app.example.com/service.php?transactionID=0x00001234&dialogId=32769&number=9876543210&text=Thank%20you&status=end

7. App responds:

HTTP 200 OK
Body: "0"

(End with GSM7, empty text)

Example 3: HTTP MT Session

1. App sends Begin (HTTP GET):

GET /begin?dialogId=5000&number=1112223333&text=Hello%20World

2. Gateway → SS7:

Begin: Dialog ID 5000, MSISDN 1112223333, Text "Hello World"

3. SS7 responds with Continue:

Text: "Response"

4. Gateway → App (via TCP/XML or HTTP MO):

If TCP/XML: Sends XML Continue
If HTTP MO: Sends HTTP GET with status=continue

Example 4: ATI Query

1. App sends ATI Request (XML):

<siggw>
  <msg type="begin">
    <stack id="0"/>
    <user id="1"/>
    <dialog id="3000"/>
    <context v="04000001001D03"/>
    <component type="invoke" id="1" op="any_time_interrogation">
      <param name="subscriber_identity">
        <param name="msisdn" number="1234567890" nai="1" npi="1"/>
      </param>
    </component>
  </msg>
</siggw>

2. SS7 responds with ATI data:

MCC: 250
MNC: 01
LAC: 1234
CI: 5678
VLR: 9876543210
Age: 30 seconds

3. Gateway → App (XML End):

<siggw>
  <msg type="end">
    <user id="1"/>
    <dialog id="3000"/>
    <context v="04000001001D03"/>
    <component type="return_l" id="1" op="any_time_interrogation">
      <param name="subscriber_info">
        <param name="location_information">
          <param name="age_of_location_information" v="30"/>
          <param name="vlr_number" number="9876543210" nai="1" npi="1"/>
        </param>
        <param name="cell_glob_id_or_lai">
          <param name="cell_glob_id_or_serv_area_fixed_length" mcc="250" mnc="01" lca="1234" cid="5678"/>
        </param>
      </param>
    </component>
  </msg>
</siggw>

Error Handling

Connection Errors

TCP/XML: Connection closed, app must reconnect
HTTP MO: Gateway retries or sends abort to SS7
HTTP MT: Returns HTTP error status

Invalid Messages

Malformed XML: Message ignored, logged
Invalid Dialog ID: Session not found, abort sent
Missing Parameters: Error returned to sender

Timeouts

Session Timeout: Session closed, abort sent
HTTP Timeout: Abort sent to SS7
Connection Timeout: Connection closed

Best Practices

Dialog ID Management: Use consistent dialog IDs within sessions
Component IDs: Applications manage component IDs themselves - gateway passes through whatever ID the app provides
Text Encoding: Use GSM7 when possible, UCS2 for special characters
Error Handling: Always handle abort messages
Connection Management: Implement ping/pong for TCP/XML connections
Shortcode Registration: Register specific shortcodes to reduce unnecessary traffic
Session Cleanup: Properly close sessions with End messages

Configuration Reference

See config.json.example for complete configuration options:

TCP/XML: tcp_xml.enabled, tcp_xml.listen_port
HTTP MO: http.mo.enabled, http.mo.base_url, http.mo.timeout_sec
HTTP MT: http.mt.enabled, http.mt.listen_port
Session: ussd.session_timeout_sec
Rate Limiting: rate_limiting.enabled, rate_limiting.per_minute, rate_limiting.burst_size

Support

For issues or questions, refer to the gateway logs:

Application Log: ussd-gateway.log (default)
Traffic Log: sigwayTraffic.log (if enabled)

USSD Gateway API

USSD Gateway API Documentation

Table of Contents

Overview

Key Features

Architecture

Interfaces

TCP/XML Interface

Connection

Connection Lifecycle

Hello Message (Registration)

Ping/Pong (Keep-Alive)

Message Format

Dialog ID Ranges

HTTP MO (Mobile Originated) Interface

Configuration

Request Format

Response Format

Transaction Management

When HTTP MO is Used

HTTP MT (Mobile Terminated) Interface

Configuration

/begin Endpoint

/notify Endpoint

Text Encoding

Message Types

Begin

Continue

End

Abort

Operations

process_ussd_request (Operation Code 59)

ussd_request (Operation Code 60)

ussd_notify / unstructured_ss_notify (Operation Code 61)

any_time_interrogation (Operation Code 71)

Procedures

SS7-Initiated Sessions

App-Initiated Sessions

ATI (Any Time Interrogation)

Protocol Details

Dialog ID Management

Component ID

Text Encoding

User Info (MAP Open/Accept)

Session Timeout

Rate Limiting

Shortcode Extraction

Examples

Example 1: SS7-Initiated USSD Session (TCP/XML)

Example 2: HTTP MO Session

Example 3: HTTP MT Session

Example 4: ATI Query

Error Handling

Connection Errors

Invalid Messages

Timeouts

Best Practices

Configuration Reference

Support