NUSASMS SMS API ARCHITECTURE

HTTP Plain

The URL for SMS API used to send messages using HTTP GET is:

Primary access point:

 https://api.nusasms.com/api/v3/sendsms/plain

SMS API Parameter specifications

URL Query String Parameters

Examples: Send plain SMS (Output XML)

https://api.nusasms.com/api/v3/sendsms/plain?user=user&password=password&SMSText=Hello%20NusaSMS!&GSM=628*********

OTP SMS

Untuk pesan yang bersifat OTP (One-Time Password), diwajibkan untuk menambahkan parameter "otp=Y" pada 'request'

Examples: Send plain OTP SMS (Output XML)

 https://api.nusasms.com/api/v3/sendsms/plain?user=user&password=password&SMSText=Hello%20NusaSMS!&GSM=628********&otp=Y

Examples:

1.Send plain SMS (Output JSON)

https://api.nusasms.com/api/v3/sendsms/plain?user=user&password=password&SMSText=Hello%20NusaSMS!&GSM=628*********&output=json

Results Example

1. Success Result Sample:

XML

<?xml version="1.0" encoding="UTF-8"?>
<results>
     <result>
          <status>0</status>
          <messageid>175041319203754627</messageid>
          <destination>6285100803380</destination>
     </result>
</results>

JSON

{"results":[{"status":"0","messageid":"175041319203754627","destination":"6285100803380"}]}

2. Wrong User/Password

XML

<?xml version="1.0" encoding="UTF-8"?>
<results>
     <result>
          <status>-5</status>
          <messageid></messageid>
          <destination>6285100803380</destination>
     </result>
</results>

JSON

{"results":[{"status":"-5","messageid":"","destination":"6285100803380"}]}

3. Missing Destination Number

XML

<?xml version="1.0" encoding="UTF-8"?> 
  <results> 
     <result> 
       <status>-13</status> 
       <messageid></messageid> 
       <destination>085100803380</destination> 
    </result>
</results>

JSON

{"results":[{"status":"-13","messageid":"","destination":"6285100803380"}]}

2.Send plain OTP SMS (Output JSON)

https://api.nusasms.com/api/v3/sendsms/plain?user=user&password=password&SMSText=Kode%20OTP%20anda%20xxxxxx&GSM=628********&otp=Y&output=json

Results Example

1. Success Result Sample:

XML

<?xml version="1.0" encoding="UTF-8"?>
<results>
     <result>
          <status>0</status>
          <messageid>175041319203754627</messageid>
          <destination>6285100803380</destination>
     </result>
</results>

JSON

{"results":[{"status":"0","messageid":"175041319203754627","destination":"6285100803380"}]}

Send SMS Using Group Recipients

https://api.nusasms.com/api/v3/sendsms/group?user=user&password=password&SMSText=Hello%20NusaSMS!&group=Example

Note: group parameter in this url is the group name (containing one or more contacts to send the sms to). You create group in https://app.nusasms.com using your account that reside in [Utilities -> address book] menu.

Results Example:

1.Success Result Sample:

XML

<?xml version="1.0" encoding="UTF-8"?>
<results>
     <result>
          <status>0</status>
          <campaign_name>Group-Api-Campaign-cf27252-5101</campaign_name>
          <group>Example</group>
     </result>
</results>

JSON

{"results":[{"status":"0","campaign_name":"Group-Api-Campaign-cf27252-5101","group":"Example"}]}

2.Group Not Found Or Group Count is 0 Sample:

XML

<?xml version="1.0" encoding="UTF-8"?>
<results>
     <result>
          <status>-55</status>
          <campaign_name>Group-Api-Campaign-cf27252-5101</campaign_name>
          <group>Example</group>
     </result>
</results>

JSON

{"results":[{"status":"-55","campaign_name":"Group-Api-Campaign-cf27252-5101","group":"Example"}]}

Additional HTTP GET commands

Additional HTTP GET commands use following syntax:

Primary access point:

 https://api.nusasms.com/api/command

Currently, available commands are:
CREDITS – return your available account credits
DR – return the current status of message
output – Json, XML

Examples: Check available credits

https://api.nusasms.com/api/command?user=user&password=password&cmd=CREDITS&type=sms&output=json

API CALLBACK 

Another method for collecting Delivery Status / Message status is by registering URL Call Back API in menu Account Setting on your web app account https://app.nusasms.com.

CallBack API URL will call with HTTP GET with follwing values like this examples: {“ref_no”:”053380444905641291″,”status”:”D”,”sent_date”:”2017-09-25 17:49:05.0″,”err_code”:”0″}

HTTP Method Response

PYTHON SAMPLE CODE

import requests

url = "https://api.nusasms.com/api/v3/sendsms/plain"
username = 'username'
password = 'password'
payload = {
        "SMSText": "This is an example using Python.",
        "GSM": "628170003364",
        "output": "json"
}

