USSD Lua Service
Introduction
The ProcessUssdLuaService is a service for initiating Lua scripts running within the LogicApp.
The ProcessUssdLuaService receives a ProcessUnstructuredSSRequest
message from one or more instances of the
SigtranApp which is
configured to receive TCAP messages from an external client.
The ProcessUssdLuaService communicates with the SigtranApp using the TCAP-… messages.

Configuring ProcessUssdLuaService
The ProcessUssdLuaService is configured within a LogicApp.
<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
...
<applications>
...
<application name="Logic" module="LogicApp">
<include>
<lib>../apps/logic/lib</lib>
</include>
<parameters>
...
</parameters>
<config>
<services>
<service module="SigtranApp::ProcessUssdLuaService" libs="../apps/sigtran/lib">
<menu_timeout>10</menu_timeout>
<timeout_message>Custom Timeout</timeout_message>
<success_message>Custom Success</success_message>
<triggers>
<trigger dest_ssn="120" ussd_string_prefix="*123#" script_name="123"/>
<trigger dest_ssn="120" destination="333" script_name="333"/>
<trigger dest_ssn="120" ussd_string_prefix="*444#" script_name="444"/>
<trigger dest_ssn="120" ussd_string_prefix="*666#" script_name="666"/>
<trigger dest_ssn="120" destination="777" script_name="777"/>
</triggers>
</service>
</services>
<agents>
...
</agents>
</config>
</application>
...
</application>
...
</n2svcd>
Under normal installation, the following service
attributes apply:
Parameter Name | Type | XML Type | Description |
---|---|---|---|
module
|
String | Attribute |
[Required] The module name containing the Lua Service code: SigtranApp::ProcessUssdLuaService
|
libs
|
String | Element |
Location of the module for ProcessUssdLuaService.(Default: ../apps/sigtran/lib )
|
script_subdir
|
String | Attribute | An optional subdirectory for scripts used by this service. |
dcs_language
|
Integer | Element |
The default ussdDataCodingScheme_language .If not present, a codec-specified default is applied. |
menu_timeout
|
Integer | Element | The default time (in seconds) after which the script will resume if no menu response is received. |
timeout_message
|
String | Element | The message which will be returned to the subscriber if the USSD operation times out. |
error_message
|
String | Element |
The message which will be returned to the subscriber if an unhandled error occurs in then Lua script. The internal script error will be written to the application log, but will not be sent to the subscriber. |
success_message
|
String | Element |
The message which will be returned to the subscriber if the Lua script concludes successfully but
returns a nil final result.
|
.triggers
|
Array | Element |
Array of trigger elements specifying Lua scripts to run for USSD Inbound Transactions.
|
.trigger
|
Object | Element | Provisions a Lua script to run for a USSD Inbound Transaction for a destination/source party. |
Script Trigger Rules
Each USSD Incall trigger rule defines the name of a script which is ready to handle an inbound USSD Transaction.
Note that destination and source addresses may contain hex digits A-F, and the
matching is for destination_prefix
and source_prefix
is case-insensitive.
However, the string matching for ussd_string_prefix
is case-sensitive.
Each trigger
Object in the config
.triggers
Array is configured as follows.
Parameter Name | Type | XML Type | Description |
---|---|---|---|
ssn
|
1 -255
|
Attribute |
This trigger applies for only USSD Transactions to this exact SCCP subsystem number. (Default = Trigger applies to all SCCP subsystem numbers). |
ussd_string_prefix
|
String | Attribute |
This trigger applies for only USSD ProcessUnstructuredSSRequest with content beginning with this sub-string. (Default = Trigger applies to all ProcessUnstructuredSSRequest). |
destination
|
Hex Digits | Attribute |
This trigger applies for only USSD ProcessUnstructuredSSRequest to this exact destination party. (Default = Trigger applies to all ProcessUnstructuredSSRequest). |
destination_prefix
|
Hex Digits | Attribute |
This trigger applies for only USSD ProcessUnstructuredSSRequest to destination parties starting with this prefix. (Default = Trigger applies to all ProcessUnstructuredSSRequest). |
source
|
Hex Digits | Attribute |
This trigger applies for only USSD ProcessUnstructuredSSRequest from this exact source party. (Default = Trigger applies to all ProcessUnstructuredSSRequest). |
source_prefix
|
Integer | Attribute |
This trigger applies for only USSD ProcessUnstructuredSSRequest from source parties starting with this prefix. (Default = Trigger applies to all ProcessUnstructuredSSRequest). |
script_name
|
String | Attribute |
The name of the Lua script to load (excluding the ".lua" suffix).
The script should reside in the directory configured for the LogicApp's lua_script_dir ,
or in the specified subdirectory if script_subdir is configured for this service library.
|
Script Selection (USSD Transaction Request)
The Lua Script selection to execute for a USSD ProcessUnstructuredSSRequest takes into consideration the received content of the inbound TCAP_BEGIN transaction and/or the MAP content and/or the SCCP addressing information.
The destination address for matching is:
- The MAP_OPEN Destination Reference Digits.
The source address for matching is the first value found in:
- The ProcessUnstructuredSSRequest MSISDN, or
- The MAP_OPEN Origination Reference Digits.
The Process USSD Lua Service will iterate the configured trigger
entries in the sequence
in which they are configured and find the first trigger which matches the parameters of the
received message.
Refer to the LogicApp configuration for more information on directories, library paths, and script caching parameters.
Script Entry Parameters (USSD Request)
The Lua script must be a Lua chunk which returns an n2svcd.handler
, such as the following:
local n2svcd = require "n2.n2svcd"
local ussd = require "n2.n2svcd.ussd"
-- The args contain the content of the ProcessUnstructuredSSRequest sent by the HLR.
local handler = function (args)
-- This sends UnstructuredSSRequest and expects a UnstructuredSSRequestResult.
local input = ussd.menu ("1. Add-ons\n2. Packages\n3. Account Services\n4. Other Services", 2)
if (type (input) == "nil") then
return "No input provided. Session over."
end
-- This sends UnstructuredSSNotify within the session. No response is required.
ussd.notify ("You chose option " .. input .. " thanks.")
-- This closes the session by sending ProcessUnstructuredSSRequestResult.
return "We'll send an SMS with your usage details."
end
return n2svcd.handler (handler)
The handler will be executed with a single ussd
entry parameter which is an object with the
following attributes:
Attribute | Type | Description |
---|---|---|
.ussd_string
|
String |
The USSD string "sent" by the handset. This is a copy of .process_ussd.ussdString_text .
|
.msisdn
|
Integer |
The MSISDN source, being either the MSISDN digits from the ProcessUnstructuredSSRequest
operation, or the Origination-Reference Digits from the MAP-Open .This is the source address used for the trigger matching.This is a copy of .process_ussd.msisdn_digits or .map_open.origination_reference_digits .
|
.process_ussd
|
Object |
The decoded attributes of the ProcessUnstructuredSSRequest operation. Some of these
attributes may be optional. Site-specific protocol variants may add additional parameters
not documented here.
|
.ussdString
|
Binary | The raw encoded bytes of the USSD message content. |
.ussdString_text
|
String |
The decoded text of the ussdString in ASCII or Unicode.
|
.msisdn
|
Binary | The MSISDN (raw bytes) encded as MAP Address String. |
.msisdn_digits
|
HEX String |
The decoded digits of the MSISDN address.
|
.msisdn_noa
|
Integer |
The decoded Nature Of Address of the MSISDN address.
|
.msisdn_npi
|
Integer |
The decoded Numbering Plan Indicator of the MSISDN address.
|
.ussdDataCodingScheme
|
Binary | The USSD Data Coding Scheme (raw bytes) encded as USSD Call Broadcast Data Scheme. |
.ussdDataCodingScheme_encoding
|
Integer |
The decoded encoding of the ussdDataCodingScheme compound field.
|
.ussdDataCodingScheme_group
|
Integer |
The decoded group of the ussdDataCodingScheme compound field.
|
.ussdDataCodingScheme_is_compressed
|
0 /1
|
The decoded is_compressed of the ussdDataCodingScheme compound field.
|
.ussdDataCodingScheme_language
|
Integer |
The decoded language of the ussdDataCodingScheme compound field.
|
.map_open
|
Object | The decoded attributes of the MAP-Open element within the TCAP's MAP Dialogue PDU. Some of these attributes may be optional. Site-specific protocol variants may add additional parameters not documented here. |
.destination_reference
|
Binary | The Destination Reference (raw bytes) encded as MAP Address String. |
.destination_reference_digits
|
HEX String | The decoded digits of the Destination Reference address. |
.destination_reference_noa
|
Integer | The decoded Nature Of Address of the Destination Reference address. |
.destination_reference_npi
|
Integer | The decoded Numbering Plan Indicator of the Origination Reference address. |
.origination_reference
|
Binary | The Origination Reference (raw bytes) encded as MAP Address String. |
.origination_reference_digits
|
HEX String | The decoded digits of the Origination Reference address. |
.origination_reference_noa
|
Integer | The decoded Nature Of Address of the Origination Reference address. |
.origination_reference_npi
|
Integer | The decoded Numbering Plan Indicator of the Origination Reference address. |
Script Return Parameters (USSD Response)
The Lua script is responsible for determing the contents of the ProcessUnstructuredSSRequestResult
which will be sent back to the subscriber at the conclusion of the session.
The simplest way to do this is by the return value given back to the service at the end of script execution.
For full control over the USSD response, the script return value may be a response
object with the following attributes:
Field | Type | Description |
---|---|---|
response
|
Object | Container for the USSD response parameters we are to send. |
.ussdString
|
Binary |
The encoded bytes for the USSD String content. You will generally not specify this value, the service will encode it for you. |
.ussdString_text
|
String |
The user string in ASCII for Unicode that you wish to be encoded. (Default = None) |
.ussdDataCodingScheme_group
|
Integer |
The encoding group associated with the string encoding. (Default = 0 )
|
.ussdDataCodingScheme_language
|
Integer |
The encoding language associated with the string encoding. (Default = service dcs_language or codec-determined default)
|
.ussdDataCodingScheme_is_compressed
|
Integer |
The compression flag associated with the string encoding. (Default = 0 )
|
.ussdDataCodingScheme_message_class
|
Integer |
The encoding message class associated with the string encoding. (Default = 0 )
|
.ussdDataCodingScheme_encoding
|
Integer |
The encoding type associated with the string encoding. (Default = 0 )
|
Alternatively, the script may return a string. This is the same as specifying .ussdString_text
=
(the given simple string) with all other attributes not specified.
Alternatively, the script may return nil
in which case the configured default success_message
string will be used with all other attributes not specified.
Example (returning a Table USSD Response):
local n2svcd = require "n2.n2svcd"
local handler = function (ussd)
return ({ ussdString_text = "Bienvenue a la service", ussdDataCodingScheme_language = 3 })
end
return n2svcd.handler (handler)
Alternatively, a script may return a simple string instead of a Table.
Example (returning a String USSD Response):
local n2svcd = require "n2.n2svcd"
local handler = function (ussd)
return "Welcome to the service"
end
return n2svcd.handler (handler)
This is a shorthand for ussdString_text
= (Text Message) with all other values set to defaults.
Alternatively, a script may return nil
.
Example (returning the default success message):
local n2svcd = require "n2.n2svcd"
local handler = function (ussd)
return nil
end
return n2svcd.handler (handler)
In this case, the default-configured success_message
for the service will be returned.
The ProcessUssdLuaService API
The Process USSD Service API can be loaded as follows.
local ussd_api = require "n2.n2svcd.ussd"
It is not necessary to load the Process USSD Service API if you are only using the simple response mechanism described above. It is only required if you wish to use any of the extended features described below.
.response
When a Lua Script needs to perform extended processing, it may wish to send an early USSD
response before the script completes. This can be done with the response
method on the
USSD API.
This method will send a ProcessUnstructuredSSRequestResult
within a TCAP_END. The USSD
transaction is over. Subsequent calls to response
, notify
, or menu
are not permitted,
and will generate a runtime script error.
The response
method takes a single response
parameter.
Parameter | Type | Description |
---|---|---|
response
|
Object or String | A simple "text/plain" string, or an Object with the same structure as the returned object described under "Script Return Parameters". |
The response
method returns true
.
[Fragment] Example Early Response specifying Language:
...
ussd_api.response ({ ussdString_text = "Bienvenue a la service", ussdDataCodingScheme_language = 3 })
[post-processing logic after USSD transaction is terminated]
...
[Fragment] Example Early Response with default Language:
...
ussd_api.response ("Welcome to the service")
[post-processing logic after USSD transaction is terminated]
...
[Fragment] Example Early Response with default Message:
...
ussd_api.response ()
[post-processing logic after USSD transaction is terminated]
...
.notify
As part of the interaction, the Lua script may wish to send intermediate UnstructuredSSNotify
messages to the subscriber. There is no response or confirmation for these messages.
The notify
method on the USSD API will perform this function.
After calling the notify
message, the USSD transaction is still in progress. Calls may
still be made to notify
, menu
, or response
.
The notify
method takes a single notify
parameter.
Parameter | Type | Description |
---|---|---|
notify
|
Object or String | A simple "text/plain" string, or an Object with the same structure as the returned object described under "Script Return Parameters". |
The notify
method returns true
.
[Fragment] Example Notification specifying Language:
...
ussd_api.notify ({ ussdString_text = "En cours. Patientez SVP.", ussdDataCodingScheme_language = 3 })
...
[additional logic including further USSD interactions]
...
[Fragment] Example Notification with default Language:
...
ussd_api.notify ("Working... please wait.")
...
[additional logic including further USSD interactions]
...
.menu
As part of the interaction, the Lua script may wish to send intermediate UnstructuredSSRequest
messages to the subscriber. The subscriber will be prompted to enter additional input which
is returned to the service in a UnstructuredSSRequestResult
message.
The script will suspend until the subscriber input is received, or until the configurable time value expires.
The menu
method on the USSD API will perform this function.
After calling the menu
message, the USSD transaction is still in progress. Calls may
still be made to notify
, menu
, or response
.
The menu
method takes the following parameters.
Parameter | Type | Description |
---|---|---|
menu
|
Object or String | A simple "text/plain" string, or an Object with the same structure as the returned object described under "Script Return Parameters". |
timeout
|
Integer |
The timeout in seconds before the script resumes processing without input. (Default = Service configured menu_timeout value).
|
The menu
method returns the text string which was supplied by the subscriber in response
to the menu prompt.
[Fragment] Example Menu with custom Timeout:
...
local input = ussd_api.menu ("1. Account Balance\n2. My Usage\n3. Recharge History\n4. Recharge\n0. Back", 20)
if (type (input) == "nil") then
return "No input received to menu. Session terminated."
end
if (input == "1") then
...
end
...