Unified Communications API's

1. - Submit Messages

1.2 - GET Message Submission API

http://<server>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S

All parameters are explained below. Note that all the parameters, especially message and URL should be URL-UTF-8 encoded

N°	Parameter	Description
1	username	The username of the HTTP account.
2	password	The password of the HTTP account.
3	type	It indicates the type of message. Values for "type" include: 0       : Plain text (GSM 3.38 Character encoding) 1       : Flash (GSM 3.38 Character encoding) 2       : Unicode 3       : Reserved 4       : WAP Push 5       : Plain text (ISO-8859-1 Character encoding) 6       : Unicode Flash 7       : Flash (ISO-8859-1 Character encoding)
4	dlr	Indicates whether the client wants delivery report for this message. The values for "dlr" include: 0 : No delivery report required 1 : Delivery report required
5	destination	Mobile number to which the message is to be sent (may or may not include a plus [+] sign). Multiple mobile numbers need to be separated by a comma (,) (the comma should be URL encoded).
6	source	The source address that should appear in the message. ·        Max Length of 18 if numeric. ·        Max Length of 11 if alphanumeric. Note: You need to URL encode the plus sign. The SMSC may enforce additional restrictions on this field.
7	message	The message to be sent. It can be used for 'long' messages, that is, messages longer than 160 characters for plain text, 140 for flash, and 280 for Unicode. For concatenated (long) messages every 153 characters are counted as one message for plain text and 268 characters for Unicode. The system uses the rest of the characters for packing extra information for reassembling the message on the mobile phone.

1.3 - Exemple Request

1.3.1 - PHP - cURL

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S&ip=x',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

1.3.2 - PHP – http_Request2

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

1.3.3 - PHP – pecl_http

<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S');
$request->setRequestMethod('GET');
$request->setOptions(array());

$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

1.3.4 - curl

curl --location --request GET 'http://<server>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S' 

1.3.5 - Python (Requests)

import requests

url = "http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

1.3.6 - Python (http.client)

