Differences between TMS2 and TMS3 protocols

This page details the differences in the way TMS3 natively accesses third-party applications via HTTP. Note that TMS3 has full "legacy mode" support for TMS2 applications for backwards-compatibility, however the TMS2 protocol has some irregularities and inconsistencies and should not be used for new applications.

General information

• USSD callbacks can be done using either a HTTP GET or a HTTP POST method. For HTTP GET, parameters are always URL-encoded (even if TMS3 is using TMS2 legacy mode). For HTTP POST, parameters are always form-encoded.
• The GET/POST parameter ordering in TMS2 legacy mode is consistent, whereas it is random in TMS3.
• All parameter names in TMS3 are lowercase with underscores joining separate words, e.g. "my_tms_parameter". TMS2's parameter names did not follow any standardized naming scheme.
• Note that in some cases TMS3 provides extra callback parameters that do not have an equivalent in TMS3.
• TMS3 will ensure that any HTTP GET/POST parameters that are specified directly in the callback URL are encoded properly, whereas TMS2 did not implement this correctly,
  e.g. if a USSD application's callback URL is specified as:
  
  http://www.example.com?my_variable=123
  
  An example resulting callback URL in TMS3 would be:
  
  http://www.example.com?my_variable=123&msisdn=12345&message=*120*1%23&session_id=123&service_type=FIRST&network_id=1
  
  ...whereas TMS2 would incorrectly encode this as:
  
  http://www.example.com?my_variable=123?msisdn=12345&message=*120*1%23&sessionid=123&serviceType=FIRST&networkid=1
  
  Notice the incorrect second ? character in the TMS2 callback URL.

USSD callback parameters

The table below specifies the parameters sent by TMS3 along with their equivalents in TMS2.

SMS request and callback parameters

SMS callbacks are sent via either a GET with parameters or POST containing XML. The difference between the parameters and XML in TMS and TMS3 are given below.

MT SMS request parameters

In order to send a SMS via TMS3, you need to send a HTTP POST request, whereas TMS2 required a HTTP GET request. The number of parameters that the request could contain has been significantly reduced.

TMS2 would respond to a "MT SMS" request differently, depending on the value of the bulk parameter. TMS2 would respond with a reference (the format is the same as for a status update, given below), if bulk was set to n or with Status : Accepted Request. An error would be returned if there was a problem with the request

TMS3 will always respond the same way. The format of the response is given in the API reference for send.

MT SMS Status update

GET

POST

<delivery_report>
  <msisdn>27820000222</msisdn>
  <status>DELIVRD</status>
  <delivery_date>2011-08-17 13:45:38.497 UTC</delivery_date>
  <tms_session_id>733629987</tms_session_id>
  <network_id>0</network_id>
  <batch_id>1108171545388673093</batch_id>
</delivery_report>
                                        

<Reference xmlns="http://ha.flashmedia.co.za/schema/TMS2">
    <refRecord>
        <fmgsession>-1422640526</fmgsession>
        <messageid>-1422640526</messageid>
    </refRecord>
</Reference>
                                        

MT SMS Delivery report

GET

POST

<delivery_report>
  <msisdn>27820000222</msisdn>
  <status>DELIVRD</status>
  <delivery_date>2011-08-17 13:45:38.497 UTC</delivery_date>
  <tms_session_id>733629987</tms_session_id>
  <network_id>0</network_id>
  <batch_id>1108171545388673093</batch_id>
</delivery_report>
                                        

<DeliveryReport xmlns="http://ha.flashmedia.co.za/schema/TMS2">
    <DeliveryReports>
        <status>DELIVRD</status>
        <messageid>-1422640526</messageid>
        <deliverydate>2011-08-18T09:53:00.000Z</deliverydate>
        <networkid>2</networkid>
        <msisdn>27785046872</msisdn>
        <fmgsession>-1422640526</fmgsession>
    </DeliveryReports>
</DeliveryReport>
                                        

MO SMS

GET

POST

<mobile_originated>
  <source>4477665544</source>
  <destination>33050</destination>
  <message>Hello from SMPPSim</message>
  <tms_session_id>1606028024</tms_session_id>
  <network_id>1</network_id>
</mobile_originated>
                                        

<MainMessage xmlns="http://ha.flashmedia.co.za/schema/TMS2">
    <MainMessages>
        <msisdn>27823981477</msisdn>
        <message>Tms3</message>
        <shortcode>33055</shortcode>
        <fmgsession>1850839097</fmgsession>
        <networkid>1</networkid>
    </MainMessages>
</MainMessage>