USSD

Overview

Introduction

CLX’s USSD service helps enterprises reduce their cost of messaging by leveraging on USSD technology without increasing the complexity of their messaging solution. All messages are submitted to our platform according to SMS standards through SMPP/SMPPS or HTTP/HTTPS interfaces, removing the need for USSD-specific integration. Our service makes USSD messaging just as easy as SMS messaging.Virtually all mobile handsets and a vast majority of the mobile networks worldwide support USSD messages. With an appearance identical to Flash SMS, USSD Flash messages appear at the very front of the screen on any device. Since USSD Flash messages are not saved in any inbox, this service is especially suitable for applications such as one-time passwords, alerts and reminders.

../_images/ussd_mob11-196x390.png

USSD Flash, SMS/USSD Fusion and USSD Menus

To complement our USSD Flash service we have created a SMS/USSD Fusion service that seamlessly combines the cost efficiency of USSD with the extensive global coverage of CLX’s Outbound SMS service. All messages are submitted to one single gateway and to the networks covered by our USSD service, messages will be delivered as a USSD Flash. For the networks not covered by our USSD service, messages are delivered as SMS. The coverage & price list will tell you in advance whether messages to a certain network will be delivered as USSD or SMS to give you full control over the per message cost.In addition to being a cost effective complement to SMS, USSD also enables for a new type of interactive mobile services: USSD Menus. USSD Menus let you create mobile application-like services without any need for the subscriber to download any app. The messages within the menus can be menu options and responses (i.e. 1,2 or 3) or text at the same length as an SMS (160 characters). By routing back the handset responses in real time to your platform we give you complete control of the message flow as well as the possibility to add real time data to the interaction.

../_images/ussd_mob21-195x390.png

USSD Flash via SMPP or HTTP

How To Connect

The IP addresses and port number to connect to our USSD services are identical to the IP addresses and port numbers used for our SMS Services. Please find them listed in the tables below. Your username and password is available in the CAD (Client Account Details) document provided to you by your account manager.

Server - SMPP Host:Port
Primary SMPP Server 93.158.78.4:3600
Backup SMPP Server 195.84.167.34:3600
Server - HTTP Host:Port
Primary HTTP Server 93.158.78.4:3800
Backup HTTP Server 195.84.167.34:3800
Primary HTTPS Server 93.158.78.4:3801
Backup HTTPS Server 195.84.167.34:3801

How To Send Messages

Submitting a USSD message to our platform is identical to submitting an SMS. As no originator is displayed on the handset when receiving USSD messages, you can set the originator and TON/NPI parameters to any valid value of your choice.

Examples

USSD Submit - SMPP

Parameter Example
command_id SUBMIT_SM
sequence_number 2
service_type 0
source_addr_ton ALPHANUMERIC
source_addr_npi UNKNOWN
source_addr Test
dest_addr_ton 1
dest_addr_npi 1
dest_addr 46706160585
esm_class 0
protocol_id 0
priority_flag 0
validity_period 2014-02-19 09:24:42 UTC
registered_delivery 0
replace_if_present_flag 0
data_coding 0
sm_default_message_id 0
sm_length 12
short_message Test message

USSD Submit - HTTP

http://93.158.78.4:3800/sendsms?username=CompanyName_USSDgw0&password=pass
&from=CLX&to=46700123456&text=Test+message

SMS/USSD Fusion via SMPP or HTTP

How To Connect

The IP addresses and port number to connect to our SMS/USSD Fusion service are identical to the IP addresses and port numbers used for our SMS Services. Please find them listed in the tables below. Your username and password is available in the CAD (Client Account Details) document provided to you by your account manager.

Server - SMPP Host:Port
Primary SMPP Server 93.158.78.4:3600
Backup SMPP Server 195.84.167.34:3600
Server - HTTP Host:Port
Primary HTTP Server 93.158.78.4:3800
Backup HTTP Server 195.84.167.34:3800
Primary HTTPS Server 93.158.78.4:3801
Backup HTTPS Server 195.84.167.34:3801

How To Send Messages

