logo-long-43.png login-logo.png

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

AUTHENTICATION user Client username for NusaSMS system login
password Client password for NusaSMS system login
MESSAGE SMSText Message body
RECIPIENTS GSM Message destination address, must be international format without leading 0 or +
Example: 6281123456789
COMMAND output

Desired output, support values are (optional):

xml: values are formatted as xml

json: values are formatted as json

If no output parameter is specified, xml formatting will be used

URL Query String Parameters

Parameter Description
user Required, username yang digunakan untuk mengakses API, bukan user WEB
password Required, password user API
SMSText Required, message TEXT (160 characters)
GSM Required, recipient GSM number in international format (eq. 6285100101698)
unicode Optional
True=Unicode
otp Optional
Y=OTP message

Examples: Send plain SMS (Output XML)

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"}]}
  1. 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"}]}
  1. 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

Status Value Description
ALL_RECIPIENTS_PROCESSED 0 Request was successful (all recipients)
SEND_ERROR -1 Error in processing the request
NOT_ENOUGH_CREDITS -2 Not enough credits on a specific account
NETWORK_NOTCOVERED -3 Targeted network is not covered on specific account
INVALID_USER_OR_PASS -5 Username or password is invalid
MISSING_DESTINATION_ADDRESS -6 Destination address is missing in the request
BALANCE_EXPIRED -7 Balance has expired
NO_ROUTE -9 Routing not found for specific operator
REJECTED -10 OTP messages that do not use an OTP route will be REJECTED
INVALID_DESTINATION_ADDRESS -11 Number is not recognized by NusaSMS platform
MISSING_MESSAGE -12 Message is missing in the request
INVALID_DESTINATION_ADDRESS -13 Number is not recognized by NusaSMS platform
SYNTAX_ERROR -22 Incorrect XML format, caused by syntax error
ERROR_PROCESSING -23 General error, reasons may vary
COMMUNICATION_ERROR -26 General API error, reasons may vary
INVALID_SENDDATETIME -27 Invalid scheduling parametar
INVALID_DELIVERY_REPORT_PUSH_URL -28 Invalid PushURL in the request
INVALID_CLIENT_APPID -30 Invalid APPID in the request
DUPLICATE_MESSAGEID -33 Duplicated MessageID in the request
SENDER_NOT_ALLOWED -34 Sender name is not allowed
IP_ADDRESS_FORBIDDEN -40 Client IP Address Not In White List
SPAM_PATTERN -77 More than 10 same message send to the same recipeints in 1 day
LIMIT REACHED FOR DESTINATION NUMBER -78 Sending messages to the same number has reached the limit in 24 hours
REJECTED ROUTE -88 Operator Rejected The Request
GENERAL_ERROR -99 Error in processing request, reasons may vary

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)

 

 

 

 

nusasms api v.1.0.0

 

 

 

 

 

Push SMS: Call Back API Provided by Client

Client should provide URL of Callback API called by NusaSMS to forward all incoming messages. URL is registered in NusaSMS Web App (https://app.nusasms.com), using your account. (If you don’t have any account yet, you can create one on https://nusasms.com/freetrial ). From Menu SMS Inbox > Activity, Create an activity with push inbox type options as shown in :

API Call:

Method: POST

Parameter POST:

  • id: id sms
  • originator: nomor telepon pengirim
  • msg: isi pesan sms
  • receive_date: tanggal sms (YYYY-mm-dd H:i:s)

 

PHP SAMPLE CODE

<?php

$id = $_POST["id"];
$gateway_no = $_POST["gateway_number"];
$sender = $_POST["originator"];
$receive_date = $_POST["receive_date"];
$message = $_POST["msg"];

# you can write your code here, for example if you want to write the data to a file;

$myfile = fopen("inbox.txt", "w") or die("Unable to open file!");
fwrite($myfile, "ID: " . $id . PHP_EOL);
fwrite($myfile, "Gateway No: " . $gateway_no . PHP_EOL);
fwrite($mufile, "Sender: " . $sender . PHP_EOL);
fwrite($myfile, "Receive Date: " . $receive_date . PHP_EOL);
fwrite($myfile, "Message: " . $message . PHP_EOL);
fclose($myfile);

?>
logo-long-43.png login-logo.png

 

HTTP Plain

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

Primary access point:

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

 

New Documentation WA API here : New WA API

WA API Parameter specifications

AUTHENTICATION user Client username for NusaSMS system login
password Client password for NusaSMS system login
MESSAGE SMSText Message body
RECIPIENTS GSM Message destination address, must be international format without leading 0 or +

Example: 6281123456789

COMMAND output Desired output, support values are (optional):

xml: values are formatted as xml

json: values are formatted as json

If no output parameter is specified, xml formatting will be used

URL Query String Parameters

Parameter Description
username Username
password Password
GSM Recipient GSM number in international format, eq. 6285100101698)
text text message to send (max 1000 chars)

