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:

 http://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 Username
password Password
sender Message sender name

Alphanumeric sender: max. length 11 characters

Numeric sender: max. length 14 characters

SMSText Message text (160 characters)
GSM Recipient GSM number in international format, eq. 6285100101698)
encoding U=Unicode
7= GSM7Bit

Examples: Send plain SMS (Output XML)

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

Examples:

 

1.Send plain SMS (Output JSON)

http://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"}]}

 Send SMS Using Group Recipients

http://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:

 http://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

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

Examples: Check message status

http://api.nusasms.com/api/command?user=user&password=password&cmd=DR&ref_no=766387461827XXX

Another method for collecting Delivery Status / Message status is by registering URL Call Back API in menu Account Setting on your web app account http://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
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
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 => 'http://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("http://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) := 'http://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 (http://app.nusasms.com), using your account. (If you don’t have any account yet, you can create one on http://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)

 

Share This: