API-N Message Submission

  API-N

API-N provides a direct connection to a user’s account. It requires the Username and Password of the user to connect and execute all the possible commands.

http://orgds.org/api?username=XXXXXXXX&password=XXXXXXXX&cmd=send&message=MESSAGE&recipient=23480xxxxxxxx,23470xxxxxxxx,23490xxxxxxxx&sender=SenderID&type=0&route=1&display=plain

To send a message using OrgDS API-N, the required parameters that must be submitted to the Base URL are cmd (whose value is equal to send) username, password, message, recipients, and sender.

Parameters and Descriptions

Schedule Message

To schedule a message for delivery in the future, add schedule variable to the HTTP request and set its value to a datetime in the format YYYY-MM-DD HH:MM

http://orgds.org/api?username=XXXXXXXX&password=XXXXXXXX&cmd=send&message=MESSAGE&recipient=23480xxxxxxxx,23470xxxxxxxx,23490xxxxxxxx&sender=SENDERID&type=0&route=1&schedule=2019-06-20 22:10

Sample API-N Message Submission PHP Code

<?php
//cURL function that sends either HTTP POST or HTTP GET request
function postData($baseurl, $dataArray = array(),$httpmethod = 'post') {
	  $buildData = http_build_query($dataArray);
      $ch = curl_init();
      
      if (strtolower($httpmethod)=='get') {
	      $geturl = $baseurl.'?'.$buildData;
	      curl_setopt($ch, CURLOPT_URL, $geturl);
      }
      else{
      	  curl_setopt($ch, CURLOPT_URL, $baseurl);
      	  // Enable the post response
	      curl_setopt($ch, CURLOPT_POST, true);
	      // The data to transfer with the response
	      curl_setopt($ch, CURLOPT_POSTFIELDS, $buildData);
      }
      
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      $response = curl_exec($ch);
      curl_close($ch);
      return $response;
}


//Send a message via API-N
//receive form data
if(isset($_REQUEST['message'])) {
	$username = 'username';
	$password = 'password';
	$cmd = "send";
	$message = "This is a sample message content.";
	$recipient = "234803xxxxxxx,44702xxxxxxxx,01703xxxxxxxx,234903xxxxxxx";
	$sender = "SenderID";
	$type = 0;
	$route = 2;
	$display = "json";//maybe plain or json or xml
	
	//set API base URL
	$baseurl = "https://orgds.org/api";
	
	//convert message data to array
	$dataArray = array(
                  'cmd' => $cmd,
                  'username' => $username,
                  'password' => $password,
                  'recipient' => $recipient,
                  'sender' => $sender,
                  'message' => $message,
                  'type' => $type,
                  'route' => $route,
                  'display' => $display
      );
      
	//process message sending
	// $httpmethod value maybe either post or get
	
	$reply = postData($baseurl, $dataArray,$httpmethod = 'post');
	/*
	    * $reply stores the response gotten from the API
        * The response format is determined by the value supplied to the display variable, which maybe plain or json or xml. 
        * The default response format is plain text.
        * See the response codes and formats in the documentation
     */
}

?>

Response Formats

After a message has been successfully sent, a reply will be returned based on the given display format. Available response formats are explained below.

 

Plain Response Format

600: Message sent/scheduled successfully 

Plain text response shows only a response code and its description. Other formats described below show detailed information about the message. See possible response messages and error codes here.

 

JSON Response Format

{
	"responseCode":600,
	"info":"Message sent\/scheduled successfully",
	"smsPages":1,
	"recipients":"234802xxxxxxx,234903xxxxxxx,234705xxxxxxx",
	"msgRoute":"BasicPlus",
	"msgType":"Plain",
	"basicNumbers":"234802xxxxxxx",
	"corporateNumbers":"234903xxxxxxx,234705xxxxxxx",
	"unitsBefore":"61.65",
	"unitsUsed":"4.70",
	"creditBalance":56.95,
	"messageId":"c73bb503634c1475b0c04813aca62bcd"
}

 

XML Response Format

<message>
    <responseCode>600</responseCode>
    <info>Message sent/scheduled successfully</info>
    <smsPages>1</smsPages>
    <recipients>234802xxxxxxx,234903xxxxxxx,234705xxxxxxx</recipients>
    <msgRoute>BasicPlus</msgRoute>
    <msgType>Plain</msgType>
    <basicNumbers>234802xxxxxxx</basicNumbers>
    <corporateNumbers>234903xxxxxxx,234705xxxxxxx</corporateNumbers>
    <unitsBefore>61.65</unitsBefore>
    <unitsUsed>4.70</unitsUsed>
    <creditBalance>56.95</creditBalance>
    <messageId>c73bb503634c1475b0c04813aca62bcd</messageId>
</message>