Examples: Send plain WA Text (Output XML)

https://api.nusasms.com/api/v3/sendwa/plain?username=user&password=password&GSM=6285100803380&text=testing+wa+api

Examples:

1.Send plain WA Text (Output JSON)

https://api.nusasms.com/api/v3/sendwa/plain?username=user&password=password&GSM=6285100803380&text=testing+wa+api&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"}]}
  1. 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"}]}
  1. 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"}]}

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=wa&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, Example ini PHP code:

<?php
$data=json_encode($_REQUEST);
file_put_contents("wa_dlr.dat",$data,FILE_APPEND);

result in wa_dlr.dat:
{"ref_no":"053380444905641291","status":"D","sent_date":"2017-09-25 17:49:05.0","err_code":"0"}

HTTP Method Response

Status Value Description
ALL_RECIPIENTS_PROCESSED 0 Request was successful (all recipients)
SEND_ERROR -1 Error in processing the request
NOT_ENOUGH_CREDITS -2 Not enough credits on a specific account
NETWORK_NOTCOVERED -3 Targeted network is not covered on specific account
INVALID_USER_OR_PASS -5 Username or password is invalid
MISSING_DESTINATION_ADDRESS -6 Destination address is missing in the request
BALANCE_EXPIRED -7 Balance has expired
REJECTED -10 OTP messages that do not use an OTP route will be REJECTED
INVALID_DESTINATION_ADDRESS -11 Number is not recognized by NusaSMS platform
MISSING_MESSAGE -12 Message is missing in the request
INVALID_DESTINATION_ADDRESS -13 Number is not recognized by NusaSMS platform
SYNTAX_ERROR -22 Incorrect XML format, caused by syntax error
ERROR_PROCESSING -23 General error, reasons may vary
COMMUNICATION_ERROR -26 General API error, reasons may vary
INVALID_SENDDATETIME -27 Invalid scheduling parametar
INVALID_DELIVERY_REPORT_PUSH_URL -28 Invalid PushURL in the request
INVALID_CLIENT_APPID -30 Invalid APPID in the request
DUPLICATE_MESSAGEID -33 Duplicated MessageID in the request
SENDER_NOT_ALLOWED -34 Sender name is not allowed
IP_ADDRESS_FORBIDDEN -40 Client IP Address Not In White List
SPAM_PATTERN -77 More than 10 same message send to the same recipeints in 1 day
LIMIT REACHED FOR DESTINATION NUMBER -78 Sending messages to the same number has reached the limit in 24 hours
REJECTED ROUTE -88 Operator Rejected The Request
GENERAL_ERROR -99 Error in processing request, reasons may vary

 


PHP SAMPLE CODE

<?php

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'https://api.nusasms.com/api/v3/sendwa/plain',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => array(
        'username' => 'username',
        'password' => 'password',
        'text' => '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("username", "UTF-8") + "=" +
			URLEncoder.encode("xxxxxxxx", "UTF-8");
		data += "&" + URLEncoder.encode("password", "UTF-8") + "=" +
			URLEncoder.encode("xxxxxxxx", "UTF-8");
		data += "&" + URLEncoder.encode("text", "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/sendwa/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/sendwa/plain';
  -- Post Parameters
  v_param VARCHAR2(500) := 'username=user_api\\&password=password_api\\&GSM=6285100803380\\&text=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;
/

 

 

 

 

 

nusasms api v.1.0.0

 

 

 

 

 

id_IDIndonesian