try:
       response = requests.post(url, data=payload, auth=(username, password))
       print("RESPONSE: %s" % response.text)
except requests.exceptions.RequestException as e:
       print("ERROR: %s" % e)

PHP SAMPLE CODE

<?php

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'https://api.nusasms.com/api/v3/sendsms/plain',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => array(
        'user' => 'username',
        'password' => 'password',
        'SMSText' => 'This is an example code using PHP.',
        'GSM' => '6281572610701'
    )
));

$resp = curl_exec($curl);

if (!$resp) {
    die('Error: "' . curl_error($curl) . '" - Code: ' . curl_errno($curl));
} else {
    header('Content-type: text/xml'); /*if you want to output to be an xml*/
    echo $resp;
}
curl_close($curl);

?>

Java Sample Code

import import java.net.URL;
import java.net.URLConnection;
import java.net.URLEncoder;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import org.w3c.dom.Document;
public class sendSMS {
public static void main(String[] args) {
	try {
		String data = URLEncoder.encode("user", "UTF-8") + "=" +
			URLEncoder.encode("xxxxxxxx", "UTF-8");
		data += "&" + URLEncoder.encode("password", "UTF-8") + "=" +
			URLEncoder.encode("xxxxxxxx", "UTF-8");
		data += "&" + URLEncoder.encode("SMSText", "UTF-8") + "=" +
			URLEncoder.encode("Test from API NusaSMS by Frans", "UTF-8");
		data += "&" + URLEncoder.encode("GSM", "UTF-8") + "=" +
			URLEncoder.encode("628XXXXXXXXXX", "UTF-8");
	
		// Send data
		URL url = new URL("https://api.nusasms.com/api/v3/sendsms/plain");
		URLConnection conn = url.openConnection();
		conn.setDoOutput(true);
		OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
		wr.write(data);
		wr.flush();
	
		// Get the response
		DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
		DocumentBuilder builder = factory.newDocumentBuilder();
		Document doc = builder.parse(conn.getInputStream());
		TransformerFactory factory1 = TransformerFactory.newInstance();
		Transformer xform = factory1.newTransformer();
		xform.transform(new DOMSource(doc), new StreamResult(System.out));
	} catch (Exception e) {
		System.out.println(e.toString());

ORACLE PL/SQL Sample Code

set serveroutput on;
exec dbms_output.enable(1000000000);
set escape '\\'

DECLARE
  req   UTL_HTTP.REQ;
  resp  UTL_HTTP.RESP;
  value VARCHAR2(1024);  -- URL to post to
  v_url VARCHAR2(200) := 'https://api.nusasms.com/api/v3/sendsms/plain';
  -- Post Parameters
  v_param VARCHAR2(500) := 'user=user_api\\&password=password_api\\&GSM=6285100803380\\&SMSText=Contoh+Pesan+SMS';
  v_param_length NUMBER := length(v_param);
BEGIN
  -- Set up proxy servers if required
  --  UTL_HTTP.SET_PROXY('proxy.my-company.com', 'corp.my-company.com');
  req := UTL_HTTP.BEGIN_REQUEST (url=> v_url, method => 'POST');
  --  UTL_HTTP.SET_HEADER(req, 'User-Agent', 'Mozilla/4.0');
  UTL_HTTP.SET_HEADER (r      =>  req,
                       name   =>  'Content-Type',
                       value  =>  'application/x-www-form-urlencoded');
  UTL_HTTP.SET_HEADER (r      =>   req,
                       name   =>   'Content-Length',
                       value  =>   v_param_length);
  UTL_HTTP.WRITE_TEXT (r      =>   req,
                       data   =>   v_param);  resp := UTL_HTTP.GET_RESPONSE(req);
  LOOP
    UTL_HTTP.READ_LINE(resp, value, TRUE);
    DBMS_OUTPUT.PUT_LINE(value);
  END LOOP;
  UTL_HTTP.END_RESPONSE(resp);
EXCEPTION
  WHEN UTL_HTTP.END_OF_BODY THEN
    UTL_HTTP.END_RESPONSE(resp);
END;
/

Characters per SMS

• Using GSM7Bit encoding, the maximum message length is 160 characters/SMS for single SMS and 153 characters/SMS for multiple SMS’s. (Latin character as in English Language keypad)
• GSM7Bit extended characters will consume 2 spaces in the SMS, these characters are

^ \\ [ ~ ] | € newline

• Using Unicode encoding, the maximum message length is 70 characters/SMS for single SMS and 67 characters/SMS for multiple SMS’s. (Unicode character like character in Chinese, Korea, Arabian, Japan language)
• Reference: https://en.wikipedia.org/wiki/GSM_03.38