Developers
API_TOKEN can be generated under user configuration on at desk.sms.com.na
1.1 SUBMIT SMS USING HTTP GET METHOD
https://desk.sms.com.na/api/http/?key=API_TOKEN&action=sendsms&to=LIST_OF_MOBILE_NUMBERS_SEPERATED_BY_COMMA&msg=YOUR_SMS_MESSAGE
When successful the system will return a plain text string starting with “success” followed by the unique message id, mobile number and status message for each of the recipients separated by a bar (|) and the values separated by a colon (:) e.g. success|999999:+264819992999:pending|999991:+2648199929889:pending
If an error has occurred the system will return a plain text string starting with
“error” followed by the error message e.g error - Message not provided
1.2 CHECK STATUS USING HTTP GET METHOD
Checking the status of a submitted message
https://desk.sms.com.na/api/http/?key= API_TOKEN &action=status& msgid_list = LIST_OF_SUBMITTED_SMS_IDs_SEPERATED_BY_COMMA
The system will return plain text string with status details for each SMS_ID
separated by a bar(|) and the values separated by a colon (:) as
SMS_ID:MOBILE:STATUS:STATUS_DATE:DELIVERY_STATUS: DELIVERY_STATUS_DATE
e.g
999999:+264819992999:success:12344567:DELIVERED:123458
Here is a C# code snippet that you can use:
1.3 EMAIL 2 SMS
Simply send email as mobile@sms.com.na eg 0812182326@sms.com.na from an email address of a user registered under your account.
If you want to receive incoming SMS on your website we will forward them via HTTP GET with the following parameters appended to the URL of your receiving web-page:
- SecurityKey (String) - A security key used by you to validate our http call
- IncomingSmsID (Long Integer)-The unique message id assigned by our database to the incoming message.
- TimeStamp (Long Integer) -Date and TimeStamp in UNIX format of the incoming message.
- Sender (String)- The Mobile number of the sender.
- Recipient (Int)-The short-code number that received the SMS.
- Message (String)- The Message: https://[your url]?securitykey= SecurityKey&incomingsmsid=IncomingSmsID
×tamp =TimeStamp&sender=Sender &recipient= Recipient&message=
Message
You can download a CSV string of SMS received on the system. The system will
https://desk.sms.com.na/api/http/?key= API_TOKEN &action=incoming& msgid_list = LIST_OF_SUBMITTED_SMS_IDs_SEPERATED_BY_COMMA
Option parameters:
rows - the number of rows you want to retain. The default is 10 and the maximum value is 10 000
dt - Date and Time from which you want to download the SMSs. The format must be yyyyMMddHHmm. By default
this is backdated by 24 hours from the moment of
querying. The date cannot be beyond 3 months from
the time of querying and cannot be in the future.
status - 1 = New (Unread) SMSs
2 = SMSs already fetched or read
format - CSV (default) ; JSON
encode - false or 0 (default)
true or 1 will encode the response as Base64 String
The XML post toward the WASP providd URL EndPoint will have the following format:
<ussd>
<msisdn>M</msisdn>
<sessionid>S</sessionid>
<type>T</type>
<msg>MSG</msg>
</ussd>
Where:
| Parameter | Description |
| M | The MSISDN of the subscriber making the request in International format, i.e. 27829991234. |
| S | Is the session ID. TruRoute-USSD generates a new id for every new session. |
| T | The request type. See the table below for more detail |
| MSG |
The actual text entered by the subscriber. This will be either: -the service code entered to start the session -the text entered by the user in response to a message from the WASP |
Request types:
| Identifier | Value "T" | Description |
| REQUEST | 1 | New USSD request string from the mobile. |
| RESPONSE | 2 | Response from the mobile in an already existing session |
| RELEASE | 3 | Set by TruRoute-USSD to indicate that the user has cancelled the current session. |
| TIMEOUT | 4 | The session timed out. This indicates that the user has failed to respond within a pre-set timeout value. |
| CHARGE | 10 | A premium rate charge (as requested by the WASP) failed. The reason for the failure is noted in the MSG part f the XML document. |
The WASP must respond with an XML-formatted document indicating what should be done.
<ussd>
<type>T</type>
<msg>MSG</msg>
<premium>
<cost>C</cost>
<ref>R</ref>
</premium>
</ussd>
Where:
| Parameter | Description |
| T | The request type. See the table below for more detail |
| MSG | The actual text that should be sent to the subscriber. Please also see the REDIRECT response type below. |
| C | The cost that should be charged to the subscriber by the WASP. The cost that should be charged to the subscriber by the WASP. |
| R | A unique reference supplied by the WASP for this charging transaction. |
Request types:
| Identifier | Value "T" | Description |
| REQUEST | 2 | Response to the mobile keeping the session open. |
| RESPONSE | 3 | Response to the mobile closing the session. |
| RELEASE | 5 | Redirect the response to another WASP. The "msg" field will contain the complete USSD service code to which TruRoute-USSD should redirect the USSD session. |
Where the MSISDN, Session ID, Type and message fields are the same as those listed for the XML document in the previous section.