Submitting a message using our SMS/USSD Fusion service is identical to submitting a message using our Outbound SMS service. Please make sure originator and TON/NPI values are set correctly as these will be used for the messages sent to destination networks not accepting USSD messages (message will be delivered as SMS).

Examples

SMS/USSD Fusion Submit - SMPP

Parameter Example
command_id SUBMIT_SM
sequence_number 2
service_type 0
source_addr_ton ALPHANUMERIC
source_addr_npi UNKNOWN
source_addr Test
dest_addr_ton 1
dest_addr_npi 1
dest_addr 46706160585
esm_class 0
protocol_id 0
priority_flag 0
validity_period 2014-02-19 09:24:42 UTC
registered_delivery 0
replace_if_present_flag 0
data_coding 0
sm_default_message_id 0
sm_length 12
short_message Test message

SMS/USSD Fusion Submit - HTTP

http://93.158.78.4:3800/sendsms?username=CompanyName_USSDgw0&password=pass
&from=CLX&to=46700123456&text=Test+message

USSD Menus via SMPP or HTTP

How To Connect

The IP addresses and port number to connect to our USSD services are identical to the IP addresses and port numbers used for our SMS Services. Please find them listed in the tables below. Your username and password is available in the CAD (Client Account Details) document provided to you by your account manager.

Server - SMPP Host:Port
Primary SMPP Server 93.158.78.4:3600
Backup SMPP Server 195.84.167.34:3600
Server - HTTP Host:Port
Primary HTTP Server 93.158.78.4:3800
Backup HTTP Server 195.84.167.34:3800
Primary HTTPS Server 93.158.78.4:3801
Backup HTTPS Server 195.84.167.34:3801

How To Send Menus

The communication flow for USSD Menus is divided in to two separate sessions: Initiation of the USSD Menu and Messages within the USSD Menu.

../_images/ussd_api11-390x84.png

Initiating a USSD Menu is done by submitting a standard USSD Flash message to the CLX platform with one important difference: you put your predefined USSD Menu Keyword as message content. When the Keyword is set as message content the message will not be delivered to the destination MSISDN - instead we will open a separate HTTP session back to your platform. Once the separate HTTP session is established you can send the first message within the USSD menu. To be able to open the HTTP session back to your platform we need the URL to which you want us to connect.

USSD Menu initiation can be sent using SMPP or HTTP. However the protocol for the messages within the USSD Menu will always be XML over HTTP. USSD Menu responses from the subscriber will be routed back to your platform in real time and based on the response you can choose which message will be sent next within the menu. Below you will find a sequence diagram illustrating the complete message flow of sending a USSD Menu.

../_images/ussd_api4.png

Examples

USSD Menu Initiation - SMPP

Important: Message content must be your predefined Keyword.

Parameter Example
command_id SUBMIT_SM
sequence_number 2
service_type 0
source_addr_ton ALPHANUMERIC
source_addr_npi UNKNOWN
source_addr Test
dest_addr_ton 1
dest_addr_npi 1
dest_addr 46706160585
esm_class 0
protocol_id 0
priority_flag 0
validity_period 2014-02-19 09:24:42 UTC
registered_delivery 0
replace_if_present_flag 0
data_coding 0
sm_default_message_id 0
sm_length 28
short_message CompanyName_USSDgw0_y3jJFTcr

USSD Menu Initiation - HTTP

Important: Message content must be your predefined Keyword.
  <span class="documentationcode">http://93.158.78.4:3800/sendsms?username=CompanyName_USSDgw0&password=pass
 &from=CLX&to=46700123456&text=CompanyName_USSDgw0_y3jJFTcr</span>

USSD Menu message, possible for subscriber to reply - XML over HTTP

<?xml version="1.0"?>
  <umsprot version="1"><prompt_req reqid="0" sessionid="5304ea94df428">Welcome to the
  USSD demo! Please enter your name:</prompt_req></umsprot>

USSD Menu message, not possible for subscriber to reply (USSD Flash within Menu) - XML over HTTP

<?xml version="1.0"?>
  <umsprot version="1"><display_req reqid="4" sessionid="5304ea94df428">Thanks for
  answering our survey, have a nice day!</display_req></umsprot>