HTTP API

HTTP Application Programming Interface

(API)

Version : 1.2

Date : 12 March 2013

©Web 123 Sdn Bhd, 2013 - Confidential and Proprietary

This document is copyrighted. No part of this document may in any form or by any means be
reproduced, stored in a retrieval system or transmitted without prior written permission from Web
123 Sdn Bhd

Confidential and Proprietary 1

 HTTP API
Contents

1. Document History 3

2. Abbreviation 3

3. Introduction 4

4. System Requirement 4

5. API List

5.1 Send MT message 5

5.2 Check transaction status 7

5.3 Check credit balance 8

5.4 DN URL Transaction status 9

6. Appendix 10

Confidential and Proprietary 2

 HTTP API
1.0 Document History
Date Document Version Document Description /
Changes to document
1/8/08 1.0 Document Creation
5/5/09 1.1 Update on error code
12/3/2013 1.2 Update on DN URL Transaction Status

2.0 Abbreviation
Abbreviation Full Description and explanation
CP Content Provider – Customers connecting to onewaysms gateway
HTTP Hyper Text Transport Protocol – Protocol used for CP to communicate
with onewaysms gateway
MSISDN Mobile Station International ISDN number
SMS Short Messaging Service
MT Mobile Terminating
MT URL onewaysms.com.my’s sms platform MT URL (URL for Content Provider
to interface with onewaysms sms gateway to send out MT)
DN Delivery Notification. This is the notification from the Telco to indicate
the status of the SMS

Confidential and Proprietary 3

 HTTP API
3.0 Introduction
This document is intended to be used by developers, technical architect, designer who wish to
develop applications or connect their platforms to interface with onewaysms’s sms gateway
through HTTP connectivity.

4.0 System Requirement

1. Content Provider may use any web based programming language that supports HTTP
protocol
2. Onewaysms gateway will be listening on port 10001 or port 80

Confidential and Proprietary 4

 HTTP API

5.0 API List

onewaysms gateway expose 4 API for CP to utilize
1. Send MT message
2. Check transaction status
3. Check credit balance
4. DN URL Transaction status

Guide to integrate with onewaysms gateway

5.1 Send MT message

1.0 Send MT Message Onewaysms
Content
gateway 3.0 Deliver SMS
Provider
2.0 Receive result
in body

Diagram 1: Send MT Message

To send MT, CP would need to call MT URL with the appended parameter. (MT URL can
be obtain from API section in your account)

Below are the HTTP parameter that are required to be appended to MT URL
Parameter Data Description
Name Format
apiusername String Username for your API (can be obtain under API
section once you have log into your account)
Note : API username is different from your web
username)
apipassword String Password for your API (can be obtain under API
section once you have log into your account)
Note : API username is different from your web
username)
mobileno String Phone number of recipient. Phone number
must include country code.
Example : 60121234567
10 mobile numbers can be included in this field
separated with commas (,).
Eg. 60197654321,60121234567
senderid String Refer to sender. Field can take up to 11
alphanumeric characters.
Note : Sender ID is no longer relevant in Malaysia.
Confidential and Proprietary 5
 HTTP API
You may enter “INFO” as the Sender ID. It will
always display as a 5 digit number starting with 6.
For example, 6XXXX
languagetype String Indicated the type of sms sent:
“1” – Normal Text message (160 characters as 1
MT)
“2” – Unicode Text message (70 characters as 1
MT)

For languagetype 2, refer to Appendix 1 for

example on conversion

message String Content of the SMS.

Example, if languagetype set to 1, and message

has content with length 200, 2 SMS will be sent.

We can combine SMS. We need 7 characters to

combine. Below are the character count
1 SMS = 160 characters
2 SMS = 306 characters (14 characters for joining)
3 SMS = 459 characters (21 characters for joining)

We recommend sending up to maximum 3 SMS

long

Once onewaysms gateway receives a MT request, it will return a HTTP 200 response to
CP
• If the value is other than 200, then it is a failed request.
• If the value is 200, CP is required to extract the message body for the result
• If the result is a negative value, some of the MT parameters are invalid (refer
below for details)
• If the result is a positive value, it means our gateway successfully receive it. The
result is the MT ID. (If you would like to check on transaction status, you would
need to store this ID)

Below are the result that will return on the message body
Result Description
>0 Positive value – Success
If multiple numbers are sent in the same request, result will display
multiple MT ID, For example, 200806150001,200806150002
-100 apipassname or apipassword is invalid

Confidential and Proprietary 6

 HTTP API
-200 senderid parameter is invalid
-300 mobileno parameter is invalid
-400 languagetype is invalid
-500 Invalid characters in message
-600 Insufficient credit balance

Refer to Appendix 2 on URL example on sending MT

5.2 Check transaction status (optional to implement)

Content 1.0 check transaction status Onewaysms
Provider gateway
2.0 Receive result
in body

Diagram 2: Check transaction status

Once bulk MT is delivered to subscriber, Content Provider may check transaction status
by calling bulk check URL (Bulk check URL can be obtain from API section in your
account)

Below are the HTTP parameter that are required to be appended to MT URL
Parameter Data Description
Name Format
mtid String MT ID received from onewaysms gateway when
sending MT previously

Below are the result that will return on the message body
Result Description
0 Success receive on mobile handset
100 Message delivered to Telco
-100 mtid invalid / not found
-200 Message sending fail

Refer to Appendix 3 on URL example on check transaction status

Confidential and Proprietary 7

 HTTP API
5.3 Check Credit Balance (optional to implement)
1.0 Check credit balance Onewaysms
Content
Provider gateway
2.0 Receive result
in body

Diagram 3 : Check credit balance

Content Provider can check credit by calling check balance URL . (Check balance URL can
be obtain from API section in your account)
Parameter Data Description
Name Format
apiusername String Username for your API (can be obtain under API
section once you have log into your account)
Note : API username is different from your web
username)
apipassword String Password for your API (can be obtain under API
section once you have log into your account)
Note : API username is different from your web
username)

Below are the result that will return on the message body
Result Description
0 or positive SMS Credit balance in your account
value
-100 apipassname or apipassword is invalid

Refer to Appendix 4 on URL example on check credit balance

Confidential and Proprietary 8

 HTTP API
5.4 DN URL Transaction Status (optional to implement)
1.0 Return Status in DN URL Content
Onewaysms
gateway Provider
2.0 Receive HTTP 200

Diagram 4 : DN URL Transaction Status

One Way SMS will update the status of the SMS Transaction by calling Content
Provider’s DN URL. (Content Provider can set the DN URL from your own account)
Parameter Data Description
Name Format
mtid String MT ID received from onewaysms gateway when
sending MT previously
status int 1 = success
-1 = fail

Refer to Appendix 5 on URL example on check credit balance

Confidential and Proprietary 9

 HTTP API
6.0 Appendix
Appendix 1

For send with languagetype 2, you would need to convert the message to hexadecimal value

Below are examples on the conversion

Letter “a” : hexadecimal value is 0061
人
Chinese character “ ” : hexadecimal value is 4EBA
Note : each character must be converted to 4 hexadecimal value. Using example “a”, some
software will convert to 61, you would need to append “00” to make it “0061”

Appendix 2

Example sending SMS with languagetype 1

http://mturl?apiusername=123&apipassword=123&mobileno=60121234567&senderid=onewa
ysms&languagetype=1&message=hello

Example sending SMS with languagetype 2

http://mturl?apiusername=123&apipassword=123&mobileno=60121234567&senderid=onewa
ysms&languagetype=2&message=00680065006C006C006F

Note : hello converted to hexadecimal is 00680065006C006C006F

Appendix 3

Example calling check transaction status URL

http://checkstatusurl?mtid=808010000123

Appendix 4

Example calling check credit balance

http://checkcrediturl?apiusername=123&apipassword=123

Appendix 5

Example of DN URL calling

http://dnurl?mtid=808010000123&status=1

Confidential and Proprietary 10