Communicate With OneSMS APIs In Your App
Integrate OneSMS service in your app and start to send SMS with more simple.
Introduction
The API we provide programmatic access to OneSMS features and data. In designing the API, our goal was to make it simple, intuitive, and predictable. The standards used in this API are widely accepted standards such as using POST to access the API and XML format for the returned data.
We use POST HTTP request instead of GET is because it has no restrictions on data length. Thus, the output can contain long sentences that returned by the API.
POST supports binary data type as well. Hence the possibilities of user uploading images to change their logo.
For security concern, POST is a little safer because the parameters are not stored in browser history and web server logs unlike GET.
By using POST, the URL will remain clean because the data will not be displayed in URL.
GET Method Send SMS
https://www.onesms.my/api/send.php?apiKey=[APIKEY]&recipients=[RECIPIENTS]&messageContent=[MESSAGE]&referenceID=[CUSTOMREFERENCEID]
| Parameters | Explanation |
|---|---|
| [APIKEY] | API Key. (Find your API key at www.OneSMS.my My Account > Settings) |
| [RECIPIENTS] |
Recipient mobile number. - Mobile number with country code. - Once recipient one request. - One recipient one request. - You can use semi-colon(;) to separate each recipient without space when sending multiple recipients. |
| [MESSAGE] |
Message body. - A single SMS may contain 160 characters, or 70 characters for Unicode. - Concatenated SMS may contains 156 characters, or 66 characters for Unicode. - All Malaysia mobile number will be minus 4 characters “RM0” at the beginning of each SMS content. - Maximum of 10 concatenated SMS. As per SKMM guidelines, you shall include price information at the beginning of each SMS. You shall use either “Free msg/RM0/Msj ini percuma” at the beginning of the SMS content. For more information, please read our Terms & Conditions. |
| [CUSTOMREFERENCEID] | An unique reference id from your system to avoid duplicate request. |
| [STATUS] | Show the status for send SMS (ok / error) |
| [MSGCODE] | Show code to represent particular status. |
| [REFERENCEID] | Your reference for any future enquiries. |
| [BALANCE] | Your account current balance. |
| [DATA] | Each recipient sending reference ID. |
Request and Response format
Encourage to use URL encode on the request link / url to converts reserved, unsafe, and non-ASCII characters in URLs to a format that is universally accepted and understood by all web browsers and servers. Paste it here and encode link
Please refer to here to know more about url encoding characters reference
Request
https://www.oneSMS.my/api/send.php?apiKey=[APIKEY]&recipients=[RECIPIENT]&messageContent=[MESSAGE]&referenceID=[CUSTOMREFERENCEID]
Encoded Request
https%3A%2F%2Fwww.oneSMS.my%2Fapi%2Fsend.php%3FapiKey%3D %5BAPIKEY%5D%26recipients%3D%5BRECIPIENT%5D%26messageContent%3D %5BMESSAGE%5D%26referenceID%3D%5BCUSTOMREFERENCEID%5D
Response
{"status":"[STATUS]","msgCode":"[MSGCODE]","statusMsg":"[ STATUSMSG]","referenceID":"[ REFERENCEID]"," balance":"[ BALANCE]", "data": "[DATA]" }
*Response array encoded with JSON
*Response array encoded with JSON
Example code for request and response
Request
Single recipient
https://www.oneSMS.my/api/send.php?apiKey=22f277843206d477d3cd4ae1c9220bc3&messageContent=Testing%123&recipients= 6010xxxxxxx&referenceID=ba63ht12opab6
Multiple recipients
https://www.oneSMS.my/api/send.php?apiKey=22f277843206d477d3cd4ae1c9220bc3&messageContent=Testing%123&recipients= 6010xxxxxxx;6012xxxxxxx&referenceID=iyr340hbc6ja0b
Encoded Request
Single recipient
https%3A%2F%2Fwww.oneSMS.my%2Fapi%2Fsend.php%3F apiKey%3D22f277843206d477d3cd4ae1c9220bc3%26messageContent%3D Testing%25123%26recipients%3D6010xxxxxxx%26referenceID%3Dba63ht12opab6
Multiple recipients
https%3A%2F%2Fwww.oneSMS.my%2Fapi%2Fsend.php%3F apiKey%3D22f277843206d477d3cd4ae1c9220bc3%26messageContent%3D Testing%25123%26recipients%3D6010xxxxxxx%3B6012xxxxxxx%26referenceID%3Diyr340hbc6ja0b
Response
Single recipient - Successful
{"status":"ok","msgCode":"E00001","statusMsg":"Completed successfully.","referenceID":["q5c502192aa869"],"balance":8901,"data":[{"recipients":"6010xxxxxxx","referenceID":"q5c502192aa869"}]}
Multiple recipients - Successful
{"status":"ok","msgCode":"E00001","statusMsg":"Completed successfully.","referenceID":["q5c5021c306a95","q5c5021c306ae8"],"balance":8901,"data":[{"recipients":"6010xxxxxxx","referenceID":"q5c5021c306a95"},{"recipients":"6012xxxxxxx","referenceID":"q5c5021c306ae8"}]}
Unsuccessful
{"status":"error","msgCode":"E00242","statusMsg":"invalid recipient(s).","invalidRecipients":["6010999999999"]}
*Response array encoded with JSON
*Response array encoded with JSON
Status Code List
| Status Code | Description |
|---|---|
| E00001 | Completed successfully. |
| E00081 | Account not active yet. Please contact our support. |
| E00242 | Invalid recipient(s). |
| E00243 | Please enter your message. |
| E00249 | Maximum 10 SMS per recipient(s). |
| E00248 | Please enter at least one recipient. |
| E00250 | Insufficient balance. |
| E00253 | Maximum 100 recipient(s). |
| E00359 | Invalid API Key. |
| E00366 | The message content contains international brand(s). |
| BE00035 | The message not allow to send without company name. Please contact our support to add your company name. |
| BE00036 | The message not allow to send without whitelisted. |
| BE00096 | Duplicated reference id found. |
| BE00128 | Completed successfully(low balance). |
OneSMS Add Template through API
-
:
URL: https://www.oneSMS.my/api/smsAddTemplate.php -
Variable should be passed in with format below>:
Sample Data In
{"apiKey ":"abc88888888acbde","email":"[email protected]","templateTitle":" AddTemplate02Jun2020","messageContent":"Hi, add template through api on 02 June 2020.","referenceId":"567890"}
| Param | Data Type | Description | Sample |
|---|---|---|---|
| apiKey | Varchar | API Key. (Find your API key at www.onesms.my My Account > Settings) | abc88888888acbde |
| Varchar | Email. (Find your API key at www.oneSMS.my My Account > Settings) | [email protected] | |
| templateTitle | Varchar | Template title to be add | AddTemplate02Jun2020 |
| messageContent | Text | Message content wanted to submit for whitelist | Hi, add template through api on 02 June 2020. |
| referenceId | Varchar | Reference ID to be return for you when status callback | 567890 |
-
To be more secure, only POST method is accepted, GET method will not be accepted.
** apiKey, email, templateTitle and messageContent is necessary to pass in, but referenceId is not compulsary. If referenceId is passed from your site, we will return the same referenceId when callback for template status.
** Add template through API will be consider as submitted.
Return submitted template status to client site
-
Perform steps below to allow callback status after we approved or rejected your template:
-
Pass your return URL to us
[your website URL]/[your file path]
For example: https://www.oneSMS.my/callback/receiveCallbackStatus.php
https://www.oneSMS.my => [website URL]
callback/receiveCallbackStatus.php => [file path] - Tick the checkbox name as "Enable SMS Add Template Status Callback" at settings -> SMS Template Status Through API Callback section
-
Pass your return URL to us
-
Details below will be returned:
Sample Data Return
{"action":"templateStatusCallback","actionCode":"E00101","status":"Approved"," messageContent":"Hi, add template through api on 02 June 2020.","referenceId":"567890"}
| Param | Data Type | Description | Sample |
|---|---|---|---|
| action | String | Return command | templateStatusCallback |
| actionCode | String | Return Code | E00101 |
| status | String | Template status | Approved |
| messageContent | String | Whitelisted message content | Hi, add template through api on 02 June 2020. |
| referenceId | String | Reference ID you passed to us when submit template | 567890 |
Response array encoded with JSON
GET Method Send SMS
https://www.oneSMS.my/api/getBalance.php?apiKey=[APIKEY]&email=[EMAIL]
| Parameters | Explanation |
|---|---|
| [APIKEY] | API Key. (Find your API key at www.OneSMS.my My Account > Settings) |
| [EMAIL] | Email. (Find your API key at www.oneSMS.my My Account > Settings) |
Request and Response format
Request
https://www.oneSMS.my/api/getBalance.php?apiKey=[APIKEY]&email=[EMAIL]
Response
{"status":"[STATUS]","msgCode":"[MSGCODE]","statusMsg":"[ STATUSMSG]"," balance":"[ BALANCE]"}
*Response array encoded with JSON
*Response array encoded with JSON
Example code for request and response
https://www.oneSMS.my/api/getBalance.php?apiKey=e0323drabst6728725da3dvdcra78910a&email=abcd1234@gmail.com
Response
{"status":"ok","msgCode":"E00001","statusMsg":"Completed successfully.","balance":"120.22"}
*Response array encoded with JSON
*Response array encoded with JSON
Ready to grow your business with SMS Marketing?
No. 40, Jalan Eco Santuari 8/2A Eco Santuari, 42500 Telok Panglima Garang, Selangor
+6019-319-2000
Follow Us