import http.client
conn = http.client.HTTPSConnection("<host>:port")
payload = ''
headers = {}
conn.request("GET", "/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

1.3.7 JavaScript - jQuery

var settings = {
  "url": "http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

1.4 - Response

Error codes are explained in the following table.

N°	Error Code	Description
1	1701	Success, Message Submitted Successfully. In this case you will receive the response 1701|<CELL_NO>|<MESSAGE ID>. The message Id can then be used later to map the delivery reports to this message
2	1702	Invalid URL. This means that one of the parameters was not provided or left blank.
3	1703	Invalid value in username or password field.
4	1704	Invalid value in type field.
5	1705	Invalid message.
6	1706	Invalid destination.
7	1707	Invalid source (Sender).
8	1708	Invalid value for dlr parameter.
9	1709	User validation failed.
10	1710	Internal error.
11	1725	Insufficient credit.
12	1715	Response timeout.
13	1732	DND reject.
14	1028	Spam message
15	1041	Duplicate Message.
16	1042	Explicit DND Destination
17	1033	Message Template Mismatch.
18	69	Internal Error
19	8	Internal Error
20	16	IP Blacklisted.
21	18	Non Whitelisted User IP.

Note:

• Along with the above errors codes, standard SMPP v3.4 error codes may also be returned where applicable.
• Apart from error code 1709, please do NOT retry re-sending the message for any other error code (including SMPP v3.4 Error codes).
• For error code 1715, do NOT re-submit the same message again. Body API Reply Format

<Error_Code>|<destination>|<message_id>

2. - Submit Scheduler Messages

2.1 - GET SMS Scheduler API

http://<server>:port/bulksms/schedulemsg?username=X&password=X&message=X&type=X&dlr=X&source=X&destination=X&date=X&time=X&gmt=X

All parameters are explained below. Note that all the parameters, especially message and URL should be URL-UTF-8 encoded.

N°	Parameter	Description
1	username	The username of the HTTP account.
2	password	The password of the HTTP account.
3	type	It indicates the type of message. Values for "type" include: 0 : Plain text (GSM 3.38 Character encoding) 1 : Flash (GSM 3.38 Character encoding) 2: Unicode 3: Reserved 4: WAP Push 5 : Plain text (ISO-8859-1 Character encoding) 6 : Unicode Flash 7 : Flash (ISO-8859-1 Character encoding)
4	dlr	Indicates whether the client wants delivery report for this message. The values for "dlr" include: 0 : No delivery report required 1 : Delivery report required
5	destination	Mobile number to which the message is to be sent (may or may not include a plus [+] sign). Multiple mobile numbers need to be separated by a comma (,) (the comma should be URL encoded).
6	source	The source address that should appear in the message. ·        Max Length of 18 if numeric. ·        Max Length of 11 if alphanumeric. Note: You need to URL encode the plus sign. The SMSC may enforce additional restrictions on this field.
7	message	The message to be sent. It can be used for 'long' messages, that is, messages longer than 160 characters for plain text, 140 for flash, and 280 for Unicode. For concatenated (long) messages every 153 characters are counted as one message for plain text and 268 characters for Unicode. The system uses the rest of the characters for packing extra information for reassembling the message on the mobile phone.
8	date	Scheduled date for the message. Date needs to be in the following format : MM/DD/YYYY MM : Examples of month : 01,12 DD : Examples of date : 01,18,30 YYYY : Example of year : 2018 Example of scheduledate : 03/03/2018
9	time	Scheduled time for the message. Time needs to be in the following format : hh:mm am/pm hh : Hours range from 00 to 12 mm : Examples of minutes : 00, 15,30 am/pm : one of (am) or (pm) Example of scheduletime: 03:45 am OR 11:51 pm
10	gmt	GMT +hh:mm OR GMT -hh:mm OR +hh:mm OR -hh:mm hh : Hours range from 0 to 12 mm : Examples of minutes: 00 or 30 Example : GMT +1:30 OR -10:00

2.2 - Exemple Request

2.2.1 - PHP - cURL

 <?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'http://<server>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S&date=X&time=X&gmt=X',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

2.2.2 - PHP – http_Request2

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S&date=X&time=X&gmt=X');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

2.2.3 - PHP – pecl_http

<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S&date=X&time=X&gmt=X');
$request->setRequestMethod('GET');
$request->setOptions(array());

$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

2.2.4 - curl

curl --location --request GET 'http://<server>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S&date=X&time=X&gmt=X'

2.2.5 - Python - Requests

import requests

url = "http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S&date=X&time=X&gmt=X"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

2.2.6 - Python – http.client

import http.client

conn = http.client.HTTPSConnection("<host>:port")
payload = ''
headers = {}
conn.request("GET", "/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S&date=X&time=X&gmt=X", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

2.2.7 - JavaScript - jQuery

var settings = {
  "url": "http://<host>:port/bulksms/bulksms?username=X&password=Y&type=Y&dlr=Z&destination=Q&source=R&message=S&date=X&time=X&gmt=X",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

2.4 - Response

Error codes are explained in the following table.

N°	Error Code	Description
1	1701	Success, Message Submitted Successfully. In this case you will receive the response 1701|<CELL_NO>|<MESSAGE ID>. The message Id can then be used later to map the delivery reports to this message
2	1702	Invalid URL. This means that one of the parameters was not provided or left blank.
3	1703	Invalid value in username or password field.
4	1704	Invalid value in type field.
5	1705	Invalid message.
6	1706	Invalid destination.
7	1707	Invalid source (Sender).
8	1708	Invalid value for dlr parameter.
9	1709	User validation failed.
10	1710	Internal error.
11	1725	Insufficient credit.
12	1715	Response timeout.
13	1732	DND reject.
14	1028	Spam message
15	1041	Duplicate Message.
16	1042	Explicit DND Destination
17	1033	Message Template Mismatch.
18	69	Internal Error
19	8	Internal Error
20	16	IP Blacklisted.
21	18	Non Whitelisted User IP.

Note:

•  Along with the above errors codes, standard SMPP v3.4 error codes may also be returned where applicable.
•  Apart from error code 1709, please do NOT retry re-sending the message for any other error code (including SMPP v3.4 Error codes).
•  For error code 1715, do NOT re-submit the same message again.

Body API Reply Format

<Error_Code>|<destination>|<message_id>